The sign up form should have at least these fields:

• email
• username
• password

There are few tiny things you will probably need to modify according to your application. I chose Slovak language (‘sk’) and GMT+1 time zone (’1.00′) which is a time for central Europe. I also used a controller action helper PhpbbHash above. The helper is here:

Few comments:

1. The above code is taken directly from the phpBB codebase, I only made a couple of necessary changes to make it work with Zend Framework.
2. For those of you asking why didn’t I just use phpBB API and call its native functions, there is a reason for it. The phpBB code is written to be available with PHP 4. Zend Framework requires at least PHP 5.2.4. There are lots of globals and other scary stuff in the phpBB codebase which makes it impossible for its functions to be called from ZF controllers.
3. If you think I should have done something differently or I completely forgot to do something, please let me know.

1. Creating an index and updating it regularly.
2. Searching the index with a powerful query language.

First, let’s create a fresh search index. I know it’s already tiresome but I will use a simple blog application for my example implementation. To simplify it even further, it will only be possible to search blog posts. The posts schema looks like this:

CREATE TABLE posts (
id INT NOT NULL AUTO_INCREMENT,
title VARCHAR(255) NOT NULL,
body TEXT NOT NULL,
created_at DATETIME NOT NULL,
updated_at DATETIME NOT NULL,
user_id INT NOT NULL,
INDEX (created_at),
INDEX (user_id),
FOREIGN KEY (user_id)
REFERENCES users(id)
ON UPDATE CASCADE
ON DELETE CASCADE,
PRIMARY KEY (id)
) ENGINE = INNODB;

Creating the search index is easy:

Pretty straightforward. You can see I have used three different static methods for adding fields to the document:

• UnIndexed: unindexed and unstored (therefor unsearchable) but they are returned with search results. Unindexed fields usually store primary keys, timestamps or file paths.
• Text: indexed, stored and tokenized. Text fields are searchable and are returned with search hits. Titles, first and last names, cities and states, post codes and street names are all good candidates for keyword fields.
• UnStored: indexed and unstored – ideal for large texts.

There are more types of fields you can use (keyword, binary) but you can read about them in the documentation.

Next thing you need to do is update the index every once in a while so the search hits return up-to-date information. There are two ways to get around this problem. The most obvious is to update the index every time a new post is published or an existing post is edited. Another approach would be to set up a cron job to run every now and then and rebuild the index. Which way you choose depends on many variables such as expected index size (a very large index can have few GBs in size).

Secondly, the index is already taken care of, so let’s search it:

That was possibly the simplest possible example of a Lucene search query. You can, however, create very complex queries with the powerful Lucene query language. You can either build queries manually in PHP or you can use Zend_Search_Lucene methods to build them. It’s so easy a baby could do it.

To search for posts with words ‘hello’ and ‘word’ in the contents field you would write this query:

hello

To search for a post that must contain ‘hello’ and may contain ‘world’:

+hello world

To search for a post that must contain ‘hello’ in the contents field and may contain ‘world’ in the title field:

+hello title:"world"

And those were just basics. You can use boolean operators, wildcards, ranges and even perform a fuzzy search.

The frontend and the backend adapters can take much more arguments, read the documentation to learn all possible options. I initialized the Zend_Cache object with the factory method. First argument means that we want to use the Zend_Cache_Core frontend which is the core of the Zend_Cache module. The second argument is the backend we want to use the Zend_Cache_Backend_File backend or that we want to store cached data as files in a specific directory. The other two parameters are frontend and backend options.

Now we can easily access the cache object in controllers or models:

That was easy, wasn’t it?

Cleaning the cache

You will surely also want to remove cached files at some point in your application:

That’s it for today and, by the way, Merry Christmas

Message: SQLSTATE[42000]: Syntax error or access violation: 1064 You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near ')' at line 2

It took me some time to track down the cause of this error message. I was building a complex query with Zend_Db_Select which included several joins and subqueries so I thought I had made a mistake in syntax somewhere but the problem was I was passing an undefined variable to where() method. So the problematic line was:

$select->where($where);

And $where was not defined. Hope this helps somebody.

Addendum (Oct 6, 2009 @ 14:13)

The same problem can occur also when there is any error in your WHERE clause, for instance:

WHERE id =

The above (there’s a missing integer after “id =”) would throw the same exception.

From my experience, the problem is 99% of the time with foreign keys. Here are three most common reasons I have come across:

• the two fields in the foreign key relationship are not exactly the same type (for example one is TEXT and another is VARCHAR)
• although the two fields are the same type they aren’t the same size (for example one is INT(10) and another is INT(4))
• the field you are referencing with the foreign key has no index (if the field is not a primary key you must add index to it)

I hope this might be helpfull to someone who comes across a similar error message.

Scenario is simple. Your application has three modules and each module needs to be accessible to users with different priviledges:

1. ‘default’ module – accessible to all users and guests
2. ‘member’ module – accessible only to registered users
3. ‘admin’ module – accessible only to registered users with administrator priviledges

I will go step by step and explain all parts in depth:

• database table and model
• registration form
• registration controller action
• login form
• login controller action
• logout controller action
• authentication controller plugin
• recommended reading

Database table and model

Let’s create a database table that will store all users:

CREATE TABLE users (
id INT NOT NULL AUTO_INCREMENT,
first_name VARCHAR(255) NOT NULL,
last_name VARCHAR(255) NOT NULL,
email VARCHAR(255) NOT NULL,
username VARCHAR(255) NOT NULL,
password_hash VARCHAR(255) NOT NULL,
role VARCHAR(255) NOT NULL,
status VARCHAR(255) NOT NULL,
INDEX (first_name),
INDEX (last_name),
INDEX (username),
INDEX (email),
PRIMARY KEY (id)
) ENGINE = INNODB;

The ‘role’ column will hold a user access level, for example: ‘user’, ‘administrator’ etc. The ‘status’ column could have ‘pending’ and ‘approved’ possible values which would allow administrators to approve freshly registered users before they could access private parts of the website.

I put INDEX on ‘first_name’, ‘last_name’, ‘username’ and ‘email’ fields because are often be used instead of the ‘id’ to fetch a single user.

You will also need a model representing the table. Here is a very simple model, in a real-life application you will certainly need more methods (for editing and removing users etc):

Notice this line in the add() method:

What it does is it first prepends the salt to the plain text password and then create an sha1 hash which can be safely stored in the database.

Registration form

Unless you want to create user accounts manually you should allow guests to register. The registration form:

The form is straightforward – a single form element per table column (except ‘id’, ‘role’ and ‘status’). I always use my custom decorators which produce the markup I want.

Registration controller action

First of all, in order to eliminate duplicate rows in the database we check for users with the same username or email before continuing. We also make sure a user correctly filled in both email input fields and both password input fields.

Afterwards, an email with a verification string (which happens to be an sha1 hash of the user email) is sent to the user and a new account is created. I use a handy action helper to generate a random string (in this case used as a salt):

By clicking on the link the user is taken to the email verification page:

Login form

The login form is quite simple. It contains just two input fields (for username and password) and a “Remember me?” checkbox:

Login controller action

Notice this line:

The argument of the setCredentialTreatment() method is probably confusing, it’s a little more complex SQL expression. What it does is it compares the entered password with the password_hash from the database (substitute the entered password for the question mark). CONCAT() is a MySQL function for concating strings (in PHP it’s done with the concatenation operator – ‘.’), SUBSTRING() is very similar to the PHP’s substr() (the only difference is the first character has index 1 in MySQL and 0 in PHP), SHA1() is the same as sha1() in PHP.

Logout controller action

Authentication controller plugin

I always use a controller plugin for authentication. You could possibly do it in controllers (let’s say in the init() method) but I find the controller plugin to be an ideal for this purpose:

As you can see, there are different access rules for each module. It’s not terribly difficult to create more comples access rules. The one thing you must understand is that (quoted from the Zend Framework documentation):

In general, Zend_Acl obeys a given rule if and only if a more specific rule does not apply.

For instance, let’s say you want to disallow logged in users from accessing the login form:

You can also specify actions in the access rules:

One more thing, you need to register the plugin so it works. I usually do it in the bootstrap file:

You need to add the ‘My_’ namespace to the application config file, too:

autoloaderNamespaces[] = "My_"

Recommended reading

• My favorite Zend_Form decorators configuration
• Extending Zend_Form
• Password hashes and salts

What is a hash? A hash is the result of a one-way mathematical process which creates a unique string. The string is next to impossible to decode in order to recover the original text. This makes it an ideal way of storing sensible data in databases – especially passwords.

There are many hashing algorithms, most widely used are MD5 (128-bit) and sha1 (160-bit). Researchers found out that MD5 and also SHA1 are less secure than previously thought so if security is your top priority, you should look for some more advanced algorithms (256-bit or 512-bit). But for usual applications SHA1 is still very secure.

Example: Simple user authorization using sha1 hash

Let’s create a simple table for users:

CREATE TABLE users (
id INT NOT NULL AUTO_INCREMENT,
username VARCHAR(255) NOT NULL,
password_hash VARCHAR(255) NOT NULL,
PRIMARY KEY (id)
) ENGINE = INNODB;

When user registers, you ought to save only a hash of the password in the database:

When a user attempts to log in, you just need to compare a hash of the user entered password to the hash stored in the database:

Salt improvement

Even though storing only hashed passwords in the database is already very safe, there is a weakness which can be exploited. If an attacker gains access to the database, he will be able to say that users with the same password hash must also have the same password. This information would be still useless but the attacker can use the ‘ brute forcing’ (generate numerous potential password hashes – either randomly generated or from a dictionary – and compare them with hashes in the database) to decode user passwords.

Strong passwords (containing letters, numbers and other symbols) are secure even against the ‘brute forcing’ attacks but users often like short passwords containing only letters or only letters and numbers. This weakness can be overcome by using a ‘salt’. Salt is a randomly generated string which is prepended to a plain text password before using a hasing algorithm. You need a function for creating a random string:

User registration will now look a little differently:

And when a user attempts to log in:

Unfortunately, many people use it incorrectly. The mistake they’re making is passing a complete dataset to the paginaton class which gets slower and extremely inefficient as the amount of data in the database grows.

The solution is to pass only a select object to the pagination class. I usually write a special method that returns only a select object without fetching any data:

The rest is quite straightforward. In the controller I initialize a Zend_Paginator instance, configure it (I use $_GET['p'] for a current page number) and pass it to the view. Notice the _getTable() method. It saves me lots of time because I don’t have to include and initialize models manually:

Then in the view I iterate through the data (in this example scenario blog posts) and print the pagination control:

I use this pagination template (it’s very similar to the one in the Zend Framework documentation, I use a more semantic markup though):

I often have more than one pagination template so I usually create a path/to/a/module/views/scripts/pagination directory where I keep them.

• unlimited hierarchy levels

On the other hand, there are reasons why I wouldn’t recommend using it unless you have to:

• very complicated hierarchy modifications compared to the adjacency model (you often have to update almost the whole table)
• a small mistake in PHP code for modifying the hierarchy can break up the whole table (you must test your application carefully before deploying it to the production environment)

Look at the picture to get a better idea about what the nested set model looks like:

Pay special attention to the red numbers – based on these numbers you can calculate the position of an item in the hierarchy. The schema (‘lft’ and ‘rgt’ are used because ‘left’ and ‘right’ are MySQL reserved words):

CREATE TABLE categories (
id INT NOT NULL AUTO_INCREMENT,
name VARCHAR(255) NOT NULL,
lft INT NOT NULL,
rgt INT NOT NULL,
PRIMARY KEY (id)
) ENGINE = INNODB;

Let’s populate the table with some content we can work with:

INSERT INTO categories (id, name, lft, rgt) VALUES
(NULL, 'Relational databases', 1, 12),
(NULL, 'SQLite', 2, 3),
(NULL, 'MySQL', 4, 9),
(NULL, 'PDO', 5, 6),
(NULL, 'Transactions', 7, 8),
(NULL, 'PostgreSQL', 10, 11);

The query to select the full tree is simple:

SELECT * FROM categories ORDER BY lft

PHP implementation

Displaying the tree in an unordered XHTML list is not the hardest part. There are two important formulas:

rgt < last rgt => increment the hierarchy level (move one level down)
lft - last lft > 2 => decrement the hierarchy level (move one level up)

Therefor you can create the unordered list by keeping a track of left and right values:

Modifying the hierarchy

This is where it gets interesting. Modifying the hierarchy created by the nested set model or in other words adding, updating or removing branches (nodes) from the tree while keeping the hierarchy integrity.

Adding nodes

There are two ways how to add a new node – from the left and from the right. Both have very similar implementation (I will show you just the latter). Before I show you how to do it here is another important formula:

(rgt - lft - 1) / 2 = number of children nodes

In theory, what you need to do is add a new node and update all nodes to the right (those that have higher ‘rgt’ value). First, here is the algorithm in the pseudo language:

get a parent node

for all nodes
    if rgt >= parent->rgt
        rgt = rgt + 2
        if lft <> 1 and lft > parent->lft
            lft = lft + 2
        endif
    endif
endfor

add a new node:
    lft = parent->lft + number of children nodes * 2 + 1
    rgt = lft + 1

Here is a function:

Removing nodes

Very similar to adding nodes but you must also take special care of children branches in case you want to remove a parent node. In the pseudo language:

get a node

if node->lft <> 1

    delete the node

    for all nodes
        if rgt > node->rgt
            rgt = rgt - 2
        endif
        if rgt > node->rgt and lft <> 1 and lft > node->lft
            lft = lft - 2
        endif
        if rgt < node->rgt and lft > node->lft
            lft = lft - 1
            rgt = rgt - 1
        endif
    endfor

endif

And here’s how it could look in PHP: