A friend of mine is working on a website for a local realty agent. Since the website will display data about properties that the realtor is handling, I suggested we build it on CakePHP and get some cool features as a bonus. As a bonus he’d learn some of the CakePHP internals. After having set up the database, models, controllers and admin routing and various UI-related matters, we were faced with a very interesting problem:

How do you paginate the results of a search query?

I am sure this has been addressed many times, but I wanted to give a personal taste to the answer. So I read and thought a lot bout this. The real problem I was facing is that the application won’t know about the search query in the subsequent pages of results. This is of course unless you make use of HTTP GET for your search requests. CakePHP also provides nice SEO friendly URL and I didn’t want to give that up. What’s more, HTTP GET is not the right solution because:

Good web development practices demand that HTTP GET requests always present the same data and never alter them.

Search results change with time, so there is no guarantee that the data is the same, even for the same search query. Just imagine for a moment going back to a blog and performing a search for some article’s keywords. You will get that article in your search results, but there may be other (newer) articles containing the same term (let alone a web app where a real estate agent will be updating realties each day). This is why using HTTP GET is considered Bad Practice™ and was out of our line of action.

Since HTTP is a stateless protocol and we cannot or better, choose not to use GET parameters to store the search query, the only way for us to persist data during subsequent requests (different pages of search results) is to use the PHP Session to store the search query.

The Session

The session is a mechanism that wants to make up for HTTP’s stateless nature. A session is unique for every user or, better put, every browser that requests the web pages. Every web programming language offers tools to store, retrieve and delete data relative to a user’s (i.e. browser’s session).

Our plan is to store search query data in the session. CakePHP offers a Session Component that can be used the CakePHP-way. You can even store and retrieve arrays in the session, which does came in handy, as we will see.

The Solution

To make the long story short (or is it to late for that?) the adapted solution is the following:

1. On first request (POST action), use Session component to store search conditions and then show the first page of search results.
2. On subsequent requests (GET action), use Session component to retrieve search conditions and hand them over to the paginator.

Before going into the code, I’d like to shed some light into the application structure itself. The controller that’s going to handle the search requests is PropertiesController. PropertyModel is the relative Model.

The search form is simplified to include the following criteria:

• City of property
• Type of property
• Room count
• Floor count

Data coming from the POST request is stored into Session variables using dot notation. Dot notation (i.e. Properties.floor_count will allow us to retrieve an associative array from the Session (look at line 41). In lines 45-47 we manipulate the associative array retrieved from the session and pass it as a $conditions argument to the paginator (line 52).

<?php
class PropertiesController extends AppController{

	// Session is already included in your AppController
	// this is for illustration purposes only
	$uses = array( "Session", /*...*/ );

	function search(){
		// Make sure some data has been posted
		if( ! empty( $this->data ) ){
			// Delete what was previously stored in the session,
			// this is a new query
			$this->Session->delete('Property');

			// Save search criteria to session
			$city_id = $this->data[ 'Property' ][ 'city_id' ];
			if( $city_id )
				$this->Session->write('Property.city_id', $city_id);

			$type = $this->data[ 'Property' ][ 'type_id' ];
			if ( $type != 0 )
				$this->Session->write( 'Property.type_id', $type );

			$floor_count = $this->data[ 'Property' ][ 'floor_count' ];
			if( $floor_count )
				$this->Session->write( 'Property.floor_count', $floor_count );

			$room_count = $this->data[ 'Property' ][ 'room_count' ];
			if ( $room_count )
				$this->Session->write( 'Property.room_count', $room_count );
		}

		if(  ! $this->Session->check( 'Property' ) ){
			// If no search conditions have been provided
			// set a flash message and redirect to homepage
			$this->Session->setFlash('Provide some search criteria!', true);
			$this->redirect(array('controller'=>'pages', 'action'=>'home'));
		}

		// Now, we are sure to have some search criteria
		$conditions = $this->Session->read( 'Property' );

		// fill up conditions_array
		$conditions_array = array();
		foreach( $conditions as $key => $val ){
			// dot notation for: Model.attribute
			$conditions_array[ 'Property.' . $key ] = $val;
		}

		// Now we provide the search conditions and call the paginator
		$this->paginate  = array(
			'conditions' => $conditions_array,
			'limit' => '2'
		);
		$properties = $this->paginate('Property');
		$this->set(compact('properties'));
		$this->render('search', 'public');
	}
}

After having gone through all this, it seems pretty straightforward. There is one catch: for the purposes of this post, I have not included any additional data sanitizing apart from that provided by CakePHP’s ORM. If you intend to use this code in any real web applications, please read through Data Sanitizing chapter of the CakePHP Book to understand what is sanitized and what’s not.

As a final note, there are also free benefits coming out of this solution, like: Search History and/or Search suggestions for the user, but another post is needed to talk about that.

As I had little experience with site5 hosting at the time, I went on to search the web (as well as their user forums) for guides on working with CakePHP. As strange as it may seem, different users were complaining that they were not able to install CakePHP on a site5 subdomain.

I can only assume here, but it may be related with the default cPanel way to add a subdomain which is to just add a redirect to ~/public_html/subdomain for http://subdomain.mydomain.com, which is the same thing as http://mydomain.com/subdomain. Now, this is not the way I configure my subdomains, I hate cluttering of the public_html directory, so I did not try this at all. Instead I create a webdir directory on my home and host all my add-on domains and subdomains under that directory, explicitly telling cPanel where the root location of every subdomain is.

The Fast-track

• On Site5 cPanel:
  • create subdomain
  • create DB for cakephp (remember user/pass)
• On Site5 shell
  • Checkout CakePHP from https://trac.cakephp.org/
  • Move app directory to webdir/cake
  • Move .htaccess file to webdir/cake
  • fix webroot/index.php so it knows where cake and your app directories are located

Step-by-step guide

First things first, log in to cPanel for your site5 account and go to Subdomains. Create a subdomain:

Subdomain: cake
Directory Root: web/cake

This will create a new directory ~/web/cake on your site5 home and configure the Apache web server to serve files from this directory for every http://cake.yourdomain.com request. Keep in mind that ~/web/cake will be the working directory for your CakePHP application.

The next step is to create a database (MySQL in this case) for CakePHP and configure a user for that database. Return to the “Home” view of your cPanel administration interface and then go to “MySQL database wizard”. Enter

New Database: cakedb

You can also take a look at my screenshot for cPanel DB name selection and then click Next. On the next screen enter

Username: cakeusr
Password: cakepass
Password (Again): cakepass

Again there is a screenshot for cPanel DB username/password selection.

Before clicking “Next Step” remember that this is a guide, you should replace the default values that I am providing with proper username and password values. Choose a strong password, or use the “Generate Password” button to generate a strong password. This is crucial to the security of your web app! After having considered this, click on “Next Step”.

On the following screen select all that apply or, if you want to give cakeusr full access to the database click on “ALL PRIVILEGES”. Here is another screenshot for cPanel DB privileges selection, where I have given all privileges to the database user. When you are done click on ‘Next Step’.

Ta-Da! We’re done with the cPanel, you will see a screen like:

Now log in to the site5 console via your SSH client of choice. I simply use the terminal on Unix like systems, but if you are using Windows, PuTTY seems to be the preferred choice.

Once you are logged in your account you should get a copy of CakePHP. I tend to check out a copy from their SVN repository, because it allows simple updating. If you prefer to just download CakePHP, you can get a copy from the CakePHP website.

For the subversion checkout:

mkdir -p ~/lib/php/ #  create a directory for php libraries
cd ~/lib/php/
svn co https://svn.cakephp.org/repo/trunk/cake/1.2.x.x cake

With this we are creating a a directory for php libraries where we are also storing the CakePHP framework checked out from the subversion repository. If you downloaded the zip distribution, unzip it and store it on ~/lib/php/ to follow with this guide.

A CakePHP application is served from the app directory, so we need to put that particular directory (and the .htaccess file) under the webroot of our subdomain (~/web/cake) so it can be served by Apache.

mv ~/lib/php/cake/app ~/web/cake/
mv ~/lib/php/cake/.htaccess ~/web/cake/

Now, all we need to do is tell the CakePHP application where the cake distribution is. To do that we have to edit the ~/web/cake/app/webroot/index.php file.

cd ~/web/cake/app/webroot
vim index.php

Here is my index.php file, don’t forget to change the 3rd line:

<?php
//TODO: change the following to your Site5 user
$site5user = 'YOUR_SITE5_USERNAME';

/**
 * Use the DS to separate the directories in other defines
 */
	if (!defined('DS')) {
		define('DS', DIRECTORY_SEPARATOR);
	}
/**
 * These defines should only be edited if you have cake installed in
 * a directory layout other than the way it is distributed.
 * When using custom settings be sure to use the DS and do not add a trailing DS.
 */

/**
 * The full path to the directory which holds "app", WITHOUT a trailing DS.
 */
	if (!defined('ROOT')) {
		define('ROOT', DS.'home'.DS.$site5user.DS.'web'.DS.'cake');
	}
/**
 * The actual directory name for the "app".
 */
	if (!defined('APP_DIR')) {
		define('APP_DIR', 'app');
	}
/**
 * The absolute path to the "cake" directory, WITHOUT a trailing DS.
 */
	if (!defined('CAKE_CORE_INCLUDE_PATH')) {
		define('CAKE_CORE_INCLUDE_PATH', DS.'home'.DS.$site5user.DS.'lib'.DS.'php'.DS.'cake');
	}

/**
 * Editing below this line should NOT be necessary.
 * Change at your own risk.
 */
	if (!defined('WEBROOT_DIR')) {
		define('WEBROOT_DIR', basename(dirname(__FILE__)));
	}
	if (!defined('WWW_ROOT')) {
		define('WWW_ROOT', dirname(__FILE__) . DS);
	}
	if (!defined('CORE_PATH')) {
		if (function_exists('ini_set') && ini_set('include_path', CAKE_CORE_INCLUDE_PATH . PATH_SEPARATOR . ROOT . DS . APP_DIR . DS . PATH_SEPARATOR . ini_get('include_path'))) {
			define('APP_PATH', null);
			define('CORE_PATH', null);
		} else {
			define('APP_PATH', ROOT . DS . APP_DIR . DS);
			define('CORE_PATH', CAKE_CORE_INCLUDE_PATH . DS);
		}
	}
	if (!include(CORE_PATH . 'cake' . DS . 'bootstrap.php')) {
		trigger_error("CakePHP core could not be found.  Check the value of CAKE_CORE_INCLUDE_PATH in APP/webroot/index.php.  It should point to the directory containing your " . DS . "cake core directory and your " . DS . "vendors root directory.", E_USER_ERROR);
	}
	if (isset($_GET['url']) && $_GET['url'] === 'favicon.ico') {
		return;
	} else {
		$Dispatcher = new Dispatcher();
		$Dispatcher->dispatch($url);
	}
	if (Configure::read() > 0) {
		echo "<!-- " . round(getMicrotime() - $TIME_START, 4) . "s -->";
	}
?>

We are almost done. Now all there is left to do is add your username/password for the database and of course change the security salt, but you should know how to do these if you’ve already developed with CakePHP.

We have to adapt to a market where managers more often than not are deciding to move their applications to the web. They obtain (almost) ubiquitous access, and we have new technologies to adapt to. (X)HTML, CSS and Javascript are part of the daily code-writing process, so expect some of that, too.