Checkbox label placement

The default checkbox placement is on the right side of its label. This can be easily changed by setting the placement option of the Label decorator (allowed values are APPEND and PREPEND):

Inline radio buttons

By default radio buttons are separated with <br /> tags which causes every radio button to display on a single line. To display all radio buttons on a single line:

Unescaped labels

Sometimes you will need to display a link (or any other XHTML markup) inside labels:

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

The default markup they produce is a definition list. But many web designers (incuding me) prefer some other markup. My favorite XHTML for forms is presented in the Prettier Accessible Forms article at A List Apart. It uses an ordered list instead of a definition list. Here is how to achieve it with Zend_Form decorators (the form is the same as in the last post):

Standard decorators for form elements are:

• ViewHelper (the element tag, for example <input> or <textarea>)
• Errors (errors, by default in <ul>)
• HtmlTag (<dd> by default)
• Label (wrapped in <dt> by default)

Standard decorators for the form are:

• FormElements (iterates through form elements)
• HtmlTag (<dl> by default)
• Form (<form>)

I use another decorator to display form errors all on top of the form:

• FormErrors

In the form class above I have defined customized decorators for some form elements. In case there were checkboxes or radio buttons in the form, I would add these decorators:

The loadDefaultDecorators() method applies custom decorators to the form object. The decorators are rendered from inside in the order they are specified. So it works like this:

1. FormErrors is rendered.
2. FormElements is rendered.
3. The <ol> tag is rendered.
4. Finally, the <form> tag is rendered (wrapping all other content inside it).

In conclusion, every decorator renders only its own content and the final form consists of all decorators clumped together.

There are other ways to use it but I usually extend the Zend_Form class and create a separate class for each form in my application. Moreover, I almost exclusively use the MVC design pattern and therefor I use Zend_Form together with Zend_View.

Build a form

Here’s an example of a simple contact form:

The first thing I did was to set a HTTP method to POST with setMethod(). Other option is to use HTTP GET. Next I created an object for every form element. As you can see, there are three input text fields (name, email, subject), one textarea (message), a captcha and a submit button.

Zend Framework contains classes for all HTML form elements you could ever need plus also a wide range of captcha classes. Every element object constructor takes two arguments: the first is an HTML name attribute, the second is array of other HTML attributes such as label or class and additional attributes such as filters and validators.

What’s the difference between filters and validators?

• A filter normalizes input values to match an expected format. A typical example is the StringTrim filter which removes whitespace from the beginning and end of a string. Filters are executed before validation takes place.
• A validator tests input values against some criteria. Values are not changed and the validator reports back whether the input values passed the test or not. A typical example would be the EmailAddress validator which checks if an input value is a valid email address.

The last line of the class – addElements() – adds elements to the form. You can you use the addElement() method to add a single element, too.

Validate the form

First, you need to create an instance of the form class. I use a simple method to do that for me:

Second, in a controller action you load the form and validate it:

Render the form

We have already passed the form to the view, so we can render it:

And how does it look like? Here is the result with almost no styling:

After you submit the form Zend_Form will take care of filtering and validating the input values and it will also render errors:

The default XHTML markup uses a definition list for form elements. Form elements are rendered like this:

<dt><label for="foo">Foo</label><dt>
<dd>
<input name="foo" id="foo" type="text" value="" />
<div><ul>
<li>...</li>
</ul></div>
</dd>

That’s not a bad markup but it might not fit everybody’s needs (I use an ordered list instead of a definition list). Fortunately, you can customize the markup easily using decorators. Decorators? What’s that?

Well, Zend_Form uses the Decorator design pattern to build the XHTML markup. Decorators in Zend Framework are a little bit more advanced topic but they are still pretty easy to work with. I recommend reading this article to understand how they work.