How to set up VIM for PHP development
Tags: php, vim, nvim, productivity
Published: 2022-02-14 22:05:09

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](#plugin-manager)
* [Generating Ctags](#generating-ctags)
* [Syntaxis](#syntaxis)
* [Browsing Files](#browsing-files)
* [Code Autocomplete](#code-autocomplete)
* [Additional Tips](#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](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:

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

Now for instance, if you wanted to install [vim-fugitive](https://https://github.com/tpope/vim-fugitive)  (a plugin for git) you will add it between the call `plug#begin` and `call plug#end` 

```sh
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](https://github.com/StanAngeloff/php.vim)

 I found the defaults to be good enough, however, you can go to the [GitHub](https://github.com/StanAngeloff/php.vim) repo for configuration instructions.
 
 To make sure your tab key is 4 spaces, add the following lines to your vimrc:
 ```sh
 "" 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](https://github.com/preservim/nerdtree/issues/1280) if you decide to use it though.
 
*  [preservim/nerdtree](https://github.com/preservim/nerdtree)

I have the following shortcuts in my vimrc:

```sh
"" 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`
![Gif of Ctrl+n](https://i.postimg.cc/vBkbJck7/nerdtree-toggle.gif)

And this is how it looks when I press my leader key (`\` by default) followed by the letter `o`
![Gif of leader + o](https://i.postimg.cc/tRshWwz8/nerdtree-find.gif)

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

* [junegunn/fzf](https://github.com/junegunn/fzf)
* [junegunn/fzf.vim](https://github.com/junegunn/fzf.vim)

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. 

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

After that, install [the_silver_searcher](https://github.com/ggreer/the_silver_searcher) following these [instructions](https://github.com/ggreer/the_silver_searcher).

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

```sh
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:
![Gif of file search](https://i.postimg.cc/vmWGJYMC/search.gif)

The second shortcut I added is to search for matches in the file names and inside 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'`
![Gif of text search](https://i.postimg.cc/8zGGh8LH/web.gif)

## Code Autocomplete

The best autocomplete plugin for PHP I have found is coc.vim with [coc-phpls](https://github.com/marlonfan/coc-phpls) (an extension for coc.vim)

* [neoclide/coc.nvim](https://github.com/neoclide/coc.nvim)

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

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

Then add it to your plugin list like so:

```sh
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 servers](https://github.com/neoclide/coc.nvim/wiki/Language-servers) 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

```sh
" 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!
![Gif of auto import](https://i.postimg.cc/tTnPFVH8/autocomplete.gif)

You can go to the definition of a class or variable by pressing `gd` (the g key followed by the d key)
![Gif of gd](https://i.postimg.cc/J4xyDQkG/gd.gif)

And you can search for uses by pressing `gr`
![Gif of gr search](https://i.postimg.cc/CxZFhCHy/gr.gif)

## Additional Tips

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

```sh
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

```sh
" 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](https://twitter.com/_damianeduardo), follow me if you liked this post.