1. Why bother?
2. Starting out with Vim
3. PHP syntax highlighting
4. PHP syntax checking/linting
5. Tags and auto-completion
6. Codesniffer and mess detector support
7. PHPUnit support
8. Xdebug integration
9. Everything in a neat package

If you’re impatient and want to start tinkering straight away, jump to section 9 to install my Vim configuration.

1. Why bother?

I’ve used a number of IDEs for PHP projects over the past few years: Eclipse, Aptana, Komodo Edit/IDE, Netbeans and PHPStorm. The problem with many of them is speed and resource usage: they eat away at your memory and hog your CPU. Another problem is keyboard shortcuts and commands: it is impossible to do everything using the keyboard, and many things are quicker with the mouse, requiring you to constantly swap between keyboard and mouse. This may not sound like a big deal, but spend a few months learning Vim and it will be a big source of frustration.

So, the answer to that question is this: in the long run, you will be a lot more efficient. Jump to exactly the right place in a file in just a couple of key strokes; open a horizontal split window comparing two files with a command as simple as <Ctrl-w> + s; swap between open files by number (the order of opening); and my favourite – view and navigate a directory tree with all the usual Vim functionality.

2. Starting out with Vim

If you’ve never used Vim before, try the tutorial I mentioned at the top of this post. Also, take a look at the Vim cheat sheet.

The rest of this tutorial assumes that you have a working knowledge of Vim and know how to configure it on at least a basic level (i.e. you know where your vimrc file is, and you know how to install vim scripts). It also assumes that you’re running at least version 7.0 of Vim.

If you don’t know how to install Vim scripts I’d recommend using Vundle, which will manage all your plugins for you and make installing/removing a breeze.

3. PHP syntax highlighting

Vim understands PHP by itself, but you can get improved highlighting and basic syntax checking with the php.vim plugin. This will add better support for certain PHP keywords like define and static, etc., and will allow you to apply custom colours to these keywords. Also, it puts some basic checks in place for invalid syntax, and will highlight the line if you don’t close your brackets, for instance.

4. PHP syntax checking/linting

Most IDEs will run the PHP parser on the file periodically, and warn you of any errors such as invalid syntax and multiple declarations of classes/functions within the same file. One of the beautiful things about Vim is that you can run files through command line programs with total ease, so to check your PHP file you could just run:

:!php -l %

This prints out any error message to the screen. However, we can do better. Vim has a feature called signs, which are used to mark and highlight lines in a file. Wouldn’t it be nice if we could take the PHP parser’s error message and highlight the right line in the file?

It would be nice. And it is nice, because it’s been done. <shameless plug> I have a plugin that does it, called PHP QA tools </shameless plug>. Install this, and every time you write a file it will check it for syntax errors and highlight any offending lines in the file. It will also open a quickfix window that displays the error. This window is specially made for listing errors, and you can read about how to use it in the documentation.

PHP syntax errors are highlighted and shown in the quickfix window

The same plugin will be useful for some things that appear later, so read on…

5. Tags and auto-completion

Code-completion is a feature that most large IDEs provide, along with the ability to jump to class and function definitions within multiple files. All IDEs do this by creating a database of the definitions, and updating this database as you change the code. Many people think that this is a reason not to change to using Vim, as the support isn’t there; this isn’t true.

Omnicompletion is a feature of Vim 7+, and it works by reading a tag file generated by a command-line program called ctags. This file contains definitions for all the classes, functions and variables in your project. You then use <c-x><c-o> (read that as: Ctrl+x followed by Ctrl+o – that’s Vim’s way of showing a Ctrl modifier shortcut) to bring up a list of completions when you are in insert mode. Here’s a screenshot showing it at work:

Omnicompletion at work

A quick note

Before we go on, I’d just like to say that I don’t use omnicompletion. Instead, I use Vim’s local keyword completion. There are several reasons for this:

1. There’s a delay as the context for omnicompletion is determined, and the tags are collected together. This is the case in every IDE I’ve used – it makes logical sense that it as a project gets bigger, the impact on performance of autocompletion gets greater.
2. Local keyword completion is lightning fast, and in many cases saves me valuable seconds (or at least milliseconds!) in typing longer words. This is even more the case with the SuperTab plugin, which I’ll mention soon.
3. It only works for words defined in the current file, but it encourages me to be a better programmer by using consistent naming methods for functions and variables, for instance.

How to generate Ctags

ctags-exuberant -f php.tags --languages=PHP -R

This will create a file named php.tags, which contains a summary of all the definitions of PHP constructs in your project. You may need to tweak the parameters in this command: you may want to exclude certain files (e.g. build artefacts, documentation, etc.), or exclude whole languages like JavaScript from being parsed (--languages=+PHP,-JavaScript). When you’re happy with your tags file, you need to tell Vim to use it:

:set tags=~/path/to/php.tags

You can use more than one tag file at a time: I generate a tag file for my entire PHP include library (i.e. PEAR stuff), a tag file for the framework I’m using and then a tag file for each project, and set all three to be used with a comma separated list.

Now that you’ve set up your tags, try it out. Open up a new PHP file, set the tag file and start typing the name of a class that you know exists. After a few characters type <c-x><c-o> (insert mode) and the omnicompletion will kick in. Then, on the completed class name in command mode, type <c-]>. You will be taken to the class definition, or given a list of definitions if it matches more than one.

Another neat feature is jumping to a tag from the Vim command line. For example, if you know you need to get to the file containing the class MyLovelyClass, just type:

:tag MyLovelyClass

And hit return. You will be taken straight to it. This is almost always quicker than trying to navigate a file tree to find the file you want. Also, this supports tab completion, so you could just type :tag My<tab> and you would get a list of options.

If you’re going to use omnicompletion, definitely install the phpcomplete plugin, as this adds better context awareness for omnicompletion in PHP. I’d also recommend installing SuperTab, and adding this to your vimrc:

let g:SuperTabDefaultCompletionType = ""

Now you just press Tab to trigger omnicompletion.

6. Codesniffer and mess detector support

If you’re not familiar with these tools then you may want to skip this section, as you will only want this support if you already use them. Support for these comes bundled in the PHP QA tools plugin (view on github), which you will already have installed if you’re following each step of this tutorial. The plugin parses their output, puts the violations into a quickfix window and puts line markers in the file (uses the marker S> for codesniffer and M> for mess detector violations). Nice and simple.

Codesniffer and mess detector signs are shown in the margin, and messages in the quickfix window

Everyone who uses these programs has their own set of configuration rules, and happily this plugin allows you to change the configuration to suit. You can set various options in your vimrc file:

CODESNIFFER

" Pass arguments to phpcs binary
let g:phpqa_codesniffer_args = "--standard=Zend"
" Another example
let g:phpqa_codesniffer_args = "--standard=/path/to/xml/file.xml --tab-width=4"

" PHP codesniffer binary (default = phpcs)
let g:phpqa_codesniffer_cmd='/path/to/phpcs'

" Run codesniffer on save (default = 1)
let g:phpqa_codesniffer_autorun = 0

Mess detector

let g:phpqa_messdetector_ruleset = "/path/to/phpmd.xml"

" PHP mess detector binary (default = phpmd)
let g:phpqa_messdetector_cmd='/path/to/phpmd'

" Run mess detector on save (default = 1)
let g:phpqa_messdetector_autorun = 0

7. PHPUnit support

If you use PHPUnit then you can run tests from the Vim command window with another one of my plugins: PHPUnitQF (view on github). This parses the output from PHPUnit tests, and any failures or errors are put into a quickfix window, allowing you to easily jump to the tests that weren’t successful.

To run the tests, just execute:

:Test

Where <arg> is passed straight to the phpunit command. For example, if you would normally run phpunit MyClassTest from a command line, you run :Test MyClassTest from Vim. If you have a standard set of arguments that you pass to phpunit (e.g. a configuration file), you can set a variable in your vimrc file. Here are the available configuration options:

" Arguments to pass to the phpunit binary
let g:phpunit_args = "--configuration /path/to/config"

" Location of phpunit
let g:phpunit_cmd = "/usr/bin/mytest"

" Temporary file used by the plugin
" (shouldn't need to change unless runing on Windows)
let g:phpunit_tmpfile = "/my/new/tmp/file"

You can use any test wrapper whose output is the same format as PHPUnit. For instance, I sometimes use the CakePHP framework which has a wrapper around the PHPUnit command, so I just change g:phpunit_cmd as shown above.

You can also view the full output of the last test run with:

:TestOutput

This opens the output in a split window.

8. Xdebug integration

That’s right. You can use Vim as a debugger client with Xdebug, so it throws the same punches as the big boy IDEs. In fact, I think that the Xdebug plugin for Vim allows more flexibility and functionality than any other implementation I’ve found. It’s certainly easier to tweak and modify it. It’s also great out of the box, and you can get it up and running within a few minutes.

This plugin has a bit of a legacy: it started here, a script by Seung Woo Shin, and has been modified and forked like mad. It goes without saying that I have my own version of it, which you can get from the github repository.

Note: by all means use another version if you wish, but I have added quite a few features that I use all the time, so they might be useful to you too. Look at the README in the repository for a list of changes.

After installing the plugin you will need to set up Xdebug on your machine. To do this, follow step 1 and (optionally) 4 and 5 on my Xdebug, LAMP and Netbeans tutorial.

Now you can set breakpoints in your code with F1 or:

:Bp

Press F5 to make Vim try and connect to the debugger (on port 9000 by default), where it waits for 30 seconds before timing out. During the 30 seconds, if you load the webpage or run the script then the session will start. One of my changes is to open the session in a new tab, to not disrupt the window configuration in your current tab, so you will see a new tab and a few windows open up. It will look something like this:

Windows from left, going clockwise: source code pane, watch window, current stack trace, command window

The left window shows the source code and typically the current execution point. The watch window is one of the key features, as it shows the result of getting the context (i.e. all the variables and their values at the current execution point) and eval results.

To start stepping through the program line-by-line, press F3. The -> marker will move as the program moves on. Execution will pause at any breakpoints that you’ve set up. To step into a function on the current execution line press F2, and F4 to step back out.

To get the current context, press F11 – the watch window will show all variables and their values. You can also evaluate expressions, by typing:

e

(The Leader key is usually \ or ,) You can then type a PHP expression (e.g. a variable, or any valid expression like sqrt(100)), press enter, and the result will be printed in the watch window.

When you’ve finished, press F6 to end the session and close all the windows.

That’s enough to get you started, but you can read the README on the Github repository for more information.

9. Everything in a neat package

Maintaining a Vim configuration is a tricky business. Sometimes you make changes that you think will be helpful, find it annoying after a couple of weeks, and you want to revert back to an old version. That’s exactly why I keep mine under version control – you can view it here.

If you want to use this configuration, there are a couple of things you’ll need to install. You’ll need exuberant-ctags, as talked about in section 5. I’d also recommend installing the Anonymous Pro font if you’re using GVim, as it’s the best code font I’ve come across.

To install, clone the repository to ~/.vim, and initialize the submodule. Then, install the Vundle bundles:

git clone git://github.com/joonty/myvim.git ~/.vim --recurse-submodules
vim +BundleInstall +qall

What’s in the package? Along with everything mentioned in this tutorial, it has the following plugins:

• NERDTree: shows the directory tree, and allows for navigation and modification. Completely essential in my eyes.
• MiniBufExpl: (Mini buffer explorer) shows the open buffers in a kind of tab format, allowing you to easily manage multiple files.
• Tag List:  show definition summaries of classes, functions, variables, etc. for all open files.
• Fugitive: the definitive Git plugin.
• Command-T: super-fast file finding and opening.
• EasyMotion: quickly jump to any word or character in a file.

To use Command-T you need to install a C library – follow the instructions on the plugin’s webpage to install on your system. Trust me, it’s worth it.

Here’s a word of warning: this is my configuration, and it’s likely to change on a fairly regular basis. I don’t guarantee that it will work on your system, and I certainly don’t guarantee that you’ll like it. Feel free to chop and change it as you please.

The Final Word

Hopefully this has been helpful. If you have any suggestions for things I should add to this list then just add a comment.

May the Vim be with you.

Check out http://vim.wikia.com/wiki/Use_Vim_like_an_IDE and http://arstechnica.com/open-source/guides/2009/05/vim-made-easy-how-to-get-your-favorite-ide-features-in-vim.ars for more on that.

I now use Vim as my main PHP editor, and one thing that I’ve managed to get working better than any other IDE I’ve used is integration with quality assurance tools like PHP code sniffer, PHP mess detector and clover code coverage (produced from PHPUnit tests). I’ve written phpqa (vim script #3980), a plugin for Vim that integrates these three tools with your code by highlighting and marking lines with violations and code coverage output. Here are some screenshots showing it at work:

Showing PHP syntax error caused by a missing semicolon

Showing code coverage and code sniffer violations. The lines covered by tests have a yellow "C>" marker, and lines not covered have a red marker.

For more information, including installation, configuration and usage, visit the github page.

Hopefully this plugin will be useful to others, and maybe even convert some people to using it as their IDE replacement! (I know, I’m a dreamer)

The plugin is a meme generator. Don’t know what a meme is? Take a look at memegenerator.net, and any one of those pictures is a meme. The plugin creates a new meme if your project’s build fails, using the memegenerator.net API, and posts it on the project page. Who broke the build? No more hiding – they’re immortalised in an image. Just a bit of fun.

If you fancy giving it a go, sign up for a free account at memegenerator.net and install the plugin from the update center in your Jenkins instance.

• Wiki page: https://wiki.jenkins-ci.org/display/JENKINS/Meme+Generator+Plugin
• Source code: https://github.com/jenkinsci/memegen-plugin

If you don’t agree with me about vim, or you don’t know what I’m talking about, read this article: Why, oh WHY, do those #?@! nutheads use vi?

Two worlds are about to collide: there’s a fantastic plugin for Netbeans called jVi (http://jvi.sourceforge.net/), which allows you to work with all the features of Netbeans and edit code as if you were using Vim. You can install it from Tools -> Plugin in your Netbeans. It works beautifully, and any Vim user will immediately feel at home. In fact, I’m forgetting what it’s like to live without it.

If you give it the time it deserves, I promise you that you won’t want to go back to the way things used to be!

I’ve written this tutorial using Ubuntu 11.10 with Netbeans IDE version 7. It’s recommended that you have this version of Netbeans, as certain things change pretty drastically from version to version. This tutorial mentions CakePHP specific set-up from time to time, but will work for non-Cake projects. I assume that you have a working LAMP environment (Linux, Apache, MySQL and PHP) with PHP 5+. If not, Google it ^_^

1. Install Xdebug

If you’re using Ubuntu, this is as gloriously easy as typing this in a terminal:

$ sudo apt-get install php5-xdebug

If you’re not, don’t worry – you can install it using pecl. (Having said that, I’ve frequently found that pecl doesn’t work the way it’s supposed to, and have had to compile extensions manually. Drop a comment if you have problems.)

$ sudo pecl install xdebug

Providing that one of the two previous commands worked, you need to add some configuration settings so that PHP can use Xdebug. Edit or create the file /etc/php5/conf.d/xdebug.ini, adding the following lines:

xdebug.remote_enable=on
xdebug.remote_handler=dbgp
xdebug.remote_host=localhost
xdebug.remote_port=9000

Xdebug should now be working – running php -m on its own should list xdebug as one of the loaded extensions.

2. Configure Netbeans IDE

Go to Tools -> Options, then click the PHP tab. Under “Debugging”, the following options should be set:

• Debugger port: 9000
• Session ID: netbeans-xdebug
• Stop at first line: (ticked)

This is all that’s needed to set up Netbeans in general, but it’s slightly more complex configuring each project.

3. Configure Netbeans project

There’s a huge variety of ways that you can set up a web project on your LAMP configuration, so I’ll try to make it clear what each option means. To edit the settings for an individual project, right click on the project in the Projects side bar, and choose Properties.

This panel has several categories on the right, and should have Sources selected. On this panel, set the Web Root to the directory containing your index.php file (for CakePHP projects this should be app/webroot - this is essential for making it work).

Next, select the Run Configuration panel. This is where you set up profiles for running your web application. You can have multiple profiles for different configurations, which can come in handy if you are using a framework that also supports command line execution. Choose “Local Web SIte (running on local web server)” as the Run As option, and then enter the local URL of your project (this could be http://localhost, or whatever host name you’ve given). The panel should now look like this:

Run Configuration panel in project properties

Note: many people have one local website running at a time (i.e. http://localhost), and swap the Apache document root as and when they need. I prefer to set my sites up as virtual hosts, and give them each internal host names (e.g. http://joncairns.local).

Now, on the same panel, click “Advanced”, which will open up a new window. The most important thing you should do here is add “localhost” as the debugger proxy at the bottom of the window. Another thing that you would probably like to do is choose “Ask Every Time”  for the debug URL, which will ask you to specify the URL when running the debugger, otherwise it will always go to the root URL.

You should now be ready to run the debugger. Click on a line number somewhere in your code (a line that you know will be executed) to mark it as a breakpoint; this means that the execution will pause when it gets to this line. This is what a breakpoint looks like:

Click on the line number to activate a breakpoint

One of the buttons at the top of the Netbeans window, below the menu, is the button to start the debugger (tooltip “Debug Main Project”) – click it. Your browser should open a tab with your project URL, and hang. You will then see that the breakpoint that you set has changed colour, meaning that the debugger has reached that point. You can use the debug windows to browse any variables in the current scope, which is totally awesome! I’ll leave it to you to use its full potential. When you’re ready to move on, click the icon that looks like a white arrow in a green circle, at the top of the Netbeans window. This will tell the debugger to move to the next breakpoint, or complete the execution if there aren’t any more set. You can stop the debugger at any point by clicking the big red square icon.

4. Integrating with Chrome/Firefox (optional)

Currently we can kick off a debug session from Netbeans, which opens a browser window. But what about if we want to go the other way, starting with our browser, and wake the debugger by reloading our website? This is possible for Google Chrome or Firefox, using plugins.

Google CHrome

This is my personal choice, and there’s a neat plugin called Xdebug helper that does a good job of linking your sites with Netbeans and Xdebug. Download and install, then go to Tools -> Extensions and open the options for Xdebug helper. Under Domains, enter the domain of your site (e.g. localhost or joncairns.local). Then open up a tab with your site and click the little bug icon in the far right of the URL bar until he turns green. Start up the debugger in Netbeans, and leave it running. Now, every time you load your site it will use Xdebug.

Firefox

To be perfectly honest I haven’t tried it in Firefox, but I know that an extension exists – try Easy Xdebug. If anyone fancies giving a step-by-step guide, then that would be welcome.

5. Command-line debugging

To start a debugging session from a command line script you need to set an environment variable before the PHP executable starts. I find that the easiest way to do this is to create a bash script that starts PHP with this variable set, and put it in /usr/bin/php-xdebug:

#!/bin/bash
export XDEBUG_CONFIG="idekey=netbeans-xdebug"
/usr/bin/php "$@"

Run chmod +x on the new file and run the PHP script with:

php-xdebug myscript.php

Happy debugging!

This tutorial will show you:

• How to add a submodule to your project
• How to clone repositories with submodules
• How to update submodules
• How to manage submodules within submodules (recursive submodules)
• What to do if it all goes wrong

I know that last point is slightly ominous, but we’ll get to that.

Setting Up

For this tutorial you’ll need a Github account. You probably do already, otherwise you wouldn’t be reading this far in. You can either create a repository, or you can just fork my example project, which you can do at  https://github.com/joonty/example. Skip the rest of this section if you are comfortable with forking a repository and cloning into a local copy.

Otherwise, click on the “Fork” button at the top right of the screen, which looks like this:

This will create a copy of the example repo in your account. Then, clone the repo, replacing (username) with your actual username:

jcairns$ git clone git@github.com:(username)/example.git submodule-example

This will clone your version of the project into the directory ‘submodule-example’. Move into this directory and you are ready to go.

Adding a submodule

My example project is a high-powered web application. It’s range of features include:

1. Printing out “Hello, World” as a header

jcairns$ git submodule add (repository) (directory)

This would register the repository as a submodule under the directory specified. Therefore, in the context of this example, we want to add the Doctrine repository as a submodule in the directory ‘doctrine’, using git submodule add:

jcairns$ git submodule add git://github.com/doctrine/doctrine2.git doctrine

This will register doctrine as a submodule within your project and will clone the data into the ‘doctrine’ directory. The command git submodule status will tell you that the submodule has been registered, and which commit it is pointing to in the Doctrine repository:

jcairns$ git submodule status
-15877e14430a316a7576918bc7c996e52d91105d doctrine

Also, to see what changes have been registered in the parent repository, use the git status command:

jcairns$ git status
# On branch master
# Changes to be committed:
#   (use "git reset HEAD ..." to unstage)
#
#	new file:   .gitmodules
#	new file:   doctrine
#

This shows us that two “files” have been modified: ‘.gitmodules’, which holds information about the repository’s submodules; and ‘doctrine’, which is the submodule itself. Git doesn’t track files inside the submodule when you’re in the parent repository, it just sees it as a single file. We’ll touch on that a bit more later. First, we want to save our changes and push it to the remote repository:

Commit Changes

jcairns$ git commit -m 'Added Doctrine submodule'
[master 37f40bb] Added Doctrine submodule
 2 files changed, 4 insertions(+), 0 deletions(-)
 create mode 100644 .gitmodules
 create mode 160000 doctrine

Push to Remote

jcairns$ git push
Counting objects: 4, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 433 bytes, done.
Total 3 (delta 0), reused 0 (delta 0)
To git@github.com:joonty/example.git
   223e6ba..37f40bb  master -> master

If you look at your repository on Github you will be able to see a link to the Doctrine repository in your parent repository, which will look like this:

Doctrine submodule link in Github

Congratulations! You have added a submodule. Now let’s look at cloning repositories that contain submodules.

Cloning a repository with submodules

Let’s try cloning the repository you’ve been working on into a different directory. Move to a directory above the one you’re currently in, and run:

jcairns$ git clone git@github.com:(username)/example.git submodule-clone-example

Again, make sure you replace (username) with your actual username. This will clone the example project to the directory ‘submodule-clone-example’ – move into this directory. If you take a look inside the ‘doctrine’ directory, which is meant to contain our submodule, you’ll see that it’s empty. What’s happened? Has git given up?

No. By default, a git clone won’t pull the submodules along with the parent repository. To pull the Doctrine submodule, you need to run git submodule init and then git submodule update:

Submodule Init

jcairns$ git submodule init
Submodule 'doctrine' (git://github.com/doctrine/doctrine2.git) registered for path 'doctrine'

This registers the submodule in the correct path, ‘doctrine’, but doesn’t clone the code.

Submodule Update

jcairns$ git submodule update
Submodule 'doctrine' (git://github.com/doctrine/doctrine2.git) registered for path 'doctrine'
Jonathan-Cairns-iMac:submodule-example jcairns$ git submodule update
Cloning into doctrine...
remote: Counting objects: 63339, done.
remote: Compressing objects: 100% (16009/16009), done.
remote: Total 63339 (delta 44444), reused 62836 (delta 43982)
Receiving objects: 100% (63339/63339), 16.16 MiB | 712 KiB/s, done.
Resolving deltas: 100% (44444/44444), done.
Submodule path 'doctrine': checked out '15877e14430a316a7576918bc7c996e52d91105d'

This actually pulls the code for the registered submodules. You have now got a working copy of your repository, submodules intact.

Updating a submodule

As I’ve said before, submodules are simply Git repositories inside another: there’s nothing magical about them. Therefore, as long as you are in the submodule directory, all the normal Git actions like push, pull, reset, log, status, etc. work as normal. If you want to make sure that your submodule is bang up to date with the remote repository, simply do a git pull (don’t use submodule!) when you’re in the submodule directory:

jcairns$ cd doctrine
jcairns$ git pull
Already up-to-date.

If it looks like you’re getting an error message saying that you aren’t on any branch, do a git checkout master to fix it.

If your submodule did have some updates when you did a pull then your parent repository will be telling you that there are some changes to commit. The submodule is pointing to a particular commit, and if the commit changes then the parent repository registers the change. If your submodule needs to be at a particular commit to work with your repository you can set it using git reset:

jcairns$ git reset --hard (commit hash)

For example, if we want to fix our version of Doctrine to the most recent tag (currently 2.1.2), we would just need to do:

jcairns$ cd doctrine
jcairns$ git reset --hard 144d0de
HEAD is now at 144d0de Release 2.1.2

We can then go back to the parent directory, and commit it:

jcairns$ cd ..
jcairns$ git commit -am 'Set doctrine version to 2.1.2'

When this is pushed to the remote repository the submodule will be associated with that particular commit. It’s worth mentioning that, if you have others working on the same project, someone else could pull on the submodule and commit the change, thereby changing the submodule commit. But that’s easily fixed – just do the reset again.

It’s also worth noting that, if your submodule is a repository that you have push access to, you can edit, commit and push submodule content completely independently from your parent repository. The only thing that affects the parent is when the submodule is pointing to a different commit, as mentioned previously.

Submodules within submodules

One great feature about submodules is that they can contain submodules themselves. For instance, the Doctrine repository has several submodules, including doctrine-common and dbal.

Let’s go back to the example repository. Currently, Doctrine is registered as a submodule, but none of its submodules have been pulled. In the doctrine directory, type git submodule status:

jcairns$ git submodule status
-3762cec59aaecf1e55ed92b2b0b3e7f2d602d09a lib/vendor/Symfony/Component/Console
-c3e1d03effe339de6940f69a4d0278ea34665702 lib/vendor/Symfony/Component/Yaml
-ef431a14852d7e8f2d0ea789487509ab266e5ce2 lib/vendor/doctrine-common
-f91395b6f469b5076f52fefd64574c443b076485 lib/vendor/doctrine-dbal

This shows that there are four submodules in the doctrine repository. The “-” sign at the beginning of each line shows that the submodules haven’t been downloaded yet. We can run git init and then git update, which would clone all the repositories and put them into the right place. But what about when we’re cloning our repository to another machine? It would get pretty tedious to have to go through all the submodules, performing an init and update as deep as we need.

Fortunately, we can get round this at the point of cloning. We can just use the --recursive option when doing a git clone:

jcairns$ git clone --recursive (repository)

This initialises and pulls all submodules, recursively. Simple!

At some point that I can no longer remember, I thought it would be useful to have a similar thing, but using jQuery selectors instead. For instance, if you want to find out the jQuery selector representation of a particular element of a page, how would you do it? What if you wanted to test a selector on a particular website, and see what it would return?

Enter jTools

jTools is a plugin for Google Chrome that uses jQuery to provide various methods of page analysis on the site you’re currently on, in real time. It currently has two modes:

1. Execute a jQuery selector and highlight the objects on the page that match
2. Hover over elements on a page and see the jQuery selector that represents it

It’s still very much in development at the moment, so I haven’t packed it up as a proper Chrome extension. In fact, the only access to it at the moment is through Github. Here’s how to give it a go.

1. Grab the Code

You need git installed on your machine – follow these instructions if you haven’t got it yet. Then run:

$ git clone git@github.com:joonty/jtools.git

That will grab all the source code.

2. Load in Chrome

Click the spanner (hand wrench for Americans) at the top right of Google Chrome, then go to Tools -> Extensions. Hopefully you’ll see a button saying “Load Unpacked Extension” near the top of the page. If not, click a link saying “Developer Mode” at the right of the page and it should appear. In the file browser, navigate to the directory where you just cloned the source and accept.

This should load the extension into your browser.

3. Try it Out

Reload any of your open tabs to try the extension out. You will see a jQuery logo in the top right of the screen, for inserting jQuery selectors into the current page, and a logo at the bottom right of each page, for analysing the DOM jQuery style.

I might add more information here as the project grows, but I’m just going to leave you to mess around with it for the time being.

4. Collaborate

I’m all for social coding, so for the technical amongst you please feel free to add to the project and work with me on my Git repository.