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:

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

• Download & install composer curl -s https://getcomposer.org/installer | 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.