debuggable

I originally wanted to write a complete guide to studying the CakePHP source code today, but this 2 hours monster of a post got into the way. So therefor I decided to split it up in two (or maybe more) parts.

Why study the code if it just works?

If you are already convinced you want to learn more about the CakePHP core just skip this section, if not keep reading.

When hanging out in #cakephp I usally try to answer questions people have as good as I can. A lot of the times I have no idea what the answer is and in most cases the fastest way to find out is by looking at the core code. Ok, the manual is pretty decent these days and I would recommend most people to look for an answer in there first. But if you take the time to study the core code, you'll be able to answer almost any question by yourself, no matter if it has been answered somewhere before. Another big advantage is that you can start to enjoy some of the useful & undocumented functionality hidden in the core files most people don't know about. Very few of you will know that there is a Configure Singleton class that you can use to share & manipulate variable values or other information throughout all parts of you application or that you can use the ClassRegistry to register objects you want to be globally accessible. Ok a lot of those things you'll never need or shouold be treated carefully in order to not break the MVC pattern, but hey some of this stuff is damn useful. But the main advantage you should keep in mind, is that you cannot write a really big & good application if you lack the understanding how the framework behind it works. You might open your app to security issues because you are not fully aware of what requestAction does, or because you simply thought CakePHP would automatically sanitize a certain value for you. So knowing the framework will help you to write better apps.

But not only that, one of my favourite parts about reading the framework, was learning how to write easy to read and effective php code. Ok, some parts are rather cryptic and not easy to decipher, but most of them are delightful and should help you to become a better programmer. Oh and also make sure to check out the coding standards used for CakePHP. Even so at some point they broke up with the braces style recommend in there (I liked the old one better), it should help you to read the code and to write better code yourself.

But alright, let's make our first steps in the beautiful code of CakePHP:

First things first, /app/webroot/index.php

The first file you should check out is the one that actually get's called first when a CakePHP site is being requested. It's the /app/webroot/index.php file and it's main purpose is to define the most important path's of the folder layout, you can find some information about that in the manual. After that the $_GET['url'] value is used to invoke the Dispatcher class (/cake/dispatcher.php). There is also a little if statement checking if this value is 'favicon.ico' which can be used to bootstrap CakePHP without invoking a Dispatcher request, which is handy if you want to use CakePHP with an existing CMS like drupal or wordpress. The last thing happening in here is always a check if DEBUG is > 0, and if so, the execution time of this request is added as a hidden html comment to the source of your site.

The heart of CakePHP - The Dispatcher

Alright, you might have heard of this class before as it is the most important part of CakePHP. If it wasn't for the Dispatcher, none of your sites would ever render. It is the responsibility of the Dispatcher, together with the Router (/cake/libs/router.php) to turn your '/posts/index'-like requests into action. Action in this case means to figure out what Controller to use, setting this controller up (loading Models, Components, etc.), invoking possible error pages and handling a couple other things you don't even know about existing ; ).

As I'm running out of time for today, most of the Dispatcher functionality will be covered in Part II. For now I just want to tell you how to use the Disaptcher from any part your application.

But First of all: in most situations Object/Controller::requestAction() will be what you should use when trying to call another action inside one of your Controllers. However, there are situations where you want a little bit more control and use the Dispatcher directly. In those cases you create an instance of the Dispatcher and call the Dispatcher::dispatch() function like this:

This will have the same effect as calling /posts/index via your browser and output the view directly where you place this call. So if you call the Dispatcher like this from within another action you'll probably see two pages being returned instead of one, causing ugly results. If you use the Dispatcher like this, in most case you will want to call ob_start() before and ob_get_clean() afterwards to tunnel the output into a variable, rather then directly echo'ing it out.

Another neat feature of the Dispatcher::dispatch() function is that you can set a 2nd parameter called $additionalParams ($extra for requestAction), where you can set things like the layout, form/url data or any other information you want to make available via $this->params in the invoked Controller.

Ok, more good stuff will be coming tomorrow and if you have any questions so far, feel free to ask. Oh and while reading this "Learning from the CakePHP source code"-series, please keep one thing in mind: 99% of what I know about the core code comes from my own efforts of reading and playing around with it. I might be sometimes wrong about the exact interpreation or best use of a function/class/whatever, so if you know more then I do (maybe because you are a dev ^^), please let me know so I can correct errors easily.

--Felix Geisendörfer aka the_undefined