How to set up VIM for PHP development

February 13th, 2022

This is a general guide to set up vim or nvim for PHP development the way I currently use it, by the end of this guide you will be able to use vim as any other text editor designed for developers but with all the features of vim.

This article will cover the following:

Plugin Manager
Generating Ctags
Syntaxis
Browsing Files
Code Autocomplete
Additional Tips

Plugin Manager

I use a plugin manager to install all my vim plugins, you don't necessarily have to, but it will make it easier to install, delete and update your plugins.

junegunn/vim-plug

vim-plug is the plugin manager I use, you will find the installation instructions in the link above. Once you have it installed, you just need to add this configuration on top of your .vimrc:


call plug#begin()
    ""Your plugins go here
call plug#end()

Now for instance, if you wanted to install vim-fugitive (a plugin for git) you will add it between the call plug#begin and call plug#end


call plug#begin()
    Plug 'tpope/vim-fugitive'
call plug#end()

Then after saving, you run the command from vim :PlugInstall to install all the plugins listed there. Remember to do :source path/to/your/vimrc file if you didn't close vim after adding a new plugin to the list.

And done, you now have your new plugin installed!

Generating Ctags

This tag file is an index that can be set for a lot of OOP languages, including PHP.

You will need to have tags for some plugins in this article to work the easiest way to manage ctags in vim is with the following plugin

https://github.com/ludovicchabant/vim-gutentags

Syntaxis

I use this plugin for PHP syntaxis:

StanAngeloff/php.vim

I found the defaults to be good enough, however, you can go to the GitHub repo for configuration instructions.

To make sure your tab key is 4 spaces, add the following lines to your vimrc:


"" set tab width to be 4 spaces
set tabstop=4
" set the size of an 'indent' to be 4 spaces
set shiftwidth=4
" Insert 4 spaces when pressing tab instead of the tab character
set expandtab

Browsing Files

Vim comes with a default file browser while it's good enough for some, I have been using NERDTree for a while now, keep in my this issue if you decide to use it though.

preservim/nerdtree

I have the following shortcuts in my vimrc:


"" ctr+n will open and close NERDTree
nnoremap <C-N> :NERDTreeToggle<CR>
"" <leader> + o will open NERDTree in the file your editing
nnoremap <leader>o :NERDTreeFind<CR>

This is how it looks when I press ctrl+n

And this is how it looks when I press my leader key (\ by default) followed by the letter o

However, I don't usually use NERDTree to browse to a file if I already know its name for that I use:

fzf is a general-purpose command-line fuzzy finder. This has other dependencies, so it's not as simple as the other ones, you have to add two lines instead of one to your vimrc file.


    Plug 'junegunn/fzf', { 'do': { -> fzf#install() } }
    Plug 'junegunn/fzf.vim'

After that, install the_silver_searcher following this instructions.

Now, these are the shortcuts I have in my vimrc:


let $FZF_DEFAULT_COMMAND = 'find .'
nnoremap <leader>f :Files<CR>
nnoremap <leader>a :Ag<CR>

Now if I wanted to search for the Kernel.php file I would press my leader key and f right after, and then type the name of the file I'm looking for:

The second shortcut I added is to search for matches in the file names and inside of the files, for example, if I wanted to search the uses of 'web' I would press my leader key and a right after, and then search for 'web'

Code Autocomplete

The best autocomplete plugin for PHP I have found is coc.vim with coc-phpls (an extension for coc.vim)

neoclide/coc.nvim

For this plugin to work, you need to install nodejs:


curl -sL install-node.vercel.app/lts | bash

Then add it to your plugin list like so:


Plug 'neoclide/coc.nvim', {'branch': 'release'}

After running :PlugInstall install the language server for PHP from vim with the command :CocInstall coc-phpls, you can take a look at the language serves to see what additional extensions for coc.vim you want to install. This is the list of what I currently have installed:

coc-phpls
coc-json
coc-html
coc-css
coc-tailwind
coc-tsserver

I recommend adding the following shortcuts to your vimrc after installing coc.vim and coc-phpls


" Use <TAB> to select the popup menu:
inoremap <expr> <Tab> pumvisible() ? "\<C-n>" : "\<Tab>"
inoremap <expr> <S-Tab> pumvisible() ? "\<C-p>" : "\<Tab>"
inoremap <expr> <CR> pumvisible() ? "\<C-y>" : "\<CR>"

" gd to go to definition
nmap <silent> gd <Plug>(coc-definition)
" gr to go to reference
nmap <silent> gr <Plug>(coc-references)

Now you should have autocomplete and auto import!

You can go to the definition of a class or variable by pressing gd (the g key followed by the d key)

And you can search for uses by pressing gr

Additional Tips

I have this little script in my vimrc to remove empty spaces from files when you write to them


fun! TrimWhitespace()
    let l:save = winsaveview()
    keeppatterns %s/\s\+$//e
    call winrestview(l:save)
endfun

augroup MY_GROUP
    autocmd!
    autocmd BufWritePre * :call TrimWhitespace()
augroup END

These are some of my mappings


" leader space to remove the hightlight after a search
nnoremap <leader><space> :nohlsearch<CR>

" easier movement between splits
" Ctrl + j to move to the split below
nnoremap <C-J> <C-W><C-J>
" Ctrl + k to move to the split above
nnoremap <C-K> <C-W><C-K>
" Ctrl + l to move to the split to the right
nnoremap <C-L> <C-W><C-L>
" Ctrl + h to move to the split to the left
nnoremap <C-H> <C-W><C-H>

" . to repeat the last action to all the lines selected in visual mode
vnoremap . :norm.<CR>

" ctr + y to yank to the system clipboard
vnoremap <C-Y> "+y

And that's it, if you have any questions or comments you can reach me on Twitter at @_damianEduardo, follow me if you liked this post.