With their suite of modules site developers can now easily create locale aware, geo-targeted compelling experiences in Drupal.

The suite of modules for both Drupal 6 and 7 includes:

• Quova Core – Provides an API to interact with the Quova IP Info service, and helpers for location based customizable content.
• Quova Context – Built in context support allows you to use country and line speed as a context argument. This allows you to easily display localised blocks, display country dependent blocks, or swap out bandwidth sensitive content.
• Quova Locale – Provides automatic language switching based on the users country and region.
• Quova Weather – Integrates with the Weather module to provide a block showing weather at the users current location.
• Rules – Built in rules support allows you to use country as a rules condition allowing location based site customizations or geofencing. Combined with Drupal Commerce, this allows you to enable and disable payment processors depending on the users location.
• Views / Location – Built in helpers to allow you to interface easily with Views and the Location module. For example this can be used to automatically display branches closest to a potential customer.
• Ad – Allows geotargeting of advertising using Quova and the Ad module.

For more information, visit the project page or check out the documentation.

This said, I was sadly unimpressed with the social landscape support. Facebook’s own Python SDK has a slew of bugs and is not actively maintained, I recommend people use David Ziegler’s fork.

For integration with Django, there was Django-facebook which had good intentions but doesn’t quite cut the mustard, Pyfacebook which is no longer actively maintained and does not work with the new Graph API, and Social registration which was the best of the bunch, but still offered poor integration with the django authentication system.

To this end, I have released django-facebook which offers total and seamless integration with Facebook for your social apps.

It has a bunch of nifty tools including template tags, a nice middleware, an authentication backend and some actual documentation!

Spread the word, and watch this space.

/**
 * Allows running a callback on all files in a deep directory structure
 *
 * @author Aidan Lister <aidan@php.net>
 * @param string $dirname The directory to walk
 * @param callable $callable The callable to execute on all files found
 * @param mixed $arg{n} Extra parameters to be passed to the callable
 * @return mixed The return value of the last callable run
 */
function directory_walk($dirname, $callable)
{
    $ignore = array('.', '..', '.DS_Store');
    $args = func_get_args();
    array_shift($args);

    // Sanity check
    if (!file_exists($dirname)) {
        return false;
    }

    // Create and iterate stack
    $stack = array($dirname);
    while ($entry = array_pop($stack)) {
        if (is_link($entry)) continue;

        // Run the action
        if (is_file($entry)) {
          $ret = call_user_func_array($callable, array($entry) + $args);
          continue;
        }

        // Add the directory into the stack
        $dh = opendir($entry);
        while (false !== $child = readdir($dh)) {
            if (in_array($child, $ignore)) continue;
            $child = $entry . DIRECTORY_SEPARATOR . $child;
            $stack[] = $child;
        }
        closedir($dh);
    }

    return $ret;
}

So, for some examples. We’ll start simple and simply print the directory:

$func = create_function('$file', 'echo "found $file";');
directory_walk('target-dir', $func);

Which for me outputs:

found target-dir/foo
found target-dir/bar
found target-dir/baz
found target-dir/baz/ding
found target-dir/baz/dong
found target-dir/baz/dong/witch

What if we wanted to add a .txt extension to all of these files? We could write:

function my_rename($entry, $extension) {
    if (is_file($entry)) {
        rename($entry, $entry . $extension);
    }
}
directory_walk('target-dir', 'my_rename', '.txt');

Another example might be deleting all the .svn or CVS folders in a directory. We could write:

function delsvn($file) {
  $ext = substr($file, strlen($file)-4,strlen($file));
  if ($ext === '.svn') rmdirr($ext);
}
directory_walk('test', 'delsvn');

Note that the above example used the recursive delete function also.

Happy stacking.

The example I am using is an editing platform. At the top of the tree are Volumes, each of which contain many Papers. Authors have access to papers, while Editors have access to volumes and all the papers there-in. Because we have two trees, it’s important to design our ACL tree well or it quickly becomes unmanageable. We’ll call the top of our tree Papers, but this choice is arbitrary.

We create the following ACO hierarchy: Papers/Volume/Paper

This tree structure allows you to provide editors access to a volume, which
automatically gives access to the papers inside. This is the beauty of
ACLs.

To create the ACO tree for an existing dataset, we can develop our own cake shell tool. I will assume you have already created the ARO tree for your users and groups.

class AcltoolShell extends Shell
{
    /**
     * Build a complete ACO tree for two linked models
     *
     * Usage: $ cake acltool aco_models
     */
    function aco_models()
    {
        $this->out('Starting models sync');
        $Paper  = ClassRegistry::init('Paper');
        $Volume = ClassRegistry::init('Volume');

        // Create the root node
        $root_alias = 'papers';
        $this->Aco->create();
        $this->Aco->save(array('parent_id' => null, 'model' => null, 'alias' => $root_alias));
        $aco_root = $this->Aco->id;

        // Iterate all the volumes
        $volumes = $Volume->findAll();
        foreach ($volumes as $volume) {
            // Create a node for the volume
            $this->out(sprintf('Created Aco node: %s/%s', $root_alias, $volume['Volume']['number']));
            $this->Aco->create();
            $row = array('parent_id' => $aco_root, 'foreign_key' => $volume['Volume']['id'], 'model' => 'Volume', 'alias' => $volume['Volume']['number']);
            $this->Aco->save($row);
            $parent_id = $this->Aco->id;

            // Iterate all the papers
            $papers = $Paper->find('all', array('conditions' => array('volume_id' => $volume['Volume']['id']), 'recursive' => -1));
            foreach ($papers as $paper) {
                // Create a node for the paper
                $this->out(sprintf('Created Aco node: %s/%s/%s', $root_alias, $volume['Volume']['number'], $paper['Paper']['slug']));
                $this->Acl->Aco->create();
                $row = array('parent_id' => $parent_id, 'foreign_key' => $paper['Paper']['id'], 'model' => 'Paper', 'alias' => $paper['Paper']['slug']);
                $this->Acl->Aco->save($row);
            }
        }
    }
}

Once our ACO tree is built, we need to give our users permissions. Again we will use a cake shell tool.

    /**
     * Grant user access to two related models
     *
     * Usage: $ cake acltool vol_perms
     */
    function vol_perms()
    {
        // Row level access for volumes
        $this->out('Creating row-level permissions for volumes');
        $Volume = ClassRegistry::init('Volume');
        $volumes = $Volume->findAll();
        foreach ($volumes as $vol) {
            $this->out(sprintf('- Entering volume number %s', $vol['Volume']['number']));
            $Volume->id = $vol['Volume']['id'];
            foreach ($vol['User'] as $user) {
                $this->out(sprintf('-- Granting access to %s', $user['name']));
                $User->id = $user['id'];
                $this->Acl->allow($User, $Volume);
            }
        }
    }
}

?>

We need to inform our models about our chosen ACO structure. We do this for Papers and Volumes in the same way we would for Users and Groups.

models/volume.php
class Volume extends AppModel
{
    /**
     * Describe our ACO tree
     */
    function parentNode()
    {
        return null;
    }
}

models/paper.php
class Paper extends AppModel
{
    /**
     * Describe our ACO tree
     */
    function parentNode()
    {
        if (!$this->id && empty($this->data)) {
            return null;
        }
        $data = $this->data;
        if (empty($this->data)) {
            $data = $this->read();
        }
        if (empty($data['Paper']['volume_id'])) {
            return null;
        } else {
            return array('Volume' => array('id' => $data['Paper']['volume_id']));
        }
    }
}

Unfortunately Auth does not provide a way to automatically handle model access. We use beforeFilter to implement access control manually in the necessary controllers.

First we check that they’re not an admin, then we apply our Acl check. This relies on the fact that a) access is blocked to users by the ‘controllers’ Aco tree and b) access is granted to editors/volumes to this controller by the ‘controllers’ Aco tree. Both of these constraints are enforced by Auth (with $this->Auth->authorize = ‘actions’).

class PapersController extends AppController
{
    /**
     * Row level access checking
     */
    function beforeFilter()
    {
        $methods = array('admin_edit', 'admin_view', 'admin_delete');
        if (isset($this->params['pass'][0]) && in_array($this->params['pass'][0], $methods)) {
            $aco = $this->Acl->Aco->findByModelAndForeignKey('Paper', $this->params['pass'][0]);
            $aro = $this->Acl->Aro->findByModelAndForeignKey('User', $this->Auth->user('id'));
            if (!$this->Acl->check($aro['Aro'], $aco['Aco'])) {
                $this->Session->setFlash($this->Auth->authError);
                $this->redirect(array('su' => true, 'controller' => 'papers', 'action' => 'index'));
            }
        }
    }
}

The only thing remaining is displaying a list of papers and volumes
that a user has access to, instead of all the papers/volumes. This is quite difficult for large trees because it’s simply not what ACL’s are designed for. There’s work being done in Cake 1.3.x.x to build an access cache which would solve this problem, but in the mean time:

class PapersController extends AppController
{
    /**
     * Display a list of papers for which the user has access to view
     */
    function admin_index()
    {
        $papers = array();
        $user_id = $this->Auth->user('id');
        $nodes = $this->Acl->Aro->findByForeignKeyAndModel($user_id, 'User');
        foreach ($nodes['Aco'] as $node) {
            if ($node['model'] === 'Paper') {
                $papers[] = $node['foreign_key'];
            }

            // Get children from volumes
            if ($node['model'] === 'Volume') {
                $children = $this->Acl->Aco->children($node['id']);
                foreach ($children as $child) {
                    $papers[] = $child['Aco']['foreign_key'];
                }
            }
        }
        $conditions = array('Paper.id' => $papers);

        if ($this->Auth->user('group_id') == 1) {
            $conditions = null;
        }

        $this->set('papers', $this->paginate($conditions));
    }
}

The same applies to the volumes controller, but a little simpler as
you don’t need the hierarchy.

class VolumesController extends AppController
{
    /**
     *
     */
    function admin_index()
    {
        $volumes = array();
        $user_id = $this->Auth->user('id');
        $nodes = $this->Acl->Aro->findByForeignKeyAndModel($user_id, 'User');
        foreach ($nodes['Aco'] as $node) {
            if ($node['model'] === 'Volume') {
                $volumes[] = $node['foreign_key'];
            }
        }
        $conditions = array('Volume.id' => $volumes);

        if ($this->Auth->user('group_id') == 1) {
            $conditions = null;
        }

        $this->set('volumes', $this->paginate($conditions));
    }
}

And that’s it, we’ve implemented complete row-level access control in CakePHP. Cake’s AclComponent is incredibly flexible and very powerful, as you can see you can design quite clean and fine-grained permissions quickly and efficiently.

I hope this tutorial helps other developers out there with similar problems, and as always let me know if you have comments or suggestions.

Update: Now compatible with CakePHP 1.3.x. You can also download the source code directly from GitHub.

Here, we build a complete community based website in five minutes using Cake best practices, with the following features: account registration, login and logout, account management page, and password retrieval.

We will take the following steps:

1. Bake a new Cake website
2. Build an account registration page
3. Create a login page, and optionally add a lastlogin field
4. Add change password functionality to our account page
5. Finish with the password retrieval feature

At any time you can download the source code used in this tutorial. Let’s get started!

Step 1. Bake a new Cake website

I’m going to assume that you have a working cake shell installation, so change to your DocumentRoot and execute:
$ cake bake community

This will create a community folder with all the necessary files for your new website. If you visit http://example.com/community, you should see the “all green” indicating you have a working cake installation.

Next, we’ll create the users table by executing the following SQL:

CREATE TABLE `users` (
  `id` int(11) NOT NULL auto_increment,
  `created` datetime,
  `modified` datetime,
  `lastlogin` datetime,
  `name` varchar(100),
  `email` varchar(200),
  `username` varchar(50),
  `password` varchar(42),
  PRIMARY KEY (`id`),
  UNIQUE KEY `email` (`email`)
)

That’s it for the setting up … Let’s move on.

Step 2. Build an account registration page

We’ll get straight into it by creating the users controller, model and the register view.

Because of CakePHP’s automatic hashing, we have to do all our validation work on the password_confirm field, as the password field contains only the hash of the users password.

models/user.php:
<?php
class User extends AppModel
{
    /**
     * Standard validation behaviour
     */
    var $validate = array(
        'name' => array(
            'length' => array(
                'rule'      => array('minLength', 5),
                'message'   => 'Please enter your full name (more than 5 chars)',
                'required'  => true,
            ),
        ),
        'username' => array(
            'length' => array(
                'rule'      => array('minLength', 5),
                'message'   => 'Must be more than 5 characters',
                'required'  => true,
            ),
            'alphanum' => array(
                'rule'      => 'alphanumeric',
                'message'   => 'May only contain letters and numbers',
            ),
            'unique' => array(
                'rule'      => 'isUnique',
                'message'   => 'Already taken',
            ),
        ),
        'email' => array(
            'email' => array(
                'rule'      => 'email',
                'message'   => 'Must be a valid email address',
            ),
            'unique' => array(
                'rule'      => 'isUnique',
                'message'   => 'Already taken',
            ),
        ),
        'password' => array(
            'empty' => array(
                'rule'      => 'notEmpty',
                'message'   => 'Must not be blank',
                'required'  => true,
            ),
        ),
        'password_confirm' => array(
            'compare'    => array(
                'rule'      => array('password_match', 'password', true),
                'message'   => 'The password you entered does not match',
                'required'  => true,
            ),
            'length' => array(
                'rule'      => array('between', 6, 20),
                'message'   => 'Use between 6 and 20 characters',
            ),
            'empty' => array(
                'rule'      => 'notEmpty',
                'message'   => 'Must not be blank',
            ),
        ),
    );

    /**
     * Ensure two password fields match
     *
     * @param   array   data provided by the controller
     * @param   string  the original (already hashed) password fieldname
     * @param   bool    whether the password field has been hashed,
     *                  only hashed when a username input is present
     */
    function password_match($data, $password_field, $hashed = true)
    {
        $password         = $this->data[$this->alias][$password_field];
        $keys             = array_keys($data);
        $password_confirm = $hashed ?
              Security::hash($data[$keys[0]], null, true) :
              $data[$keys[0]];
        return $password === $password_confirm;
    }
}

Next we create our view at views/users/register.ctp. Because we’ve done all our validation on the password_confirm field, the error messages (password too short, etc.) will appear under password_confirm. This isn’t ideal from the user interface perspective; luckily we can just swap the input labels and noone is the wiser.

views/users/register.ctp:
<?php
echo $this->Form->create(array('action' => 'register'));
echo $this->Form->input('name');
echo $this->Form->input('email');
echo $this->Form->input('username');
echo $this->Form->input('password_confirm', array('label' => 'Password', 'type' => 'password'));
echo $this->Form->input('password', array('label' => 'Password Confirm'));
echo $this->Form->end('Register');

Finally we create our users controller at controllers/users_controller.php. We define a beforeFilter method to make our registration page publicly accessible, our register action, and a blank login action.

controllers/users_controller.php:
<?php
class UsersController extends AppController
{
    var $components = array('Auth');

    /**
     * Runs automatically before the controller action is called
     */
    function beforeFilter()
    {
        $this->Auth->allow('register');
        parent::beforeFilter();
    }

    /**
     * Registration page for new users
     */
    function register()
    {
        if (!empty($this->data)) {
            $this->User->create();
            if ($this->User->save($this->data)) {
                $this->Session->setFlash(__('Your account has been created.', true));
                $this->redirect('/');
            } else {
                $this->Session->setFlash(__('Your account could not be created.', true));
            }
        }
    }

    /**
     * Account login page
     */
    function login()
    {

    }

    /**
     * Log a user out
     */
    function logout()
    {
       return $this->redirect($this->Auth->logout());
    }
}

The next issue with Auth arises when the user has entered a valid password, but has failed to validate the entire form – for example, if they picked a username that is in use and must be re-entered. As the password has already been replaced by the hashed password, the form will be redisplayed with the hashed password in the password input. If the user attempts to resubmit the form without retyping their password, form validation will fail on the password_confirm field. Even worse, if you’re not using a password_confirm field, the user will simply be unable to log in to their newly created account.

Thus, we need some hackery to make sure encrypted passwords are not sent back to the user. We can do this in AppController, by writing a beforeRender method.

app_controller.php:
class AppController extends Controller
{
    /**
     * Before Render
     */
    function beforeRender()
    {
        unset($this->data['User']['password']);
        unset($this->data['User']['password_confirm']);
    }
}

And that’s it, we have a complete working registration page. We can view this completed page by visiting /users/register and create our first account.

Step 3. Create a login page

Next up is our login page. We need to modify the default layout which lives at views/layouts/default.ctp. We replace the content div which allows Auth to display messages to the user.

views/layouts/default.ctp:
<div id="content">
    <?php echo $this->Session->flash(); ?>
    <?php echo $this->Session->flash('auth'); ?>
    <?php echo $content_for_layout; ?>
</div>

Next we create a very simple login page:

views/users/login.ctp:
<?php
echo $this->Form->create(array('action' => 'login'));
echo $this->Form->input('username');
echo $this->Form->input('password');
echo $this->Form->end('Login');

And that’s it – it doesn’t get much simpler. We can view our new login page at /users/login.

If we wanted to track the time the user logged in last, we can do some extra work:

Adding to the AppController, we set Auth->autoRedirect:

app_controller.php:
class AppController extends Controller
{
    ...

    /**
     * Before Filter
     */
    function beforeFilter()
    {
        $this->Auth->autoRedirect = false;
    }
}

Then we modify our login controller to do the necessary work:

controllers/users_controller.php:
class UsersController extends AppController
{
    ...

    /**
     * Ran directly after the Auth component has executed
     */
    function login()
    {
        // Check for a successful login
        if (!empty($this->data) && $id = $this->Auth->user('id')) {

            // Set the lastlogin time
            $fields = array('lastlogin' => date('Y-m-d H:i:s'), 'modified' => false);
            $this->User->id = $id;
            $this->User->save($fields, false, array('lastlogin'));

            // Redirect the user
            $url = array('controller' => 'users', 'action' => 'account');
            if ($this->Session->check('Auth.redirect')) {
                $url = $this->Session->read('Auth.redirect');
            }
            $this->redirect($url);
        }
    }

}

Not a lot of additional work, and it will come in handy if you need to prune inactive accounts. Note we can’t this part of the step yet, as it’s expecting an /users/account page to exist (which we create next).

Step 4. Add change password functionality

Cake’s form validation functionality is somewhat limited, in that it only allows you to define validation rules at the model level. Often, you will want to validate data at a per-form level instead. To achieve this, we can dynamically modify the validation rules before form validation takes place. We dive into the user model again:

Note: If we simply added the password_old rule to our validation behaviour, other forms that didn’t include password_old would not validate (because we have set required = true). If we removed required = true, a POST request can easily be forged bypassing this security check.

models/user.php:
class User extends AppModel
{
    ...

    /**
     * Extra form dependent validation rules
     */
    var $validateChangePassword = array(
        '_import' => array('password', 'password_confirm'),
        'password_old' => array(
            'correct' => array(
                'rule'      => 'password_old',
                'message'   => 'Does not match',
                'required'  => true,
            ),
            'empty' => array(
                'rule'      => 'notEmpty',
                'message'   => 'Must not be blank',
            ),
        ),
    );

    /**
     * Dynamically adjust our validation behaviour
     *
     * Look for an _import key in new ruleset, and import
     * those rules from the base validation ruleset
     *
     * @param   string  array key of the validation ruleset to use
     */
    function useValidationRules($key)
    {
        $variable = 'validate' . $key;
        $rules = $this->$variable;

        if (isset($rules['_import'])) {
            foreach ($rules['_import'] as $key) {
                $rules[$key] = $this->validate[$key];
            }
            unset($rules['_import']);
        }

        $this->validate = $rules;
    }

    /**
     * Ensure password matches the user session
     *
     * @param   array   data provided by the controller
     */
    function password_old($data)
    {
        $password = $this->field('password',
            array('User.id' => $this->id));
        return $password ===
            Security::hash($data['password_old'], null, true);
    }

    ...
}

Our change password logic now becomes very simple. We validate, then update the password and redirect the user.

Note: In this case Cake decides not to automatically hash the users password field, so we must perform the hashing manually. This happens because Cake will only hash the password if both the username and password key are set.

controllers/users_controller.php:
class UsersController extends AppController
{
    /**
     * Account details page (change password)
     */
    function account()
    {
        // Set User's ID in model which is needed for validation
        $this->User->id = $this->Auth->user('id');

        // Load the user (avoid populating $this->data)
        $current_user = $this->User->findById($this->User->id);
        $this->set('current_user', $current_user);

        $this->User->useValidationRules('ChangePassword');
        $this->User->validate['password_confirm']['compare']['rule'] =
            array('password_match', 'password', false);

        $this->User->set($this->data);
        if (!empty($this->data) && $this->User->validates()) {
            $password = $this->Auth->password($this->data['User']['password']);
            $this->User->saveField('password', $password);

            $this->Session->setFlash('Your password has been updated');
            $this->redirect(array('action' => 'account'));
        }
    }

    ...
}

We create a template for the account page as follows:

views/users/account.ctp:
<h2>Account Page</h2>
<h3>Change your password</h3>
<p>You are <?php echo $current_user['User']['name']; ?> who last logged in <?php echo $current_user['User']['lastlogin']; ?>.</p>

<?php
echo $this->Form->create(array('action' => 'account'));
echo $this->Form->input('password_old',     array('label' => 'Old password', 'type' => 'password', 'autocomplete' => 'off'));
echo $this->Form->input('password_confirm', array('label' => 'New password', 'type' => 'password', 'autocomplete' => 'off'));
echo $this->Form->input('password',         array('label' => 'Re-enter new password', 'type' => 'password', 'autocomplete' => 'off'));
echo $this->Form->end('Update Password');
?>

The user is now able to change their password. We can test this by logging in at /users/login which will take us to our new account page.

Step 5. Create a password retrieval page

In our final step, we allow the user to retrieve a forgotten password. We do this by emailing the user a token. The user clicks back to our website with the token, and gets emailed a replacement password.

We create a models/token.php to handle the token generation, information storage and retrieval.

models/token.php:
class Token extends AppModel
{
    /**
     * Create a new ticket by providing the data to be stored in the ticket.
     */
    function generate($data = null)
    {
        $data = array(
          'token' => substr(md5(uniqid(rand(), 1)), 0, 10),
          'data'  => serialize($data),
        );

        if ($this->save($data)) {
            return $data['token'];
        }

        return false;
    }

    /**
     * Return the value stored or false if the ticket can not be found.
     */
    function get($token)
    {
        $this->garbage();
        $token = $this->findByToken($token);
        if ($token) {
          $this->delete($token['Token']['id']);
          return unserialize($token['Token']['data']);
        }

        return false;
    }

    /**
     * Remove old tickets
     */
    function garbage()
    {
        return $this->deleteAll(array('created < INTERVAL -1 DAY + NOW()'));
    }
}

We’ll also create the necessary database table.

CREATE TABLE `tokens` (
  `id` int(11) unsigned NOT NULL auto_increment,
  `created` datetime default NULL,
  `modified` datetime default NULL,
  `token` varchar(32) default NULL,
  `data` text,
  PRIMARY KEY  (`id`),
  UNIQUE KEY `token` (`token`)
)

We next update the users controller to make the recover and verify actions public, then we define our recover and verify actions:

controllers/users_controller.php:
<?php
class UsersController extends AppController
{
    var $components = array('Auth', 'Email');

    ...

    /**
     * Runs automatically before the controller action is called
     */
    function beforeFilter()
    {
        $this->Auth->allow('register', 'recover', 'verify');
        parent::beforeFilter();
    }

    /**
     * Allows the user to email themselves a password redemption token
     */
    function recover()
    {
        if ($this->Auth->user()) {
            $this->redirect(array('controller' => 'users', 'action' => 'account'));
        }

        if (!empty($this->data['User']['email'])) {
            $Token = ClassRegistry::init('Token');
            $user = $this->User->findByEmail($this->data['User']['email']);

            if ($user === false) {
                $this->Session->setFlash('No matching user found');
                return false;
            }

            $token = $Token->generate(array('User' => $user['User']));
            $this->Session->setFlash('An email has been sent to your account, please follow the instructions in this email.');
            $this->Email->to = $user['User']['email'];
            $this->Email->subject = 'Password Recovery';
            $this->Email->from = 'Support <support@example.com>';
            $this->Email->template = 'recover';
            $this->set('user', $user);
            $this->set('token', $token);
            $this->Email->send();
        }
    }

    /**
     * Accepts a valid token and resets the users password
     */
    function verify($token_str = null)
    {
        if ($this->Auth->user()) {
            $this->redirect(array('controller' => 'users', 'action' => 'account'));
        }

        $Token = ClassRegistry::init('Token');

        $res = $Token->get($token_str);
        if ($res) {
            // Update the users password
            $password = $this->User->generatePassword();
            $this->User->id = $res['User']['id'];
            $this->User->saveField('password', $this->Auth->password($password));
            $this->set('success', true);

            // Send email with new password
            $this->Email->to = $res['User']['email'];
            $this->Email->subject = 'Password Changed';
            $this->Email->from = 'Support <support@example.com>';
            $this->Email->template = 'verify';
            $this->set('user', $res);
            $this->set('password', $password);
            $this->Email->send();
        }
    }

}

Because we are generating new passwords for users, we need a function to do this. Alternative approaches, like PEAR’s Text/Password can be substituted if you like.

models/user.php:
class User extends AppModel
{
    ....

    /**
     * Generate a random pronounceable password
     */
    function generatePassword($length = 10) {
        // Seed
        srand((double) microtime()*1000000);

        $vowels = array('a', 'e', 'i', 'o', 'u');
        $cons = array('b', 'c', 'd', 'g', 'h', 'j', 'k', 'l', 'm', 'n',
            'p', 'r', 's', 't', 'u', 'v', 'w', 'tr',
            'cr', 'br', 'fr', 'th', 'dr', 'ch', 'ph',
            'wr', 'st', 'sp', 'sw', 'pr', 'sl', 'cl');

        $num_vowels = count($vowels);
        $num_cons = count($cons);

        $password = '';
        for ($i = 0; $i < $length; $i++){
            $password .= $cons[rand(0, $num_cons - 1)] . $vowels[rand(0, $num_vowels - 1)];
        }

        return substr($password, 0, $length);
    }

We define two email templates for recovery and verification respectively:

views/elements/email/text/recover.ctp:
Dear <?php echo $user['User']['name']; ?>,

Someone is attempting to reset your password.

Your username for this account is: <?php echo $user['User']['username']; ?>

If you wish to continue, you may reset your password by
following this link:

    <?php echo Router::url(array('controller' => 'users', 'action' => 'verify', $token), true); ?>

If you did not initiate this action, please contact
support. You can log in to change your password
at this address:

    <?php echo Router::url(array('controller' => 'users', 'action' => 'login'), true); ?>

Thanks,
Support

views/elements/email/text/verify.ctp:
Dear <?php echo $user['User']['name']; ?>,

Your password has been reset, please use the following
details to log into our site.

    Username: <?php echo $user['User']['username']; ?>

    Password: <?php echo $password; ?>

Please change your password to something more memorable.
You can log in to change your password at this address:

    <?php echo Router::url(array('controller' => 'users', 'action' => 'login'), true); ?>

Thanks,
Support

And finally we define our two templates for the recovery and verification views:

views/users/recover.ctp:
<h2>Recover Password</h2>

<?php
echo $this->Form->create('User', array('action' => 'recover'));
echo $this->Form->input('email');
echo $this->Form->end('Recover');
?>

views/users/verify.ctp:
<h2>Recover Password</h2>

<?php if (isset($success)): ?>
    <div class="message">Access verified. Your new password has been emailed to you.</div>
    <p>A new password has been generated for your account and mailed to you. After you've logged in, you should change your password to something memorable via the account information page.</p>
<?php else: ?>
    <div class="warning">Invalid token. This page has expired, or the link was not copied from your email client correctly.</div>
    <p>Make sure you have copied the entire link correctly, pasting it together if the link was split over two lines. If you're copying the link correctly and still can't get access, please contact us.</p>
<?php endif; ?>

And that’s it … we’ve developed a complete community orientated website for CakePHP in less time it takes than to make a cup of tea (if you’re very slow at making tea).

On a side note: you may have noticed that CakePHP’s automatic hashing makes things a lot harder than they should be. In my opinion, automatic hashing directly goes against Cake’s mantra of “If it’s easy to do in Cake, then it doesn’t belong in core”, and I hope the core development team rethink in the idea in Cake 1.3.x.x. Although forcing developers to automatically hash their users password is a nice idea, the current implementation a major stumbling block for new bakers. We shouldn’t need a section in the manual about common problems the user will encounter trying to do simple tasks. Instead, we should fix the cause of the common problems. It is, however, a testament to Cake’s flexibility that we are able to work around most of these issues quite elegantly. It’s also worth noting that there are several ways to override this behavior.

I hope you’ve enjoyed this tutorial, please feel free to leave comments, suggestions or improvements.

This means runtime errors (e.g. an unexpected divide-by-zero) are not logged, and service errors (e.g. when a paypal checkout fails) are not explained to the user.

To solve these two problems we override php’s error handler to enable production error logging, and cake’s error handler to allow forward facing error pages.

Part 1: To enable production error logging, we can override cake’s production error handling code by conditionally setting DISABLE_DEFAULT_ERROR_HANDLING. This code only kicks in when cake is in production and logs all notices and warnings in the cake log file.

app/config/bootstrap.php
<?php
/**
 * Handle logging errors in production mode
 */
if (Configure::read() === 0) {
    // Disable the default handling and include logger
    define('DISABLE_DEFAULT_ERROR_HANDLING', 1);
    uses('cake_log');
    error_reporting(E_ALL);

    /**
     * A function to directly log errors
     *
     * @param $errno The error number
     * @param $errstr The error description
     * @param $errfile The file where the error occured
     * @param $errline The line of the file where the error occured
     * @return bool Success
     */
    function productionError($errno, $errstr, $errfile, $errline) {
        // Ignore E_STRICT and suppressed errors
        if ($errno === 2048 || error_reporting() === 0) {
            return;
        }

        // What type of error
        $level = LOG_DEBUG;
        switch ($errno) {
            case E_PARSE:
            case E_ERROR:
            case E_CORE_ERROR:
            case E_COMPILE_ERROR:
            case E_USER_ERROR:
                $error = 'Fatal Error';
                $level = LOG_ERROR;
            break;
            case E_WARNING:
            case E_USER_WARNING:
            case E_COMPILE_WARNING:
            case E_RECOVERABLE_ERROR:
                $error = 'Warning';
                $level = LOG_WARNING;
            break;
            case E_NOTICE:
            case E_USER_NOTICE:
                $error = 'Notice';
                $level = LOG_NOTICE;
            break;
            default:
                return false;
            break;
        }

        // Log
        CakeLog::write($level, sprintf('%s (%d): %s in [%s, line %d]',
            $error, $errno, $errstr, $errfile, $errline));

        // Die if fatal
        if ($level === LOG_ERROR) {
            die();
        }

        return true;
    }

    // Use the above handling
    set_error_handler('productionError');
}
?>

Part 2: To enable forward facing user error pages, we can define an AppError class. This code allows you to set up custom error handlers, and decide how you want to handle each – be it publicly displayed, logged or mailed to the site managers.

app/app_error.php:
<?php
class AppError extends ErrorHandler
{
    /**
     * List of errors which are displayed, even in production mode
     */
    var $displayErrors = array('logic', 'paypal', 'payflow');

    /**
     * List of errors which, when occur, information is emailed to
     * the site administrator
     */
    var $emailErrors   = array();

    /**
     * List of errors which, when occur, will result in log entries
     */
    var $logErrors     = array('logic', 'system');

    /**
     * A string containing people to be notified in the event of an
     * error. The string must be acceptable input for the mail function
     */
    var $siteManager   = 'aidan@php.net';

    /**
     * Override the default cakeError error handling behaviour
     *
     * By setting the debug switch, the page will be publically visisble
     * Alternatively, or in conjunction with, we can log and notify the
     * site owner
     */
    function __construct($method, $messages)
    {
        if (in_array($method, $this->displayErrors)) {
            Configure::write('debug', 1);
        }

        if (in_array($method, $this->logErrors)) {
            $bt = debug_backtrace();
            $errfile = $bt[1]['file'];
            $errline = $bt[1]['line'];
            $parameters = str_replace("\n", '',
                print_r($messages, true));
            $error = sprintf('%s: Called with parameters (%s) in [%s, line %d]',
                $method, $parameters, $errfile, $errline);
            CakeLog::write(LOG_ERROR, $error);
        }

        if (in_array($method, $this->emailErrors)) {
            $this->_notify($method, $messages);
        }

        // Handle as normal
        parent::__construct($method, $messages);
    }

    /**
     * Send out email when an error occurs
     */
    function _notify($method, $messages)
    {
        $subject  = '[CakePHP] Site Error';
        $headers  = 'From: cakephp@' . $_SERVER['HTTP_HOST'] . "\r\n";
        $headers .= 'Reply-To: cakephp@' . $_SERVER['HTTP_HOST'];
        $message  = 'An occurred error at ' . $_SERVER['HTTP_HOST'] . ".\n\n";
        foreach ($messages as $key => $value) {
            $message .= sprintf("    %s: %s\n", $key, $value);
        }

        mail($this->siteManager, $subject, $message, $headers);
    }

    /**
     * A fatal logic error occured
     *
     * @param $params Expects keys [message]
     */
    function logic($params)
    {
        $this->controller->set('message', $params['message']);
        $this->_outputMessage('logic');
    }
}
?>

Both of these solutions are independent of each other, and provide a way to practically manage error handling in your CakePHP deployment.

I have also opened a RFC to get this behavior included in cake’s core.