As a committed user of open source technologies, the difference between me using something and not using something is the documentation. Is there documentation for it? Is it easy to find? Does it answer my questions? Is there someone I can call an idiot if I disagree with the level of documentation? These are all very important questions.

My involvement with CakePHP has opened my eyes in terms of what people consider documentation. Me, I’m the type who learns from examples that come with explanations. While API documentation is great, it only becomes useful to me once *I* can figure out how to do something useful with this new technology. I see people on the mailing list for Cake asking for the source code to a sample application, which I immediately file away in my head as “looking for answer to their homework”, and move on. Maybe that’s unfair, but it’s more a reflection of the fact that I tend not to learn anything from having the source code for an application. I learn by getting in there and DOING SOMETHING and figuring out why this goddamn thing is not behaving properly and who do I know who can help me with this problem etc. Learning by mooching, I call it.

So, back to CakePHP. CakePHP had acquired the reputation that the documentation for it sucked. While I did not share that opinion, I can see why people say that. Because most coders are lazy. Seriously. They want solutions handed to them in a form that they can just drop into their application and then get onto the next problem. There are definitely times when I wish someone else could just write this goddamn “alter the football game stats form dynamically via Ajax and send the results to the XML database” code for me. Inevitably, I build the code up from an example stolen via Google into something that both works and that I understand fully. However, most of the time I am content to figure stuff out on my own and ask for help only when stuck. I’m not lazy, but maybe I’m suffering from a bit of the Lake Woebegon effect.

So, things are much better in terms of documentation for CakePHP. Whereas we used to have a manual that only covered 1.1, we now have the amazing CakePHP cookbook that covers both 1.1 and 1.2. If that’s not enough, well, you might actually have to do a little thing I like to call “research”. This gets us to the point of this blog posting. Sometimes you have to stop being lazy and actually think about where you could find an answer.

There are no shortage of blogs that talk about CakePHP. Some of them are even good. Maybe you like the code examples I put up here. People seem to like them enough to comment, so maybe I’m doing something right. Google is your friend to track down blogs that have exactly the type of information that you need: small examples with explanations about how they work.

The CakePHP mailing list is done via Google Groups, so all those posts where I make fun of people for no reason other than my poor self-esteem can be found with a few keywords. But there are a lot of great tips on how to accomplish things using Cake, so a search of the google group will find lots of good information.

The Bakery is another good source of CakePHP info, consisting of all sorts of small articles along with comments. It has a search function as well, but could easily be considered YACB (Yet Another Cake Blog). Again, perfect for people with the same learning style as me: short examples with explanations of how it was done.

Finally, we come to one of the more unorthodox documentation sources: the unit tests for CakePHP. CakePHP has some really good unit test coverage, although I sometimes wonder if you can really say that a piece of code works properly if it passes all the unit tests associated with it. This is by no means a phenomenon limited to CakePHP, it happens everywhere there are unit tests. Sometimes you can’t figure out a test that makes something break. It happens, so please do not misinterpret my thoughts on this. Unit tests are good, and the amount of tests that CakePHP has in place is awesome and perfect example of a cohesive development team. Automated testing is a goal worth striving for, don’t let anyone else tell you otherwise. I’m in the early phases of automated testing for a work project on the integration side of things because I’m tired of always running through the same damn tests by hand all the time to make sure something that I wrote didn’t break things. Tips on what good browser-based solutions are out there would be appreciated. Other than telling me to use Selenium. A solution that is tailored to the framework I have been forced to use would be even better.

Okay, back on topic. Since the unit tests cover so much of what CakePHP can do, what better way to see examples of how to actual do things? My work on fiddling around with new console functionality showed me that I had no idea of how to create unit tests for my console work. That led to discussions with people on the best way to do testing of console functionality. Which leads to changes in the console code itself to make it easier to test certain things. But at least when I’m ready to get back to doing that console work I can see if doing testing for it has become easier.

So, having been told all the stuff above, how can anyone who is not simply lazy say that the documentation for CakePHP sucks?!?

Anyhow, I saw a post the other day showing how to create an iPhone-optimized version of your Symfony app. Yawn. Cake had that a year ago.. No code provided *but* the article does tell you exactly how he did it.

But that’s really the key here. You don’t need to do anything special to make a web-based app in CakePHP that will work nicely on your iPhone. Contrast that to all the stuff I see in that article that you need to do. Off the top of my head, it seems to me the best way to do it is:

• create CSS and layouts for regular and iPhone versions of your application
• do a check in your beforeFilter() method where you check the User-Agent
• pass that info to your actions, and render whichever layout+CSS you need

Compare the Symfony article to the CakePHP article plus my notes, and let me know what you think.

While I really prefer to use tools like this for deployment, I understand that not everyone wants to mess with standalone programs and configuration files. I’ve been asked before about Cake-specific deployment techniques, so I figure the easiest way is to see about adding a task to the Cake console. Let’s call this ‘cake deploy’.

As I explained on the mailing list I am looking for opinions on what sort of things should be part of the ‘cake deploy’ task. Right now, my thoughts are as follows:

• cake deploy config

– setup and edit configuration parameters. Initially I thought of setting things like transport method (ssh, ftp), logins and passwords, remote location, source directory, and destination directory. The configuration file would be stored locally in APP/config

• cake deploy – seems pretty self-explanatory to me.

In the RFC thread on the CakePHP mailing list, someone mentioned they’d like to see rsync, but I’m trying to avoid having to external programs required to make the deployment work. Or, at least, use as few as possible. Anyhow, if you have any thoughts on this feel free to add them to the comments.

Anyhow, anyone who uses CakePHP or wants to help out can definitely get involved in the process by:

• Entering bugs into CakePHP’s trac if they don’t see them in there
• Contributing tests and/or patches for existing bugs
• Testing out the bleeding-edge versions of CakePHP that you can get from the SVN repository

There has been a lot of debate on the mailing list about both the direction of the project and the attitude of people on the mailing list. Well, as one of the people who gets to be involved in both sides (albeit a minor role in terms of contributing code) I can tell you that the project will continue moving forward, building on all the traction CakePHP has gotten. Maybe 1.2 has dragged on for a while, but isn’t that just a number anyway? Would people be reacting if it was Cake 1.7.2 or something like that?

What people don’t always see is the amount of work that goes into CakePHP by developers. Every morning when I log into my account on my MacBook, I update my copy of CakePHP from SVN. 99.999% of the time there is an update. These days, tests are being written like crazy and Tim’s awesome work in creating code coverage information and those things can only help the project as a whole get better. These are exciting times for anyone connected to the project, no doubt about that. No amount of CakePHP haters (you know who you are) are going to change that.

Secondly, people have to understand that a mailing list full of a lot of technical, highly-skilled people is not a friendly place for beginners. Sad, but true. I have answered many questions on the mailing list, some of them properly and some of them, well, let’s just say my nickname of GrumpyCanuck has been well-placed. Can we all be civil? Probably not. Should we be civil? Maybe. I think anyone who doesn’t understand the dynamics of the CakePHP list itself should go and read this. Forewarned is forearmed.

As amazing as the built-in CakePHP pagination helper is, sometimes you have to create your own custom queries for data you wish to paginate. For the simulation baseball league site I wanted to be create an admin area where I could paginate through the series instead of individual games. It took some digging around with google, but I found some info in a thread (thanks to Baz for contributing that tidbit to the thread) on how to do just that.

Okay, so it turns out that the paginate() method that is used to generate the data that you (oddly enough) paginate through takes the same arguments as Model::findAll(). So, if you want to use your own query, you simply create a 'paginate' method for your model. In my case, I needed a query that would group things together (because a 'series' is simply a collection of all games between two teams in a particular week). The query stuff I did is ugly because there currently is no support 'group by' in CakePHP (although that would be a very interesting project to tackle). So, here's what I did:

So, that's the first part of the custom query stuff taken care off. Next, I needed to be able to properly count the number of 'series' so that the numbers (you know, that stuff that says 'page 7 of 23') come out properly. Again, you can override the paginateCount() method if you need to. It uses the same parameters as Model::findCount(). Now, the custom query I'm using below is Postgres-specific, so YMMV:

So there you have it. Hope this helps out anyone who's been trying to figure out how to use custom queries with their pagination.

But I digress. With a ton of help from Andy Dawson (AD7Six) the documentation for CakePHP 1.2 has moved forward immensely with the unveiling of the CakePHP Cookbook. It's a combination of manual and wiki, where people can flesh out the manual and make comments on the methods in there. I have been quite harsh on people who have called for a CakePHP wiki in the past, because they tend to be a mess. This project is just different enough that I cannot stop recommending people to use the cookbook when searching for answers to their CakePHP problems. In fact, if you can contribute by moving entries over from the temporary documentation to the cookbook, _psychic_ will have one less thing to do.

From now on, whenever I find a solution to something in CakePHP I will not only post it here on my blog (because, after all, I am still an egomaniac) I will also create an entry in the Cookbook if it's appropriate. Lucky for you, contributions are anonymous so you won't be able to tell what I've put in there. My first contribution has been to get my documentation on the Auth component in there (although my simple user registration stuff isn't in there), and Baz added his stuff he's been doing with Auth as well.

So, no more excuses about lack of documentation! Anyone who registers and account can create entries in the manual, and everyone who complains about on the mailing list will be told to go look at the cookbook and contribute changes and comments to it.

So, I was trying to figure out how to make a test for this so I could file a bug (CakePHP not finding the proper name of the Postgres sequence for a table) when I tracked down nate on IM to whine to him about this problem, he started bugging me about "not paying attention" when looking around in code to try and track down what I thought was a bug. If I had looked at the API a little closer I would've been steered towards the solution he gave me.

Lucky for me, it turns out that the solution (for now) to the problem was to simply add the name of the sequence for that table as a variable to the model definition.

This confirmed to me that my new-found respect for trying to come up with the simplest solution to a problem is the correct way to do so. Since my head is full of all sorts of nonsense (work items, family life, baseball stats, old Dungeons & Dragons adventures from my teenage years) I find that at times I am better served by taking the time to think about the problem rather than start digging around. Especially when it comes to code that was well-written an has been tested by lots of people, like the overwhelming majority of CakePHP's core code.

Thanks again to nate for proving to me that the Devil's in the details. And continuing to make me feel stupid.

I'm going to be flying down Tuesday night, getting in around midnight and flying out Friday morning (it's looking like a 10:30 departure). So that's two full days at the conference, which is okay. Now, if anyone is going down there and could use a roomie to help cut down on costs let me know.

Okay, that's great but WHY does it work? Normally, when you do pagination you have to pass it a bunch of different parameters so it knows what records you wish to include as part of the data set you want to paginate over. In this example, you've already established that Tag HABTM Post. In order for the pagination query to correctly pull out the Posts that are also associated with the Tag, you need to merge the parameters you passed in to your 'paginate' method so that the CakePHP data mapping functionality knows what associated records are to be included. Then run your $this->findByName(...) and you're all set.