Vim for PHP development

Vim is a text-based editor which works as an antithesis to Integrated Development Environments (IDEs). It can be used proficiently to develop PHP applications, which have very few infrastructure requirements in respect to other platforms and less IDE magic to rely on for their configuration.

The discussion that follows is based on the Unix version of Vim (Linux, Mac OS X), but it applies in almost all its parts to the packages for Windows platforms, too. I also assume you already have a little knowledge of Vim, in particular about the difference between normal mode and insert mode. Basically, in insert mode you enter real text, while in normal mode your keystrokes are interpreted as commands instead of being written in the text flow. You can enter insert mode by pressing i or a from normal mode and go back to normal mode by pressing Esc.

The vimtutor binary is usually included with the package, and explains the basic commands better than this article, by forcing an hands-on approach.

Vim vs. IDEs

Text-based editors such as Vim and Emacs are very lightweight in relation to IDEs such as Netbeans and Eclipse (with PDT). This is certainly an advantage that balances the lack of available tasks supported out of the box, but I'd like to stress their versatility. Vim and similar editors take advantage of standard command-line Unix tools, which work with a plain text interface, instead of reinventing the wheel with plugins for every kind of source control and build systems.

For example, checking the syntax of a script is very simple by delegating to an external programming language parser. But it is also simple to involve any kind of external program when a keyboard shortcut or a defined function is called, or even to start an Ant or phing target. The impact on automation setup is great: you're automating a bash script or an XML build file instead of a sequence of clicks.

The syntax for running an external command is ! followed by what you would write at the command line, given that the working directory is the one where you launched vim:

!php -r 'echo "Hello.";'

You'll see the output of the command and ask to press a key to return to the opened source file.

Gotcha commands (in normal mode)

Some commands are fairly standard, even when they are only shortcuts:

• y6y selects 6 lines of text starting from the current one. Replace 6 with a custom number of lines.
• o inserts a line after the current one, while O inserts a line before it. Both leave the editor in insert mode.
• Similarly, p pastes the clipboard content after the character under the cursor, while P pastes it before.
• v can be used to select text, and V to selects full lines of text (useful for copy&paste). In one of these two visual modes, y copy the selected text while d cuts it.

Note that, unlike in bash shells, the up and down key search in the history of commands. Try inserting the start of an already issued command and complete it with up.

My .vimrc

The hidden .vimrc file in your home directory lets you define configuration directives to apply to every file you open in vim. This is my .vimrc, commented for your comfort:

" Tab key produces 4 spaces, and tab characters are converted to spaces
set tabstop=4
set shiftwidth=4
set expandtab
set background=dark
" when you start searching text with /, search is performed at every new character insertion
set incsearch
set nopaste
set autoindent
set fileformats=unix,dos
" docblock comments are continued when a newline is inserted
set comments=sr:/*,mb:*,ex:*/
syntax on
filetype on
filetype plugin on
" check syntax with Ctrl + L
autocmd FileType php noremap <C-L> :!/usr/bin/env php -l %<CR>
autocmd FileType phtml noremap <C-L> :!/usr/bin/env php -l %<CR>

Filetype plugins

The directive filetype plugin on lets you define plugin to include basing on the detected file type (for php scripts it is of course php.) All the files in .vim/ftplugin whose name starts with php will be included automatically whenever you are editing files that contain PHP code.

PHP-related vim plugins work mostly by installing themselves in the ftplugin directory. Vim normally has more than one ftplugin directory (the user defined folder in .vim, plus the system level ones), where general purpose scripts are placed. For example, these scripts set up syntax highligthing. Any PHP-specific customization you want to set up should go in the ftplugin folder to avoid interfering with Vim's general usage for other tasks such as plain text editing.

Completion

Auto completion for standard programming languages works often out of the box if you install Vim from your distribution repositories. The name of this feature is omnicompletion, and it is triggered by the sequence Ctrl + X, Ctrl + O in insert mode, to press after you have written the start of a function or class.

To setup autocompletion for a PHP library or framework with userland-defined functions, you should try ctags, which makes a periodical parsing of the source code of the given library and produces a list of the encountered tokens which Vim can use to provide autocompletion. The name implies focus on the C language, but actually all modern general purpose languages are supported. There is a simple tutorial on how to run ctags on a PHP project by the lead developer of the Zend Framework project.

There is also a very simple method to auto complete local identifiers such as variables and methods: Ctrl + N pressed in insert mode, while part of a word has already been written, will provide a list of possible completions found in the current file. Due to this combination and the simplicity of PHP's Api, I do not usually need omnicompletion and similar tools.

Plugins

snippets_emu is a useful plugin for generation of code snippets related to control structures (for, if, while) and any user-defined snipper you want to use. For example, I use it to automatically define getters and setters to access a private variable, a generic code that I would likely write many times a day instead.

Tobias Schlitt's Vim integration for PHP project is handy too. For instance, it contains functions for the insertion of docblocks on methods and automatic alignment of variable assignments. I suggest however to take only the functions you like from this plugin as many configurations can clash with the ones defined by your distribution package.