I have recently begun working on a series of modifications for CakePHP. The primary purpose of these modifications is to provide an easier migration path for my old web projects. I have made them available both as a series of patches and as a downloadable Darcs repository.

Updated: 6 Dec 2006

NOTE: Instructions for applying individual diffs found here are incorrect. [Read this][correctinsns] if you want to apply patches individually. This article is kept mostly unedited for archive purposes.

First off, these modifications started out as a set of patches to make porting between my old framework and CakePHP much easier. They may not be useful for you. Another thing to note is that these patches are made against the latest Subversion version of CakePHP. With that in mind, you might be better off using the official releases of CakePHP [found here][cakephp].

Secondly, some of these patches might break compatibility with the official CakePHP. However, I have taken great care to maintain compatibility with the official releases as much as possible. If a patch introduces features or modifications that could break compatibility, it will be indicated in the patch description.

Applying the Patches

You have two options of applying the patches. The recommended (and easiest) way is to download them using [darcs][darcsweb]. The second way is to download CakePHP from the offical Subversion repository and then apply the patches using diff.

Since the second way requires a bit more work, I will describe how to do it first. (EDIT: I highly recommend using the prepatched version found [here][prepatched] instead of applying each patch individually or use the darcs repository.)

Applying Patches with diff

1. Download the patch set [here][diffs]. You can either individually download the patches you need. Or download the tarball all.tar.gz.

2. Download the official CakePHP from the Subversion repository. Instructions can be found [here][cakeman3] (see section 2). Make sure you get the latest revision indicated in the diffs [README.html][diffsreadme]. (EDIT: The README.html now has a table showing which patch should apply cleanly to which SVN revision.)

3. Using the Gnu Patch program, apply the patches.

Assuming you have downloaded the CakePHP and you have it under the directory cake and the patches in the directory immediately above it, here is an example command line session (Unix):

$ cd cake
$ patch -p1 < ../<name of patch>.diff

The patches are numbered sequentially, in the order that they were committed to the darcs repository. So you should apply them in sequence since one patch might depend on another. If one patch does not apply cleanly, you should remove it (EDIT: Or resolve the conflicts manually). Otherwise, you may end up with a broken CakePHP.

Using the darcs Repository

Now for the recommended way of downloading the patches.

1. Get [darcs][darcsweb]. There are binaries for many operating systems, choose one that is appropriate for you.

2. From the command line (Unix), issue the command:

   $ darcs get http://abing.gotdns.com/darcs/repos/cake

   That should pull in all the patches and give you an up-to-date tree. If you only want to pull in a specific patch:

3. From the command line (Unix), issue the command:

   $ darcs get --tag='CakePHP-v-1.1.' http://abing.gotdns.com/darcs/repos/cake

4. Then look at the [ChangeLog][changelog] and search for the patch name that you want to pull.

5. Make sure you are in the local repository directory. From the command line (Unix), issue the command:

   $ darcs pull --patch='PATCH NAME'

Darcs will pull in the patch that matches the PATCH NAME you specified along with any other patches that it depends upon.

A Few Thoughts About Darcs

You may be wondering, CakePHP already uses version control software (Subversion), why use darcs?

I have been using [David's Advanced Version Control System][darcsweb] (darcs) for all of my projects for over two years now. CakePHP uses Subversion, I think only because it works well with Trac. Using darcs instead of subversion is entirely my own choice.

Darcs is what is known as a “Distributed SCM” which is vastly different from the way CVS (and Subversion) does things. There are a few things to note, especially for long-time CVS or Subversion users.

First off, you will notice that there are no revision or version numbers in darcs. It may come as a surprise to you, especially is you have been using CVS or Subversion for a long time. Version numbers are useless under darcs because of its “distributed” nature. Instead we use “Patch Names”. A patch name is just a short string used to identify a specific commit.

Secondly, your copy of the remote repository is a complete repository. Which means you can record or commit your own changes without having to connect to the remote repository. Your recorded patches remain in your repository, unless you send them to me so that I can apply them. This is where the “distributed” nature of darcs comes into play. It allows you to make changes in your local repository and commit them locally, thereby providing you with a complete record of the changes you made.

Lastly, darcs has a feature that reduces the burden of tracking down who made which changes. By setting your name and email address in the _darcs/prefs/author configuration file in your local copy, all commits made in your repository will be tagged with your name and email address. When the ChangeLog is generated, all patches that you send to me that I applied to my repository will automatically contain your name and email address.

Those who are familiar with darcs will probably wonder why I did not use tailor.py to migrate patches back and forth between the Subversion repository and my darcs repository. This is because I do not expect these patches to make it into the mainstream CakePHP code, so why bother? Most of the patches I made are necessary for my purposes, but may not be useful in the general use-cases for CakePHP.

I also wanted to be able to start from a single recent SVN snapshot (I don’t need the pre-1.0 stuff). This reduces the amount of space I need for the repository. I have a 300MB disk quota on the server hosting the remote repository, so every bit of space savings counts. This is also why you will only see the _darcs directory (without the pristine directory) on the server.

Patch Descriptions

Aside from maintaining compatibility with the mainstream CakePHP, I have made it easier to determine what a patch does based on its name. However, one can only say so much in a patch name so a longer description of the patch is necessary. I have made use of the following convention when entering patch descriptions:

[optional introductory text]

Rationale:

[explanation of why this patch is necessary]

Full Description:

[full documentation about what this patch does and what it affects as well API changes that it introduces]

[optional notes on compatibility]

The Future

This is just the beginning of a series of articles and patches for CakePHP as I continue to port my old projects to this new framework. Though I do not really expect these patches to make it into the mainstream CakePHP tree, it would be great if some of the patches make it.

You may also find that some of these patches won’t do anything useful for you. As one saying goes, “If you don’t know what it does, then you probably don’t need it.” This is most certainly true for many of the patches that you will find here. Read the description first if the patch name does not give you enough of an overview as to what a patch does.

[cakephp]: http://cakephp.org/ “CakePHP Official Website” [darcsweb]: http://darcs.net/ “Darcs Website” [cakeman3]: http://manual.cakephp.org/chapter/3 “CakePHP Manual Chapter 3″ [diffs]: http://abing.gotdns.com/cake/diffs/ “CakePHP diffs” [diffsreadme]: http://abing.gotdns.com/cake/diffs/README.html “diffs README.html” [changelog]: http://abing.gotdns.com/cake/diffs/changes.xml “ChangeLog for CakePHP modifications” [correctinsns]: http://abing.gotdns.com/cake/diffs/README.html “Correct way to apply individual patches” [prepatched]: http://abing.gotdns.com/cake/diffs/cake-diffs-latest.tar.gz “Pre-patched CakePHP”

This entry was posted on Sunday, July 9th, 2006 at 5:02 am and is filed under CakePHP, Code and Consequences, PHP. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.