ac-php

A GNU Emacs auto completion source for the PHP.

Table of Contents

• About ac-php
• Provide Features
  • PHPDoc annotations
  • Type hints
• Install
  • Using MELPA
• Usage
  • Commands
  • auto-complete
  • company-mode
  • Spacemacs
  • Working with tags
  • Using configuration file
  • Rebuilding tags
• FAQ
• License

About ac-php

This repository contains:

• ac-php-core, the core library of the ac-php package
• ac-php, auto completion source for PHP to use with auto-complete
• company-php, a company-mode back-end for PHP
• helm-ac-php-apropros, an apropos functionality using the ac-php index and helm as interface

Provide Features

The PHP code completion and the jump to definition/declaration/inclusion-file provided by phpctags.

• Support of auto-complete, company-mode and helm (an apropos functionality)
• Auto Completion for built-in extensions
  • PDO
  • SPL
  • mysqli
  • SQLite3
  • ...
• Auto Completion for PECL extensions
  • Redis
  • Imagick
  • Swoole
  • Memcache
  • ...
• Auto Completion for built-in classes
  • SplFileInfo
  • DOMDocument
  • SimpleXMLElement
  • ...
• Auto Completion for user defined classes
• Auto Completion for built-in functions
• Support of annotations and type hints
• Currently ships with Spacemacs

For more see screenshots page.

PHPDoc annotations

ac-php supports PHPDoc annotations. Thus auto completion should work for:

Property annotations

/**
 * @var \Acme\Services\HelloService
 */
public $hello;

Invisible (magic) members annotations

/**
 * @property \Acme\Services\HelloService $hello
 */
class Test
{
    // ...
}

Return type annotations

/**
 * @return \Acme\Services\HelloService
 */
public function get_v1()

Invisible (magic) methods annotations

/**
 * @method \Acme\Services\HelloService hello()
 */
class Test
{
    // ...
}

Variable annotations

/** @var \Acme\Services\HelloService $hello */
$hello = hello();

Note: if a function or a class member has no defined return value then you need to define it using annotation.

Type hints

In addition, ac-php supports return / parameter type hints. Thus you'll get additional auto completion support for the following cases:

Parameter type hints

use Acme\Services\HelloService;

public function hello(HelloService $service)
{
    // ...
}

PHP 7 return type hints

public function hello(): \Acme\Services\HelloService
{
    // ...
}

Installation

Known to work with GNU Emacs 24.4 and later. ac-php may work with older versions of GNU Emacs, or with other flavors of GNU Emacs (e.g. XEmacs) but this is not guaranteed. Bug reports for problems related to using ac-php with older versions of Emacs will most like not be addressed.

Prerequisite packages are:

• Common
  • GNU Emacs >= 24.4
  • PHP CLI
  • php-mode
• ac-php-core.el
  • s
  • f
  • popup
  • dash
  • xcscope
  • scope (optional)
• ac-php.el
  • auto-complete
  • yasnippet
• helm-ac-php-apropros.el
  • helm
• company-php.el
  • company

Using MELPA

The best way of installing ac-php, at least for GNU Emacs 24, is to use the packaging system. Add MELPA or MELPA Stable to the list of repositories to access this mode. For those who want only formal, tagged releases use MELPA Stable:

(require 'package)
(add-to-list 'package-archives
             '("melpa-stable" . "https://stable.melpa.org/packages/") t)
(package-initialize)

For those who want rolling releases as they happen use MELPA:

(require 'package)
(add-to-list 'package-archives
             '("melpa" . "https://melpa.org/packages/") t)
(package-initialize)

and then use M-x package-refresh-contents and M-x package-list-packages to get to the package listing and install ac-php from there. MELPA tracks this Git repository and updates relatively soon after each commit or formal release. For more detail on setting up see MELPA Getting Started.

You can install ac-php manually by adding following to your init file:

(unless (package-installed-p 'ac-php)
    (package-refresh-contents)
    (package-install 'ac-php))

Usage

Commands

auto-complete

1. Add hook as follows:

(require 'php-mode)

(add-hook 'php-mode-hook
          '(lambda ()
             ;; Enable auto-complete-mode
             (auto-complete-mode t)

             (require 'ac-php)
             (setq ac-sources '(ac-source-php))

             ;; As an example (optional)
             (yas-global-mode 1)

             ;; Enable ElDoc support (optional)
             (ac-php-core-eldoc-setup)

             ;; Jump to definition (optional)
             (define-key php-mode-map (kbd "M-]")
               'ac-php-find-symbol-at-point)

             ;; Return back (optional)
             (define-key php-mode-map (kbd "M-[")
               'ac-php-location-stack-back)))

2. Create the configuration file .ac-php-conf.json in the project root:

$ cd /project/to/poject/root
$ touch .ac-php-conf.json

And use M-x company-complete to complete.

company-mode

1. Add hook as follows:

(require 'php-mode)

(add-hook 'php-mode-hook
          '(lambda ()
             ;; Enable company-mode
             (company-mode t)
             (require 'company-php)

             ;; Enable ElDoc support (optional)
             (ac-php-core-eldoc-setup)

             (set (make-local-variable 'company-backends)
                  '((company-ac-php-backend company-dabbrev-code)
                    company-capf company-files))

             ;; Jump to definition (optional)
             (define-key php-mode-map (kbd "M-]")
               'ac-php-find-symbol-at-point)

             ;; Return back (optional)
             (define-key php-mode-map (kbd "M-[")
               'ac-php-location-stack-back)))

2. Create the configuration file .ac-php-conf.json in the project root:

$ cd /project/to/poject/root
$ touch .ac-php-conf.json

And use M-x company-complete to complete.

Spacemacs

To use ac-php with Spacemacs please refer to: https://github.com/syl20bnr/spacemacs/tree/develop/layers/%2Blang/php

Working with tags

ac-php uses its own tags format. By default all tags located at ~/.ac-php/tags-<project-directory>. For example, if the real path of the project is /home/jim/ac-php/phptest, then tags will be placed at ~/.ac-php/tags-home-jim-ac-php-phptest/.

And you can redefine the base path (~/.ac-php) using ac-php-tags-path variable.

The tags directory structure looks like this:

$ tree ~/.ac-php/tags-home-jim-ac-php-phptest
tags-home-jim-ac-php-phptest/
├── cache-files.json
├── tags-data-cache2.el
├── tags-data.el
└── tags_dir_jim
    ├── a.el
    ├── dir1-sss.el
    ├── testa.el
    ├── testb.el
    └── testc.el
1 directory, 8 files

Using configuration file

Because of the way that the ac-php package works, there are a couple of simple initialization tasks which must occur to get the completion working as it should. On any new project make sure to perform the following initialization tasks:

1. Run the following

   cd /root/of/project
   touch .ac-php-conf.json
   

2. Inside of Emacs run: M-x ac-php-remake-tags

The .ac-php-conf.json file is required to enable auto-completion. When you run ac-php-remake-tags and your .ac-php-conf.json file is empty the default configuration will be used and inserted in the file.

If your project contains the following files at the root folder:

1. .projectile
2. vendor/autoload.php

the necessary configuration file (.ac-php-conf.json) will be created automatically if it does not exist. Its contents will be similar to:

{
  "filter": {
    "php-file-ext-list": [
      "php"
    ],
    "php-path-list": [
      "."
    ],
    "php-path-list-without-subdir": []
  }
}

• php-file-ext-list: file extern name list
• php-path-list: base path for recursive file search to collect tags
• php-path-list-without-subdir: path for non-recursive file search to collect tags

for example:

├── dir1
│   ├── 1.php
│   └── dir11
│       └── 11.php
├── dir2
│   └── 2.php
└── dir3
    ├── 3.php
    ├── dir31
    │   └── 31.php
    ├── dir32
    │   └── 32.php
    └── dir33
        └── 33.php

{
  "filter": {
    "php-file-ext-list": [
      "php"
    ],
    "php-path-list": [
      "./dir1",
      "./dir2",
      "./dir3/dir32/"
    ],
    "php-path-list-without-subdir": [
      "./dir3"
     ]
  }
}

filter result is:

├── dir1
│   ├── 1.php
│   └── dir11
│       └── 11.php
├── dir2
│   └── 2.php
└── dir3
    ├── 3.php
    ├── dir32
    │   └── 32.php

31.php 33.php will be ignored during tag generation;

Laravel example:

{
  "filter": {
    "php-file-ext-list": [
      "php"
    ],
    "php-path-list": [
        "./app",
        "./database",
        "./vendor/laravel/framework/src/Illuminate"
    ],
    "php-path-list-without-subdir": []
  }
}

You can also add the standard php library with phpstorm stubs. Assuming you cloned this repo into /usr/local/src/phpstorm-stubs you base configuration will be:

{
  "filter": {
    "php-file-ext-list": [
      "php"
    ],
    "php-path-list": [
        "/usr/local/src/phpstorm-stubs"
    ],
    "php-path-list-without-subdir": []
  }
}

Rebuilding tags

If source has been changed, you may need run ac-php-remake-tags to remake tags.

ac-php internally uses phpctags, so its operability depends on the correct syntax you use in the project. If something goes wrong with one of your files, you can find all errors in the *Messages* buffer. For example:

phpctags[/home/jim/phptest/testa.php] ERROR:PHPParser: Unexpected token '}' on line 11 -

In this case you'll need to fix an error in testa.php and re run ac-php-remake-tags.

Note: You shouldn't download phpctags, ac-php already ships with its own modified version.

If you see something like this:

ac-php: Unable to resolve project root

This means you have to create the .ac-php-conf.json file in the project root:

$ touch /path/to/the/project/.ac-php-conf.json

FAQ

• Q: Something went wrong. It seems I followed all the instructions, but auto completion stopped working
• A: Run M-x ac-php-remake-tags-all

• Q: How I can create a reproducible test to create an issue?
• A: Please use this issue as an example

License

ac-php is open source software licensed under the GNU General Public Licence version 3 .