Getting better tags

Replacing your system default ctags

If you happen to have a ctags shipped with your operating system or with your development environment, chances are its a really outdated version of the old exuberant-ctags project last release (5.8). This version does not have support for new features of current PHP releases like namespaces, traits or old features like interfaces.

Without support for these in the tag files the plugins accuracy and general usefulness greatly reduced if your code base use these features. Fortunately you have multiple options to remedy this:

• universal ctags
  Aka ctags.io project. This project aims to revive the old exuberant ctags project and have a good php parser. For installing instructions, please see: https://github.com/universal-ctags/ctags#how-to-build-and-install

  If you are going to use this generator, the following flags are known to be working well:

  ctags -R --fields=+aimlS --languages=php --output-format=e-ctags
  

• phpctags
  This generator should work out of the box, written in php and supports new features pretty well.

• old "patched ctags"
  Patches created before the ctags.io project for the old exuberant ctags by created by @b4n (Many kudos @b4n), have almost all the same features as ctags.io have but without the namespace \\ issues. For installation instructions please read on.

The patched ctags sources can be found at the /misc/ctags-5.8_better_php_parser.tar.gz.

Windows binary

There's a pre-build binary built from the patched source of ctags inside /bin directory.

Compiling from source

Software you will need

1. gcc
2. make

On debian based systems the package build-essential will install what you need. On Fedora install @development-tools. If you are on windows, you can use the MinGW project that will provide the necessary binaries for the build.

Building ctags from source

1. Download and extract the sources:

    wget "https://github.com/shawncplus/phpcomplete.vim/raw/master/misc/ctags-5.8_better_php_parser.tar.gz" -O ctags-5.8_better_php_parser.tar.gz
    tar xvf ctags-5.8_better_php_parser.tar.gz
    cd ctags
   

   OR

    wget https://github.com/b4n/ctags/archive/better-php-parser.zip
    unzip better-php-parser.zip
    cd ctags-better-php-parser
   

2. Compile ctags

    autoreconf -fi
    ./configure
    make
   

3. Install ctags:

    sudo make install
   

   or if you don't have sudo set up

    su -c 'make install'
   

   By default, ctags will install under /usr/local/ (at least on unix like systems).

4. Check your installed ctags Run ctags --version and if you see Exuberant Ctags Development you are probably running your newly built ctags binary.

Homebrew formula for OSX users

OSX users can use homebrew with a custom formula to build and install the patched ctags. Use the following commands in terminal.

curl https://raw.githubusercontent.com/shawncplus/phpcomplete.vim/master/misc/ctags-better-php.rb > /usr/local/Library/Formula/ctags-better-php.rb
brew install ctags-better-php

This formula will build the patched sources from the source bundle under misc/, or you can use @b4n's branch directly, just extract the zipped version You might need to write out the /usr/local/bin/ctags depending on your $PATH when invoking the newly built binary. If homebrew complains that there's already a "ctags" (built previously from the original ctags formula) follow the instructions and run brew link --overwrite ctags-better-php to replace it.

Using patched ctags

With the newly patched ctags binary, you can use a bunch of newly supported flags to add extra fields to your tags. You can enable these when running ctags like this:

cd /path/to/your/projects/root
ctags -R --fields=+laimS --languages=php

• -a
  Access (or export) of class members; Adds the access field like: access: public

• -i
  Inheritance information; Adds the inherits field like: inherits:RuntimeException,ExceptionInterface

• -m
  Implementation information; Adds the implementation field like: implementation:abstract

• -S
  Signature of routine; Adds the signature field like: signature:($a, $b)

These extra fields will show up in the tag stack like this:

6 F   f    handle            vendor/monolog/monolog/src/Monolog/Handler/NullHandler.php
             class:Monolog\Handler::NullHandler access:public signature:(array $record)
             public function handle(array $record)