CakePHP as a Git submodule

After switching to Git as the code-versioning system for my CakePHP applications I had to figure out a way to set up CakePHP as a Git submodule for my projects. Using the Cake core as a submodule should provide us with a lot of handy Git benefits like:

• no need to maintain a copy of the CakePHP framework in our repository
• very small footprint for our application repository
• easily switch between various CakePHP versions
• ability to restore a complete working Cake app in seconds

This tutorial provides you with a complete step-by-step walkthrough on how to set it all up but assumes that you:

• already have some (very basic) experience using Git
• have made a complete backup of your webdirectory
• have created a Github repository (called test in this tutorial)
• have all the neccessary Github SSH-keys ready

The goal

Hopefully the following picture will make clear what we are trying to achieve here.

According to my Google searches most people will take the easy route and will end up storing the entire “Default CakePHP structure” into their Git repository.

In our case we are only interested in storing the “green blocks” into our repository because these are the only files that will actually be edited. Simply put the Cake core (the red block) will be added as a Git submodule which is basically just a reference to a certain version of another project’s repository.

Allright, that’s enough intro talking so log on to your (remote) webserver and get started with the dirty work.

Prepare the repository structure

To create a lean and mean repository we will delete the CakePHP core directory from our webdirectory  (and set up a .gitignore file while we’re at it).

cd /var/www/yourcakesite
rm cake/ -rf
echo My cool CakePHP app > README
touch .gitignore

Now paste the following lines into .gitignore to prevent your database passwords and temp files from appearing in the repository.

# The CakePHP framework will be added as /cakephp so this entry just
# prevents us from accidentally commiting the default /cake location
/cake

# Prevent sensitive data from ending up in your repo
/app/config/database.php
/app/config/core.php

# prevent temporary files from ending up in our repo
/app/tmp/cache/persistent/cake_*
/app/tmp/logs/*.log

Create the repository (git push)

Now that we have our directory structure ready it’s time to push it to our repository (the inital commit).

cd /var/www/yourcakesite
git config –-global user.name "bravo-kernel"
git config –-global user.email "bravo@kernel.com"
git init
git add .
git commit -m "initial commit"
git remote add origin git@github.com:bravo-kernel/test.git
git push origin master

Login to your Github account, take a look at your repository and enjoy the moment

Test the repository (git pull)

To get a bit of confidence in our repository we will delete all content in the webdirectory and then restore it from the repository.

cd /var/www/yourcakesite
rm -rf * .??*
ls -al
git init
git remote add origin git@github.com:bravo-kernel/test.git
git pull origin master
ls -al

Take a look at your application directory to verify that everything is restored as expected.

Add CakePHP as a submodule

An example says more than a thousand words so here we go.

cd /var/www/yourcakesite
git submodule add git://github.com/cakephp/cakephp1x.git cakephp
git submodule init
git submodule update
cd cakephp/
git checkout origin/1.3

Check out your webdirectory again. If things went right you should now have a cakephp directory with (at the time of writing) a full clone of the official CakePHP v1.3-RC3 repository.

Save the submodule

Because we only want to set up the submodule once it is time to commit (save) the new submodule to our repository.

cd /var/www/yourcakesite
git status
git commit .
git push origin master

Log in to Github and check your repository for a cakephp directory (there should be a green arrow on the folder icon indicating that we are pointing to an external project).

Fix your CakePHP app

Your Cake 1.3 framework is now present on the webserver and is properly set up as a Git submodule. However, your Cake app is not aware of all the voodoo that just happened so browsing to your website will give you a lot of include errors.

Fix the errors by changing the constant in /app/webroot/index.php to the line below:

define('CAKE_CORE_INCLUDE_PATH', ROOT . DS . 'cakephp');

Browse to your website again to see a CakePHP website running on v1.3-RC3. Note: make sure to commit the changed index.php so this will be a one-time action.

Test a full restore

Things are going so well that we might as well do a final test. Delete everything from your webserver directory and then restore a fully working app running the 1.3-RC3 version of the CakePHP framework. This should be very easy now.

cd /var/www/yourcakesite
rm -rf * .??*
ls -al
git init
git remote add origin git@github.com:bravo-kernel/test.git
git pull origin master
git submodule init
git submodule update
ls -al

Allright, fire up your browser and visit your website. There should be a fully restored (and working) version of your Cake app using the CakePHP v1.3 framework.

Final note

Now that we have added CakePHP as a submodule a multitude of Git possibilities are at our hands. These will not be covered in this tutorial but think think about aspects like switching CakePHP versions on-the-fly and totally removing the submodule from your repository.

If you have any comments please let me know.