Skip to content
master
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

ac-php

Build Status

A GNU Emacs auto completion source for the PHP.


Table of Contents

About ac-php

This repository contains:

  • ac-php-core, the core library of the ac-php package MELPA MELPA Stable
  • ac-php, auto completion source for PHP to use with auto-complete MELPA MELPA Stable
  • company-php, a company-mode back-end for PHP MELPA MELPA Stable
  • 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:

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

Command Description
ac-php-remake-tags Run this command to update tags if source has been changed
ac-php-remake-tags-all Run this command if you find an error
ac-php-find-symbol-at-point Jump to definition
ac-php-location-stack-back Return back
ac-php-show-tip Show definition at point
ac-php-toggle-debug Toggle debug mode
helm-ac-php-apropos Search through all the definitions of a project with helm

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)))
  1. 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)))
  1. 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 .

You can’t perform that action at this time.