VimRunner PHP

As part of my PHPUK talk, I automated vim. I promised I’d share the code, so here it is

You’ll need vim compiled with +clientserver. To test, try running vim --servername test. If you get the error Unknown option argument: "--servername" it means that your vim install doesn’t have +clientserver.

You have two options at this point. You can either recompile vim with +clientserver or you can use a distribution such as gvim or macvim that come with it enabled. On Linux, I tend to recompile vim but on OSX I use macvim.

Once you have a compatible vim, you can start using the library.

Create a composer.json with the following content

  "name": "yourname/someproject",
  "authors": [
      "name": "A User",
      "email": "[email protected]"
  "require": {
    "mheap/vimrunner-php": "^0.0.1"
  "minimum-stability": "dev"

Then run composer install. This will download the VimRunner library.

Next, create a file called example.php that contains the following:


require 'vendor/autoload.php';

$c = new Vimrunner\Client("michael");
$c->writeLine("Hello", 3);

This is the script that will drive Vim.

You’ll need a server to talk to, so start one up with vim --servername MICHAEL. It should show vim just like normal. Leave it as it is and don’t touch it.

Run php example.php and hopefully your vim instance should come to life, typing “Hello” quite slowly.

That’s all there is to it. There’s a few helper functions (take a look at the repo for docs) but you can do anything you can do in vim using a combination of $c->normal() and $c->command().

If you fancy contributing to make it a bit nicer (it really was an afternoon hack project to play around) please do! Some more abstractions and a nicer API would be awesome to add.

(PS: If you have any ideas how to test this, I’d love to hear from you)

February 25, 2016