A little while back I need to work with a custom framework that used PostgreSQL as its database. In particular, I needed to be able to set the site up on various machines both for testing and deployment purposes. As I had absolutely no experience of working with PostgreSQL, I went looking for a suitable book, and settled on this one. It proved to be an excellent choice.

The book covers the following broad areas relating to PostgreSQL:

• Installing and configuring PostgreSQL
• Working with PostgreSQL via the command line, via various GUIs and via the browser
• Programming with PostgreSQL using C, PHP, Perl, Java and C#

However, the book also has value in that it covers more general topics of database design and how to construct more complex SQL queries, something which I have found is not generally well explained. For instance, most PHP books that also cover MySQL give a basic coverage of the SELECT, INSERT, UPDATE, and DELETE commands, and perhaps a bit on adding/editing/removing databases and users, but not much assistance on important but tricky topics such as how to combine data from multiple tables.

One thing I found was that PostgreSQL is just that bit more complex that MySQL to set up and administer, so the book was especially valuable in that respect. I was told that PostgreSQL aspired to be an open source replacement for Oracle. I suppose that they have succeeded, in that it can be just as much a pain to use at times.

The download links could be reduced to a comma-separate list of tags, as there was already a lookup table mapping the tag against the appropriate image (for the download type) and the link itself. However, the information required for the images and products was more complex. For example, for the images, I needed to be able to store the “src”, “height”, “width” and “alt” attributes. Each image was represented by an array with these as named elements; these image arrays were themselves grouped together into an array representing all the images.

The solution I used for this (and the product list, which was even more complex) was to store the array as a JSON string in the database. So to convert the array to a JSON string I used the appropriate Zend Framework class as follows:

$images_json = Zend_Json::encode($image_list);

To convert the JSON string back to an array I used the following:

$image_list = Zend_Json::decode($images_json);

Each product page has a standard layout. The page divides into two vertical sections; the top vertical section is divided into two columns. The left column contains the main text describing the products on that page; the right column contains supplementary images and download links. The bottom vertical section contains a jQuery UI tab control, with one tab for each section of products being offered for sale on that page.

I needed to allow the user to edit the HTML used in the top left section. However, I didn’t want the user to have to write raw HTML, but rather to use a WYSIWYG editor. I identified the Open Source JavaScript editor CKEditor as a suitable candidate.

The process of integrating this editor with the existing Zend Framework application proved to be pretty simple:

1. Download the latest version of the editor from the CKEditor website.
2. Having unpacked the download, I uploaded the CKEditor directory (ckeditor) under the public web root (htdocs).
3. The layout script already contained the following in the page head, which forced the appropriate tags to load and enable jQuery to be added:

   echo $this->jQuery()->enable();

4. I added the following at the top of the view scripts that were going to make use of the editor. Note that the ID of the form field that was going to be enhanced by the editor was description.

   // CKEditor
   $this->jQuery()->addJavascriptFile('/ckeditor/ckeditor.js');
   $this->jQuery()->addJavascriptFile('/ckeditor/adapters/jquery.js');
   $this->jQuery()->addOnload("$('#description').ckeditor();");

5. I created a class to handle the form that used the editor. The class was named Application_Form_ProductPage and ultimately derived from Zend_Form via Application_Form_Abstract.
6. The init method of the class contained the following code to add the textarea that was enhanced going to be the editor:

   $this->addElement(
       'textarea', 'description', array(
       'label'		=> 'Product Description',
       'decorators'	=> $this->getFieldDecorators()
       )
   );

As a result of the able, the textarea was transformed into a fully-blown WYSIWYG editor. The raw HTML was passed behind the scenes, and was added to/retrieved from the database.

On another note, blogging has been light this year as I have been distracted by other, non-PHP based projects. However, I intend to put up a few new posts over the next week or so, given that my recent work has involved using PHP and related technologies again.

1. Was the user trying to access something in the admin section?
2. Was the user logged in as admin?

I still needed to add the mechanism for logging in, but there was no need for an access control list, and the implementation of the Access Control Plugin was much simpler.

As before, the plugin needs to be registered in the configuration file:

resources.frontController.plugins.accessControl = 
  "Application_Plugin_AccessControl"

The implementation of the plugin is much simpler, however:

<?php
class Application_Plugin_AccessControl extends Zend_Controller_Plugin_Abstract
{
  public function preDispatch(Zend_Controller_Request_Abstract $request)
  {
    // Get the current user role
    $role = Application_Model_Identity_Current::getRole();
 
    // Get the request module
    $module = $request->getModuleName();
 
    // Determine whether the user is allowed to access the module
    $accessDenied = false;
 
    if ($module == 'admin' && $role != 'admin')
      $accessDenied = true;
 
    // If access is denied, redirect to the login page
    if ($accessDenied)
    {
      $request->setModuleName('default');
      $request->setControllerName('login');
      $request->setActionName('index');
    }
  }
}

The workings of the class should be self-evident from the comments.

Let us start with the plugin itself. It is called Application_Plugin_AccessControl and located in the application/plugins directory. To locate the class definition, the autoloader strips the standard prefix Application_, which is declared in the configuration file, from the class name, then maps the Plugin_ part to that directory. The plugin itself is declared in the configuration file as follows:

resources.frontController.plugins.accessControl = "Application_Plugin_AccessControl"

This ensures that the plugin is initialised and used during the despatch process.

The plugin itself is derived from Zend_Controller_Plugin_Abstract and implements the standard preDispatch method:

class Application_Plugin_AccessControl extends Zend_Controller_Plugin_Abstract
{
  public function preDispatch(Zend_Controller_Request_Abstract $request)
  {
    // TODO: Apply access control
  }
}

By implementing this method, the plugin will be called via it before any request is despatched to the relevant controller. This allows access control to be applied by redirecting a request, if the user is after something that it out of bounds.

The process of applying access control involves a series of steps. These are given below.

Step 1: Get the authentication object. This is used to determine whether the user is logged in, and if so, then as whom.

    $auth = Zend_Auth::getInstance();
    $auth->setStorage(new Zend_Auth_Storage_Session());

Step 2: Get the access control list. This is done by using the static getAcl method of the Application_Model_Acl class.

    $acl = Application_Model_Acl::getAcl();

Step 3: Get the current user role and determine whether the user is logged in.

    $role = Application_Model_Identity_Current::getRole();
    $loggedIn = true;
 
    if (!$acl->hasRole($role))
    {
      $role = 'guest';
      $loggedIn = false;
    }

Step 4: Use the module name and controller name as the resource against which to check. Note that the module is added as a prefix, if it is not the default module.

    $module = $request->getModuleName();
    $controller = $request->getControllerName();
 
    if ($module == 'default' || $module == '')
      $resource = $controller;
    else
      $resource = $module . ':' . $controller;

Step 5: Use the action name as the privilege. The privilege is a sub-division of a resource, to allow finer-grained control of access. In our case, we use it to distinguish between different actions under the same controller.

    $privilege = $request->getActionName();

Step 6: If the resource is not in the ACL, use the default resource and privilege.

    if (!$acl->has($resource))
    {
      $resource = 'index';
      $privilege = 'index';
    }

Step 7: Check whether the user is allowed access to the specified resource. If not, display the home page instead if the user is logged in, otherwise display the login page.

    if (!$acl->isAllowed($role, $resource, $privilege))
    {
      if ($loggedIn)
      {
        $request->setModuleName('default');
        $request->setControllerName('index');
        $request->setActionName('index');
      }
      else
      {
        $request->setModuleName('default');
        $request->setControllerName('login');
        $request->setActionName('index');
      }
    }

I’d like to start by considering the function of each of these classes, and the relationship between them.

The Authentication class is concerned with verifying a person’s identity. The Identity class is used to encapsulate a person’s identity. The Access Control List class is a description of what particular persons are permitted to access.

The Identity class can be seen as acting as the glue between the Authentication and Access Control List class. The role is the primary piece of information stored in the Identity class that is used by the Access Control List class to determine what is accessible and what is not to that user.

We shall look at how the Access Control List class can be used in the next post. This post will be concerned with how the class is implemented.

The class is essentially a wrapper around a Zend_Acl object, which is initialised in the class. This allows the specific Access Control List used by an application to be stored in one place, while the common code for the other components can be reused directly between applications.

The skeleton code for the class is as follows:

class Application_Model_Acl
{
  protected static $_acl = null;
 
  public static function getAcl()
  {
    if (null === self::$_acl)
    {
      // Create the access control list
      self::$_acl = new Zend_Acl();
 
      // TODO: Create and add the roles
 
      // TODO: Create and add the resources
 
      // TODO: Set up the access control
    }
 
    return self::$_acl;
  }
}

Note that the method for retrieving the Access Control List object is static, and that the object is only created if it has not already been initialised.

Zend_Acl works with two basic collections of objects: roles and resources.

Roles are used to group users, and assign permissions to those groups en masse.

In our example we have two roles, which are added like this:

      // - Create the roles
      $guestRole = new Zend_Acl_Role('guest');
      $userRole = new Zend_Acl_Role('user');
 
      // - Add the roles
      self::$_acl->addRole($guestRole);
      self::$_acl->addRole($userRole, $guestRole);

The guest role represents anyone accessing the site who has not logged in. The user represents anyone accessing the site who has logged in.

Note that when adding the user role, we pass the guest role as the second parameter; this means that the user inherits all the permissions of the guest role. This is logical, as logging in should extend what a user can do on the site.

Resources represent things that a user might try to access on the website. In the scheme I am using here, each resource maps directly to a controller. Therefore, we need a resource for each controller used by the application.

Let us assume that the application has four controllers: index, error, login and user. We need to add a resource for each one.

      // - Create the resources
      $indexResource = new Zend_Acl_Resource('index');
      $errorResource = new Zend_Acl_Resource('error');
      $loginResource = new Zend_Acl_Resource('login');
      $userResource= new Zend_Acl_Resource('user');
 
      // - Add the resources
      self::$_acl->addResource($indexResource);
      self::$_acl->addResource($errorResource);
      self::$_acl->addResource($loginResource);
      self::$_acl->addResource($userResource);

Now we have defined the roles and resources, we can wire them up together, to indicate what can and cannot be accessed by users with a particular role.

      // - Set up the access control
      self::$_acl->deny();
      self::$_acl->allow(null, array($errorResource, $loginResource));
      self::$_acl->allow($userRole, array($indexResource, $userResource));

This scheme allows guests only to visit the login page (and to see the error page, if necessary). To visit the home page or user page, the user must first log in successfully.

A basic version of the class would look something like this:

class Application_Model_Identity
{
  private $_username = '';
  private $_role = '';
  private $_name = '';
 
  public function __construct($resultRow)
  {
    if (isset($resultRow->username))
    {
      $this->_username = $resultRow->username;
 
      if (isset($resultRow->role))
        $this->_role = $resultRow->role;
 
      if (isset($resultRow->name))
        $this->_name = $resultRow->name;
    }
  }
 
  public function getUsername()
  {
    return $this->_username;
  }
 
  public function getRole()
  {
    return $this->_role;
  }
 
  public function getName()
  {
    return $this->_name;
  }
}

This provides an unremarkable means of encapsulating the essential information retrieved via the result row.

As we shall see in a later post, having a role defined for each user is a basic method for providing more finely-grained access control. Typically, a site will allow users to log in at various levels, such as admin.

It is possible to do some more advanced things here.

For instance, in one application I have written, the user can be a member of one or more sales organisations. To support this we have an additional member variable to store these sales organisations:

  private $_salesOrgs = array();

We then extend the signature of the constructor to take the database adapter and logger as additional parameters:

  public function __construct($resultRow, $dbAdapter = null, $log = null)

Then in the constructor, below the lines

      if (isset($resultRow->name))
        $this->_name = $resultRow->name;

we add the following:

      $this->_salesOrgs = array();
 
      if (null !== $dbAdapter)
      {
        try
        {
          // Get the user's sales organisations
          $sql = $dbAdapter->quoteInto(
"SELECT sales_org_id, name FROM sales_org WHERE sales_org_id IN 
(SELECT DISTINCT sales_org_id FROM user_sales_org WHERE username=?)", 
$resultRow->username);
 
          $this->_salesOrgs = $dbAdapter->fetchAssoc($sql);
        }
        catch (Exception $e)
        {
          if (null !== $this->_log)
            $log->err($e->getMessage());
        }
      }
      else
      {
        if (null !== $this->_log)
          $this->_log->crit('Database adapter not specified');
      }

We also add a means to retrieve the sales organisations:

  public function getSalesOrgs()
  {
    return $this->_salesOrgs;
  }

To retrieve the user’s identity, and therefore all the above information, elsewhere in the application, we use the following code:

$auth = Zend_Auth::getInstance();
$identity = $auth->getIdentity();

The class has following methods and member variables:

class Application_Model_Login
{
  private $_dbAdapter = null;
 
  private $_log = null;
 
  public function __construct($dbAdapter = null, $log = null)
  {
    // TODO: Insert construction code here
  }
 
  public function login($username, $password)
  {
    // TODO: Insert login code here
  }
 
  public function logout()
  {
    // TODO: Insert logout code here
  }
}

When using the class, we pass the constructor references to the database adapter and log objects to use; these are stored in the appropriate member variables:

  public function __construct($dbAdapter = null, $log = null)
  {
    $this->_dbAdapter = $dbAdapter;
    $this->_log = $log;
  }

The login method receives the username and password from the calling function:

  public function login($username, $password)
  {

The database adapter must be set, otherwise the class cannot authenticate against the database:

    // Check that the database adapter has been set
    if (null === $this->_dbAdapter)
    {
      if (null !== $this->_log)
        $this->_log->crit('Database adapter not specified');
 
      return false;
    }

Note that the method uses the logger (if it has been supplied) to record this failure. Also, the method returns false to indicate that the login was unsuccessful.

Next, the method gets the date and time of the login attempt; this will be logged later:

    // Get the date and time of the attempt
    $date = new Zend_Date();

Then, the method gets the global authentication object:

    // Get the authentication object
    $auth = Zend_Auth::getInstance();

Next, the method creates an authentication adapter:

    // Set up the authentication adapter
    $authAdapter = new Zend_Auth_Adapter_DbTable(
      $this->_dbAdapter, 'user', 'username', 'password', 'md5(?)');
    $authAdapter->setIdentity($username);
    $authAdapter->setCredential($password);

The adapter is passed the username and password supplied to the method. In this case, the database is assumed to have a user table, with fields named username and password. Also, the password has been encrypted using MD5.

The method is now ready to authenticate the user, using the global authentication object and the adapter:

    // Attempt to authenticate the user
    $result = $auth->authenticate($authAdapter);

If the attempt is successful, the method now gets the entire row in the database table associated with the user. This information is used to create the identity object. This object is an instance of the class Application_Model_Identity, which we will examine in a subsequent post. This identity is stored in the global authentication object. The application will be able to determine whether the user is logged in by the existance of the identity.

   // Check the result of the attempt
    if ($result->isValid())
    {
      // Get the result row object
      $resultRow = $authAdapter->getResultRowObject();
 
      // Create the identity object
      $identity = new Application_Model_Identity($resultRow, 
$this->_dbAdapter, $this->_log);
 
      // Store it in the current session
      $auth->getStorage()->write($identity);

The method uses the logger (if it has been supplied) to record this success, including the date of the attempt:

      if (null !== $this->_log)
      {
        // Log the successful login
        $notice = sprintf('Successful login from %s by %s at %s',
          $_SERVER['REMOTE_ADDR'], $username, $date->toString());
        $this->_log->notice($notice);
      }

Finally, the method returns true, to indicate that the login succeded:

      return true;
    }

If the login attempt fails, the method uses the logger (if it has been supplied) to record this failure, including the date of the attempt:

    else
    {
      if (null !== $this->_log)
      {
        // Log the failed login attempt
        $warn = sprintf(
          'Failed login attempt (invalid username/password) from %s by %s at %s',
          $_SERVER['REMOTE_ADDR'], $username, $date->toString());
        $this->_log->warn($warn);
      }

It then returns false, to indicate that the login failed:

      return false;
    }
  }

The logout function is quite simple. We get the authentication object, then clear any identity stored in it:

  public function logout()
  {
    // Get the authentication object
    $auth = Zend_Auth::getInstance();
 
    // Clear the user identity to log out
    $auth->clearIdentity();
  }

The application will now regard the user as being logged out.

The form class is derived from an abstract base class of my devising. This contains the functionality shared between all forms in an application. The abstract base class is itself derived from Zend_Form.

The abstract base class is defined as follows:

abstract class Application_Form_Abstract extends Zend_Form
{
  public function getFieldDecorators()
  {
    return array('ViewHelper', 
      array('HtmlTag', array('tag' => 'dd')), 
      array('Label', array('tag'  => 'dt'))
    );
  }
 
  public function getFirstFormError()
  {
    $fields = $this->getMessages();
 
    foreach ($fields as $field => $messages)
    {
      foreach ($messages as $message)
      {
        $error = array('message' => $message, 'field' => $field);
        return $error;
      }
    }
 
    return null;
  }
}

The class supplies contains two functions, both of which are connected to the rendering of error messages.

The first function modifies the standard field decorators to remove the error decorator, as I don’t usually want any error messages displayed beside the field. Instead, I prefer to show the first error message at the top of the form; it is the task of the second function to retrieve this.

The actual Login form class is straighforward:

class Application_Form_Login extends CapArgo_Form_Abstract
{
  public function init()
  {
    $this->setAttrib('id', 'login_form');
 
    $this->setMethod('post');
 
    $this->addElement(
      'text', 'username', array(
        'label'      => 'Username:',
        'maxLength'    => 64,
        'required'    => true,
        'filters'    => array('StringTrim'),
        'decorators'  => $this->getFieldDecorators(),
        'errorMessages'  => array('Please enter your username')
      )
    );
 
    $this->addElement(
      'password', 'password', array(
        'label'      => 'Password:',
        'maxLength'    => 64,
        'required'    => true,
        'decorators'  => $this->getFieldDecorators(),
        'errorMessages'  => array('Please enter your password')
      )
    );
 
    $this->addElement(
      'submit', 'submit', array(
        'ignore'    => true,
        'label'      => 'Login'
      )
    );
  }
}

The above code needs little explanation.

Note that there is a call to $this->getFieldDecorators() in order to attach the proper decorators to the input fields.

Also, note that the required option is set to true, and an error message is supplied, should the user fail to enter either a username or password; this uses Zend_Validate_NotEmpty to check that the user has entered a value.