Cover photo for post Comfortable PHP editing with VIM -5-

Comfortable PHP editing with VIM -5-

More than a half year after my last "Comfortable PHP editing with VIM" post, I take up this series again, although I decided to let it die in January. Sadly I did not find any time by now, to extend PDV (the PHP Documentor for VIM plugin) further than it's version 1.0.1, which is available through and on my SVN. Anyway, I collected a lot of (at least for me) helpful VIM tips, which I'd like to share here:

Next occurrence of a word

If you hit *in command mode and your cursor resides on a word, you are taken to the next occurrence of the word. This is quite nice, if you like to know, where a function is called again.

Find matching brace

VIM 7.0 luckily highlights matching parenthesis, if your cursor resides on a brace, but sometimes you need to quickly jump to that matching brace. You can achieve this by hitting the % sign in command mode.

Repeat the last change

It often occurs, that you need to perform 1 change several times, but not often enough to write a short script or to address the changes with a complex regex. In those cases you can perform the change once, move the cursor to the next place and hit the . (dot) char, in command mode.

Enhanced functionality with external programs

This tip is quite commonly known, but I repeat it here, because it's really helpful: Although VIM has a huge set of useful functions, it does not have everything. If you don't find a utility in VIM, you can simply use extern shell tools to perform certain tasks, by using :!<command> in command or visual mode. For example sorting a range of lines can easily be achieved with the following 2 steps: 1. Select the lines to sort in visual mode. 2. Type :!sort and hit return.

Indenting and unindeting

Especially when editing code, it happens often, that you have to indent/unindent a code block. If you use VIM's auto-indenting features (like used by my .vimrc), VIM can do that job for you, too. Simply select the lines to (un-)indent in visual mode and hit <} to unindent 1 level or > to indent 1 more level. This also works (as usual in VIM) with quantifiers like 4> to indent 4 more levels.

Remote file editing

Often you have to quickly edit a file on a remote server. Usually you SSH to that server or mount a remote file system locally, edit the desired file and quit the session again. VIM allows you to do this i 1 step, using SCP. On your shell type vim scp://user@server//path/to/the/file and VIM will edit the file directly through SCP.

Recover the last visual selection

It often happens, that you selected some text in visual mode, e.g. to perform a regex on it. Occasionally your regex is incorrect and you have to revert the changes or they don't even happen. What you then need is to re-select the text portion again, which might take quite a long time, if you deal with large files. Hitting gv in command mode, takes that work from you and selects the last visual selection again.

Grep within VIM

Refactoring happens quite often in dynamic projects. "Real" IDE's offer a lot of tools for this task. While VIM does not, you can enhance your refactoring process a lot with using regex and this tiny tip: To grep through a lot of files for certain strings and then perform changes on each occurrence, vim offers the :grep command. :grep <string> <files> and VIM will store the list of changes for you and :cn will take you to the next occurance of your string. The :grep command utilizes your systems instance of grep, or a custom command stored in the grepprg configuration variable. There is also an internal implementation of grep available in VIM, which you can use with :vimgrep /<regex>/<flags> <files>. The benefit of the external implementation is, that you can easily customize the command to use, e.g. if you need to ignore certain directories while grepping recursively (for instance .svn dirs). You can also get a list of all occurrences of your grep command, using :ll, which is actually a feature of VIMs quickfix tool. Simply select the next entry you want to jump to and hit return in the location list.

Placeholders in commands

Who doesn't know the case, where you need to open a file in the same directory, the currently edited file resides in? Sure, you can simply use :split <file>, but if your current working directory is far away from the edited file, you possibly will have to type a long long path again. VIM offers you, to replace certain placeholders in commands automatically, most important: % is replaced with the actual file name (so, :split % will open a new window editing the current file - I know that just :split does the same, but it's a nice example to show what % does). So, how does this help in the described case? The replacement text can also be modified by certain modifiers, like :h, which removes the last portion of a file path (the file name). For instance if you currently edit /home/dotxp/dev/ez/ezc/trunk/ConsoleTools/src/table.php and want to split to /home/dotxp/dev/ez/ezc/trunk/ConsoleTools/src/output.php you can do this easily using :split %:h/output.php. Another useful modifier is :s?<regex>?<replacement>?, which obviously uses a regex to modify the given path. Unlikely the usual replacement command :s, you need to specify the global modifier g before the regex instead of doing so after it. A short example: :split %:gs?trunk?/releases/1.1/? will split to the file table.php of ConsoleTools release 1.1.

Emergency help

Appending an exclamation mark (!) to a command (:<command>!) forces VIM to execute the command, even if it might be dangerous to do so. Quite useless, but still funny is :help!.

Rewrap my text

I reached a stage, where do not only edit my source code using VIM, but mainly every other kind of text data (like documentation, todo lists, etc.), because I'm simply so used to its features. When editing plain text, the automatic wrap features (e.g. textwidth) of VIM are quite useful. In some cases, you might edit text later and therefore destroy a nicely wrapped text block. VIM can easily re-perform the wrapping for you: Select the text block in visual mode (using <SHIFT>+<v>) and hit "<g><q>".

Spelled correctly?

In VIM versions earlier to 7.0 you could add spellchecking using external scripts. The new version has this feature per default. What you need to do before spell checking is available, is to set the language of the document you are currently editing, using :setlocal spell spelllang=en_us (note, :setlocal only sets the value for the current window, use :set to set it globally). Now VIM highlights all unknown words and you have 3 important new commands available (in command mode). All are used when your cursor resides on a highlighted word: <z><=> opens a list of suggested replacements, you can choose one by typing its number or leave the selection untouched using <RETURN>. <z><g> adds the highlighted word to the global dictionary, so that it is recognized as correct on any spell checking session, later. <z><G> only adds the word to the local dictionary, so that is recognized as correct during the actual spell checking session.


Performing complex tasks very often might be quite time consuming and often not solvable using even highly complex regex. Before writing a complex script, you should consider, that VIM can simply follow your instructions and record them to a script: Type <q><a> in command mode, to instruct VIM to record all following commands to the register a. Perform whatever you like and finally hit <q> again (in command mode). Your macro is now recorded. Type <@><a> in command mode, to execute the contents of register a (namely your just recorded macro). A simple example for this is to move certain lines of a file to its top: Go to the first line you need. Type <q><a>. Now perform the changes: <d><d> to delete the line, <m><'> to set the "last editing position mark", <:><1><RETURN> to jump to the first line of the file, <P> to paste the just deleted line, <'><'> (2 single quotes) to return to the last editing position. Finally hit <q> to end the recording. Now you can just do <@><a> on every line you need at the start of your file. Easy, isn't it? :) Additionally <@><@> repeats the last macro execution (so you even don't need to remember the register you stored it in).

Uppercase letters

There are a lot of helpful shortcuts on your keyboard, which you might not know about. Every VIM user should now, that <d> deletes something, <y> (yank) copies something and <c> changes something (delete and start inserting) in VIM (all in command mode). Furthermore, most people know that e.g. <d><w> deletes the next word, etc.. What I did not know for a long time was, that <D>, <Y> and <C> are shortcuts to perform the desired operation until the end of the current line. For instance, simply type <C> to change the contents of the current line from your cursors position on.

Where am I?

If you have a large resolution (e.g. mine is 166x1200), you sometimes loose your cursor when looking at something else in the room. The new customization features of VIM 7 allow you to add a nice finding help: Add the lines autocmd InsertLeave * se nocul and autocmd InsertEnter * se cul to your .vimrc and you will get the current line underlined as soon as you enter insert mode.

Regex driven commands

Regular expressions belong to every VIM users toolbox. What some people might not know (so didn't I) is, that you can not only do replacements with them in VIM, but also address lines you want to perform commands on. Simply do :s/<regex>/=<command> to execute the given <command> on each text portion that matches <regex>.

Magic regex

Those of you who are used to PCRE syntax (and I hope all of you PHP developers out there), will often struggle over VIMs POSIX style regex and forget toescape parenthesis and other stuff. Usually VIMs regex work in so called magic mode, which means that VIM treats only a limited set of characters as magic inside a regex (that applies e.g. to ., matching any character, and *as a quantifier). Other characters, like (, ) and | are per default not considered magic and have to be escaped to make them magic (i(, ) and |). While this might be convenient insome cases (like simple text replacements without back-references), it becomes quite ugly, if you need to refer to a lot of capturing parenthesis. For this cases, it makes sense to switch VIM into very magic mode, using v at the beginning of your regex. The opposite of this switch is V, which makes the regex very nomagic. Because VIM is normally in magic mode (which corresponds to setting m, if you change the default behaviour), there is also a nomagic mode, which considers less, but still some, characters as magic. Some simple examples:

Error with CSV data in "csv-table" directive: ',' expected after '"'

.. csv-table:: "s/(foo)bar/1/", "does not work, () must be escaped" "s/\v(foo)bar//1/", "does work, regex is considered very magic" "s/.*bar$/foobar/", "replaces a line with foobar, that ends on bar" "s/\V.*bar$/foobar/", "replaces a line with foobar, contains literaly ".``*``\bar$""

This were quite many tips, especially for unexperienced VIM users. I recommend to not try to learn them all at once. Pick out 2-3 tips that you consider very important for your daily work and start getting used to them. When you are sure, you use them every time it makes sense, grab the next 2-3 and so on. I also recommend to every programmer out there, to read a work I personally call "Bible of text editing", written by Bram Moolenaar, the author of VIM itself. These 7 tips really make sense and explain quite simple, why I personally love to use VIM.

I hope the above shown tips help some people to make their daily work a bit more efficient and I also hope that I will manage to set up a new website soon, so I can consolidate all of my VIM tips in 1 central place. So long you will have to use my blog to find them again, so here is the whole collection of my "Comfortable PHP editing with VIM" series:

Part -1- Part -2- Part -3- Part -4-

Note, that in the links in earlier editions of this series might be broken. Please refer to the latest versions of the links, contained in this article!

Have fun! :)


It good solution to use ctags utility for autocomplete php functions 1. download the latest php manual in "many html files" format 2. write some shell(or perl) scripts that will parse these files and creates e.g. from function.mysql-connect.html via e.g. lynx 3. function.mysql-connect.html.txt -> function.mysql-connect.html.txt.php

4. ctags ~/php-tags, ~/php-tags is directory where function.*.html.txt.php is located 5. in ~/.vimrc put

now you can autocomplete php word by ctrl+ p and if you press ctrl+w & ctrl+ } you'll go to needed man page

Taras at 2006-08-23

This will be invaluable to me, thanks a lot :)

David Craddock at 2006-08-23

is there any chance to download your .vimrc? It is linked in part 3 of the tutorial, but opening the URL I only get a 404 error

hans at 2006-08-24

You can find it in my SVN repo (as writen in the article):

Hope it's useful! Toby

Toby at 2006-08-24

Awesome stuff Toby, I'm a keen follower of this little mini series.

Particularly like the editing over scp, although I'm not having much luck with it under cygwin, going to keep digging though.

Keep up the good work.

Dave Marshall at 2006-08-24

Very usefull tips. I just started to use VIM, and looked for some PHP specific tipis, then I found your blog and your entries, thanks ... good job! :)

depi at 2006-08-26

Great stuff, thanks for all the tips. I was hoping that you had been cooking up some improvements using VIM 7s omnicomplete feature. My experience with it thus far has been mixed, as it adds some interesting completion for objects, functions, and support for ctags. But in some ways it lags behind simple keyword completion.

Another type for expanding the current filename on the command line is to use ctrl-r % to insert the current filename directly onto the command line. Where's the documentation on placeholders? I can't seem to find it.

Thanks again for all your vim tips.

Scott Wehrenberg at 2006-09-07

damn, this is great stuff! say i use this autocompletion-function and type fex $_GET["test|"] and the pointer is at the pipe |, is there an easy way to make it jump to the end $_GET["test"]| at the press of Enter? this could be a nice feature

Torgeir at 2006-09-19

im also wondering if you got these examples for using PDV..

Torgeir at 2006-09-19

Where did the 'auto reload vimrc when it has changed' go? I can't seem to find it in your svn. Thanks.

Roel at 2006-10-02

i get a 404 on your .vimrc file... else than that, i have to say, that your tips are great!

caillou at 2006-11-23

sorry to bother you with that, but the SVN gives 404 / 403.

i use your config on a daily basis (and i am very grateful), but i cannot seem to get the old one to work with vim 7...

any tips?

cheers ... caillou

caillou at 2006-11-23

I'm sorry, because of a server migration, it is currently down. It will be up shortly, again.

Toby at 2006-11-23

So, the SVN web access is up and running again.Sorry for the inconvenience.

Toby at 2006-11-25
Craig at 2006-12-20

Fixed now. Thanks for the hint!

Toby at 2006-12-23

Great stuff, Toby :D A small suggestion: you may want to replace

so that people who install the plugin using their distribution's package manager can still customize things in .vimrc (which gets sourced before the plugins, apparently) without losing the changes on upgrade ;)

m0n5t3r at 2006-12-24

Hi there!

That sounds like a good idea. I will keep it in mind for the next release.

Thanks! Toby

Toby at 2006-12-24


i just wanted to download the vimrc but i could't, not allowd in svn. thanx for great tutorial and help. i just want to work with it and i can't


Tim at 2007-01-05

Looks like this issue occurs now and then. I fixed it now again. Thanks for the hint!

Toby at 2007-01-09

Any chance that you could put a copy of phpm in the repository. Havard Eide's site is down, and seems to have been for at least a half year.

troels at 2007-03-25

That subversion repository for the .vimrc file doesn't work anymore.

Thomas Andrews at 2010-02-15

Note that PDV is now named VIP and hosted on github. For details, please refer to

Toby at 2010-02-16