CakePHP as a Git submodule


This post is based on CakePHP version 1.3. You might be more interested in the CakePHP 2.x version.

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.

CakePHP directory structures

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

# Prevent sensitive data from ending up in your repo

# prevent temporary files from ending up in our repo

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 "bravo-kernel"
git config –-global ""
git init
git add .
git commit -m "initial commit"
git remote add origin
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 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:// 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 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.

Posted in: CakePHP, Git
Tagged with: ,
6 comments on “CakePHP as a Git submodule
  1. TomWS says:

    Thanks for this. I’m new to git and almost as new to cake, so this really opens up some possibilities as I go forward.

  2. TomWS says:

    Extra piece of information for anyone else attempting this. I had a problem running a “cake schema generate” on the console after making this change. It wasn’t using the database connection details in my app/config.

    The root problem seems to be that when running the console, you need to specify the application path relative to the non-standard cake core path used above (or use an absolute path, if desired). Get your path info by running the cake console with no arguments. Here’s what I got:

    Current Paths:
    -app: app
    -working: /var/www/cakesites/artemis2_cakephp_1.3.0/cakephp/app
    -root: /var/www/cakesites/artemis2_cakephp_1.3.0/cakephp
    -core: /var/www/cakesites/artemis2_cakephp_1.3.0/cakephp

    Apparently, the console works relative to the core rather than determining it’s location through the webroot conf line changed above. In my case, I needed to change the command:

    cake schema generate


    cake -app ../app schema generate

    The schema generation worked fine with that change. I suspect, though haven’t tested, that a “cake bake” (as well as the other shells) would also work incorrectly without the added app argument. I’m not sure if one of the other config options in app/webroot/index.php or elsewhere could be changed to make this unnecessary.

  3. Bravo_Kernel says:

    @TomWS: Thanks for commenting, I just bumped into that myself as well.

    I chose to add the migrations plugin as a submodule as well (in the submoduled /cakephp/plugins directory) so I can change both CakePHP and Migration versions as I like.

    Thanks for the comment,

    Funny enough I encountered exactly the same problem as you describe and I can confirm that your solution works.

    I chose to add the Migration Plugin as a submodule as well (below the submoduled CakePHP core /plugins directory). This gives me the option to change both CakePHP as Plugin versions independently.

    If the Migration is not added as a submodule to /cakephp but to your application root the following error will occur:
    Error: Class MigrationShell could not be loaded.

    To add the Migration plugin as a submodule to /cakephp:
    # submodule init
    # git submodule add git:// plugins/migrations

    Make sure the database-account has CREATE rights on the database or the following error will occur:
    Fatal error: Uncaught exception ‘MigrationException’ with message ‘SQL Error: 1142: CREATE command denied to user ‘dbuser’@’localhost’ for table ‘schema_migrations” in /var/www/domain/cakephp/plugins/migrations/libs/model/cake_migration.php:228

    Start enjoying migrations:
    show help: ./cake migration help -app /var/www/domain/app
    full dump ./cake migration generate -app /var/www/domain/app -f

  4. TomWS says:

    Good info since I’m also looking at the Migrations plugin!

    An additional consideration to further muddy the waters, I just noticed yesterday that the CakePHP team is reworking the git repo in preparation for 2.0 work ( Apparently, that means that the submodule command above:

    git submodule add git:// cakephp

    would need to change to:

    git submodule add git:// cakephp

    Being new to git (and VCSs, in general, really), I’m unsure if this means I’m always going to be loading the latest version rather than a known release. I assume that it won’t pull dev and RCs, but I’m too ignorant at this point to know for sure. Need to do a little more reading.

  5. TomWS says:

    Gah! The answer is implied in your instructions above if I would just pay better attention: git checkout origin/1.3

    And your other post on version switching gives more details:


  6. db says:

    Testing your full restore won’t work (as implied) as you’ve .gitignored the /app/config/core.php file. If you import that in from somewhere then things work smoothly. Otherwise, good article! Thanks, it was quite helpful.

1 Pings/Trackbacks for "CakePHP as a Git submodule"