Using composer in CakePHP 3.0

For 3.0 the team and I are re-visiting how we’ll recommend installing CakePHP, and as always I wanted to try to provide context on what my thoughts are, and get some feedback on the plans.

Background & context

CakePHP is currently availiable in a few different ways. Generally people either download zip files, or clone the repository. Both of these methods provide a quick easy way to get started. The easy start has been a huge boon for CakePHP as people can start coding and seeing results in < 5 minutes. While this is great for people starting with CakePHP, advanced installation configurations are more problematic. You could use the PEAR package, but system wide installations have a number of problems. Other solutions often involve special directory layouts, or symlinks.

Problems with the current solutions

Three simple words – multiple version hell. Having more than one version of CakePHP installed via PEAR is impossible, without advanced knowledge of how PEAR works. Multiple versions of CakePHP installed system wide makes using include_path and the standard cake executable painful. You end up having to create aliases for cake and either hard-coding paths to CakePHP, or doing odd filesystem layouts like putting your apps inside a CakePHP. I personally find these solutions icky, and want a better way.

Composer as a solution

If you haven’t heard of composer, its a package manager for PHP. It borrows many ideas from npm and uses basic json files for package definitions. Composer packages are generally published on the packagist, but can also be published & installed from other servers. Composer provides a neatly packaged solution for both installing CakePHP, plugins & vendor libraries. In this article, I’m only going to cover installing CakePHP. I’ll cover plugins and vendor libraries in a separate post. Using composer to install CakePHP has a number of benefits in my mind:

  • There would be one unified way to install all the dependencies for an application. Plugins, vendor libraries, and PEAR packages could be installed via composer.
  • composer/installers already handles CakePHP plugins.
  • Composer provides easy access to excellent libraries created outside the CakePHP community.

Installing CakePHP

I think there are a two main user groups that need to be accomodated when considering installation:

  • The new developer – He doesn’t want to use command line to set things up, he doesn’t know what git is and doesn’t have the time to figure it out. He’s heard of frameworks, and wants to try one out. Ideally he’d download a zip file and get started.
  • The advanced user – She is comfortable using git, or other cli tools. She wants to get started on a new project and would like a simple way to do that.

With those two user types in mind, I think the different recommended ways to install CakePHP would be as follows.

Installing from a zip file

A zipfile should and hopefully will always be offered as an installation method. Having a simple 1 minute setup has been a huge advantage in the past, and will continue to be one in the future. The install story should look something like the following:

  • Download zipfile
  • Unpack in webserver document root.
  • View traffic light homepage.

The zipfile installation method would look very much like it does today, containing the App and lib/Cake directories. When it comes time to update CakePHP, the developer would simply re-download Cakephp and replace the lib directory.

Using composer to create new applications

Composer provides the create-project command for creating new projects. CakePHP could use this feature to provide an application skeleton that is easily setup using:

Show Plain Text
  1. composer.phar create-project cakephp/app my_new_app

This also partially or entirely replaces cake bake project. The install story for using composer should look something like:

  • Download & install composer curl -s | php.
  • Run composer.phar create-project cakephp/app my_new_app inside the webserver document root.
  • View traffic light homepage.

Updates using composer are as simple as updating your application’s composer.json and running composer.phar install.

No more system wide installation

Both installation methods would contain a local CakePHP, and installing CakePHP as a systemwide library would no longer be a recommended method. This helps avoid a number of problems with systemwide dependencies that are always painful when using tools like pear or easy_install. While local installs use more disk space, they simplify life considerably and are well worth the extra bits in my mind.

Repository changes required

In order to facilitate ease of creating separate packages for CakePHP the framework and an application skeleton for use with composer create-project I’m suggesting:

  • Create new repos for cakephp/framework and cakephp/app.
  • Use the existing cakephp/cakephp as the master repository. Automated subtree-splits would be used to update the framework & app repositories.

From what I can tell, composer does not support creating multiple packages from a single repository. This is the primary reason that two new repositories are required.

Maintaining the existing cakephp/cakephp repository is required for compatibly with existing clones and familiarity with existing developers.

The vendor directory issue

CakePHP uses Vendor, while composer prefers to use vendor. I think renaming the CakePHP directory to vendor will make life easier overall as leveraging the generated autoloader simplifies CakePHP and application code.

So those are my thoughts/plans as they stand. The proposed changes I did have been merged in, and will be part of CakePHP 3.0. You can see the code as it stands in the cakephp github repository

2013-06-02 Updated links.


I have a set of Bash scripts for CakePHP and nginx configuration. The CakePHP one is named “baker” and does cloning/pulling the git repository, making local branches tracking the upstream release branches, and symlinking ~/cakeroot/version/bake to ~/bin/bake.

Gordon on 11/10/12

Gordon: That’s a nice way to do things. However, I think composer would make that workflow even simpler. The cake console would be available in $app/Console/cake and installing dependencies would be as simple as composer install in the application directory.

mark story on 11/11/12

I’m wondering how to use composer for an CakePHP app for installing and updating. The installation should be straight forward. But the update/patching is the tricky part. Is there a nice way to detect user changes in Config/core.php or Config/bootstrap.php on an update action?

E.g. CakePHP provides a newer version of Config/core.php with additional required settings, but the user changed already the Security.salt settings. It would be nice to merge the upstream with the current file.

Xemle on 11/11/12

+1 for Xemle comment. It’s always been a trouble for me to update the config.php with new settings or changed settings in default config.php.

jodator on 11/12/12

+1 for using Composer, along with PSR-0 and PSR-1 recommendations, taking dependency management for PHP from painful to a breeze.

@xemle I think your app’s Config/core.php would lie outside composer’s remit. There are plenty of diff tools that will make this task easier. In my experience the core config file doesn’t change that often.

Robert on 11/14/12

Just a short note regarding vendor/Vendor, you can use this in your composer.json to change it: config “vendor-dir”: “Vendor” }

That said, if the difference is only one of case, maybe it’s best to change your convention to vendor and keep the defaults. The more projects using the convention the better IMO for consistency.

Jordi Boggiano on 11/16/12

Jordi Boggiano: Great to know, I missed that reading the composer docs the first time through. Like you said, since its a minor casing issue, I think switching is worth the effort. Improving consistency is worth working towards.

mark story on 11/17/12

+1 on changing to `vendor`. convention over configuration.

Kevin van Zonneveld on 11/29/12

Mark: thanks for pushing this forward! PHP dev here who loves NPM, is excited about Composer, and would love to be able to list all application plugin/behavior/core framework/etc. deps in a composer.json like a hip kewl JS developer. :)

I’ve used Composer for a work project; just including Slim & Respect\Validation but it was very nice. :) Viva modern dependency management in PHP!

Sequoia McDowell on 4/4/13

Hi Mark,

The link to your GitHub fork of CakePHP with added composer goodness is broken.

Have you made any further progress with a composer based CakePHP install since this article?

Thanks for all your CakePHP work by the way,


Scott Donnelly on 5/26/13

Scott: Thanks for pointing that out. The changes have been merged into the primary 3.0 branch and can be found there now.

mark story on 6/2/13

This is a topic which is near to my heart… Take care!
Where are your contact details though?

Chaise Panton pas cher on 7/3/13

this was actually informative – not like most of what i see online. sharing :)

Zach Smith on 8/5/13

quote: I’m only going to cover installing CakePHP. I’ll cover plugins and vendor libraries in a separate post.

Hey Mark, you got a post about plugins and composer for cake 3? I couldn’t find it ;)



Bob on 2/26/15

i have been using cakephp for while with several sites. i have never used composer but thought i would start.

first, its not clear if composer is :

* downloading the cakephp 3.0 install file and then installing it


* installing previously downloaded cakephp 3.0 install file

also its not clear to me what the “cakephp/app my_new_app” refers to?

* is the “cakephp” intended to tell composer what package to download and install (or just to install)?

* is the whole thing “cakephp/app my_new_app” a folder reference? if so, i am a bit confused as when I normally install cakephp, i put the cakephp files into domain root and that is where the “app” folder is eg its domain root/app

genoki on 6/21/15

genoki: Composer will download a zip file of the application skeleton, and then download zip files for each of the dependencies. The @cakephp/app@ part is the package name for the application skeleton. The only real folder path in that example is @my_new_app@.

mark story on 7/10/15

Question: while creating a plugin should I have my own vendor and dependencies included in my plugin? or is responsibility of the app that will use my plugin to have all dependencies in its own vendor directory.

My guess is that a plugin should by self contain and auto sufficient, should it include the cakephp framework within it?

I came acrross this problems while trying to test it , and found out that a needed to test it from within an application. Whats the best practices regarding this issues? Canyou point me to some resources

Thank you!

Jorge Ramirez on 7/13/17

Comments are not open at this time.