Example Zend Framework Blog Application Tutorial - Part 6: Introduction to ...

In the previous entry, we created a new Administration Module to hold blog management functionality, added a Module specific layout for it, and discussed the upcoming need to ensure this is only accessible by authorised Authors. In this entry I'll unravel some of Zend_Form's mysteries in adding a login form, before using Zend_Auth to implement authentication for authors.

Previously: Part 5: Creating Models with Zend_Db and adding an Administration Module

Authentication in the Zend Framework is the domain of the Zend_Auth component, and it is really easy to use. Zend_Auth is really an abstract API to a number of components working in concert, and without the usual micromanagement of database interaction, sessions, cookies and user data persistence, it makes my life a lot simpler. Of course authentication demands a login form, and so I'll first visit using Zend_Form. Zend_Form is an interesting component because it's one of the worst to get started with. The manual, as it does for all components, does not impose a best practice to setting up forms. Mix that with the number of form organisations possible (class based, config based, view template based) and it can be very confusing.

Step 1: Adding a Login Action and View

Before we actually perform authentication, we need a login form. I've decided to attach all Author account actions to an Author Controller. Add a new file called AuthorController.php in /application/controllers/ containing the following:



The logout action for the moment does nothing, but forwards /author/logout requests to the main index, just as I would intend to occur after a real logout.

We'll also add a matching template at /application/views/scripts/author/login.phtml:



Nothing major here, except for a mysterious reference to a view variable, $loginForm!

Step 2: Creating a Login form with Zend_Form

Zend_Form is one of the most recent additions to the Zend Framework with the release of 1.5. It's not surprising it took so long since a decent Form library is not a trivial component to get through development.

The object oriented approach to developing forms takes a bit of getting used to but it works wonders for simple forms that don't need a heavy design hand. I suppose from my own perspective it was design over functionality that first struck me as problematic when I started using Zend_Form but I think I'm over that learning curve, so let's see how this look at a simple two field login form goes .

I've deliberately selected a preferred form style to adhere to so this will necessitate customising Zend_Form options and decorators. It's standard based, tableless, composed of semantic markup, and still looks okay without CSS styling or when using a screenreader (which is one of the more important facets for a form im my opinion).

Like a lot of areas in the Zend Framework, actually organising Form objects is left to your imagination. My first question when approaching any potential object nearly always concerns how reusable I can make it. A reusable form object assumes I'll end up implementing a standard subclass of Zend_Form so I don't have to repeat myself a dozen times in concrete classes. Hopefully this section provides you with a few good ideas - I have seen Zend_Form examples in the wild that are horrific so I will spend a chunk of time on Zend_Form on this outing.

Since I don't intend on mucking about with forms using the traditional design form, apply filtering, extract clean data, process data, re-add data and errors to form template, blah, blah, blah if I can avoid it - I'll use Zend_Form for almost every form in Maugrim's Marvelous Blog application. Besides, the only public facing form for now would be for comments .

Here's the proposed output I'd be seeking with all this:



Let's see if I can kick Zend_Form into cooperating with me on generating that! Or something similar at least...

If Zend_Form has a flaw, the biggest one is its documentation because like most of the Zend components it doesn't dictate a best practice for organising the final classes. It also appears a little vague at times, but still it does answer a lot of questions if you read it attentive to detail. If something here is just not making sense do ask in the comments or on the Zend Framework mailing lists.

My own take is to take the term "Divide and Conquer" as my motto for dealing with Zend_Form. Break down each specific stage, and from there dump each stage into its own class family. Tackling the whole thing up front without some groundwork is a recipe for the most unmaintainable ugly looking Zend_Form implementation imaginable.

With forms our divisions to conquer are quite simple to visualise. We have the form elements which are segregated from any hint of presentation and which carry elements of business logic by virtue of them containing validation/filtering logic. We have the form element decoration which surrounds form elements with semantic markup styled by CSS we can write independently. Finally we have overall layout which groups all elements logically.

At it's simplest, this suggests we'll have two sets of classes. One group for form elements, and another for decorating those form elements. Take the suggested markup from earlier. The li tags are obviously decorators of the form elements they wrap. The fieldset tags pose another difficultly in that they are not specific to a form element group (there are 2 of them, and the placement is purely for presentation) and so we need some sort of form element grouping mechanism to apply decorators to.

The Zend_Form component does precisely that. Despite any confusion it may cause you, it does have a very logical setup for grouping and decorating elements.

Decorators will cause you a few headaches but they aren't completely nuts . The four main standard types are ViewHelper, Label, HtmlTag and Error. There are fourteen in total for even more decorating madness. By default, each of these effects the form element by adding to it's markup in a predefined (but usually configurable) way.

For example, you can use Label to prepend a form element with some markup. Obviously the name suggests a label tag for the form element but any tag is allowable. Or you can use HtmlTag to wrap tags around a form element like a set of li tags. Hit the manual for a full description of all 14 decorators.

Revisiting our markup, we can suggest a few decorator steps, by working our way out from the form element. The more specific we get here the better.

1. Prepend form element with label tags
2. Wrap form element and label with li tags
3. Prevent application of 1 and 2 to submit element
4. Eliminate default decoration of submit element

Once we hit this point in the decorator flow, we leave the domain of the individual form element. ol and fieldset decorate groups of form elements. Zend_Form wins again by letting us create Display Groups for decorating groups of form elements.

5. Create display group for each fieldset
6. Wrap display group (name, password) with ol tags
7. Prepend display group (name, password) with legend tags
8. Wrap display group (name, password) with fieldset tags
9. Wrap display group (submit) with fieldset tags

Hopefully you're getting the picture. Pick apart your form, and take it step by step. There is a very logical flow with Zend_Form that makes implementing each step simple once you identify those steps! If you just jump in you will get lost unless you're already very comfortable with Zend_Form.

It's again really important that you watch the ordering of decorators - the first decorator added to the stack will be the first applied to the bare bones form element. So each step should be implemented from the inside out in order.

Delving back into PHP, we can now encode a few standard decorator arrays in a Zend_Form subclass. We do need to remember we have one exception above - the submit element requires special treatment since it's not decorated as an unordered list. In this subclass we'll also set a few defaults for all forms such as setting a new "accept-charset" attribute for the form element, and ensuring the rendered form object is free of any default decoration apart from the wrapping form element itself obviously.

Create the file /library/ZFBlog/Form.php as part of our slowly growing application specific library.



The decorator arrays defined as protected properties are quite simple. For example the standardGroupDecorator wraps a display group with the HTML ol tag, and then wraps this again with a fieldset tag. The "FormElements" decorator is sort of a group dynamic - we want to render these group HTML tags around all the form elements included in this display group. You'll see this decorator used for any decoration of a display group of form elements, including the parent form as a single display block (helps to think of a form as a single parent display group with children).

As another example, the standardElementDecorator prepends a form element with a label (notably the label content is not defined yet), and wraps both the form element and label in li tags. You'll notice the standard group decorator wraps the parent ol tags around all of this.

See how easy that was? Once you break down your form markup into a series of specific decoration steps, writing Zend_Form decorator arrays tailored to those steps is pretty simple.

So we have a platform for making forms. How about something specific - like a Login form?

Create a new file /library/ZFBlog/Form/AuthorLogin.php:



How's that for something interesting? Now all we do for an author login form is define the elements, assign a standard or specific decorator array from the parent class, and assign to a display group which also gets a decorator array from the parent class assigned.

The only real sore point here perhaps, is that I'm declaring the text content of labels and legends in the source code. Some bright mind might find it better to stuff these into a configuration file, and maybe link up a Translator for good measure (not covered here but is a documented possibility in the manual), but for now it's enough to work with.

Let's now revise our AuthorController to create this form and pass it to the View.



Go ahead and open up your browser to http://zfblog/author/login.

Here's the exact output I get from Firefox without tinkering with element separator options:



Apart from needing a few newline separators, it's pretty much what I set out to create . Zend_Form just added a few default classes and attribute values.

Step 3: Adding Validation to Login Form

Zend_Form isn't just for presentation since you can also make forms self validating. This takes advantage of all the standard validators you might expect to use manually. Let's revisit the ZFBlog_Form_AuthorLogin form class after including some validation rules.



Note the additions including a new "required" flag dictating these values are required (i.e. must not be empty) and also a "validator" array giving a string length minimum and maximum for the "name" form element. I also just threw in a class attribute for our authorloginsubmit fieldset display group - it'll make styling that fieldset easier.

One thing blatantly missing is error messages - we haven't added any decorators to our form elements to include error message text somewhere.

Step 4: Handling Error Messages with a Custom Decorator

We now have another interesting problem on our hands. Assuming validation fails, where will we display error messages? Usually I prefer to stick them into each form element's label tag (I like really short error messages ) whereas by default, remembering that we've now either disabled or overridden Zend_Form's decoration defaults, it's displayed separately by an appending Error decorator.

Since we're departing from the norm, it's time to customise how labels are generated.

What we need to do is intercept a label before it's rendered, and append error messages to it's content. Simplest way of doing that is to subclass the Label decorator. There is one additional thing to watch out for which is the fact that the standard Label decorator (when used to generate a label element) makes use of the FormLabel View Helper in Zend_View. If we intend appending HTML to the label name (as here) we'll need to disable the FormLabel Helper's default treatment of escaping the label name.

This points out another interesting nugget to remember. Many form decorators use Zend_View's View Helpers. And any options passed to a decorator, are also made available to the relevant View Helper. So it does pay to know the View Helpers as well as Zend_Form - the helpers have another layer of configurable behaviour you might find handy.

About that custom decorator, it's very simple. It just grabs the error messages for any element it's decorating and appends them to the label name wrapped in strong tags for styling access with CSS. Create a new file for the decorator at /library/ZFBlog/Form/Decorator/LabelError.php:



Here we're subclassing the getLabel() method - easier this way than retyping the whole original render() method! All the method does is append the error messages - we refer back to the parent class version of this method afterwards so we don't duplicate any source code from the standard decorator we're extending.

This is great - so let's wrap up by amending our ZFBlog_Form class to tell Zend_Form where to find our custom decorator (and indeed any future ones), and also add the new LabelError decorator to one of our decorator stacks.



The new decorator reference receives a new option - we disable escaping of the label's name value so any included HTML doesn't get the htmlspecialchars treatment. This option is passed into the FormLabel View Helper when called from the decorator class.

In our constructor we have a comment. Never, ever, ever, forget that comment. It is essential that decorator paths for your custom decorators are added as early as possible - in fact they should be the first thing you do in a subclass of Zend_Form even before passing options to the parent's constructor.

Feel like taking a peek? Go ahead and browse to http://zfblog/author/login. The form is still there, and it looks like it hasn't broken yet . Go team!

Step 5: Replacing Those Cumbersome Default Errors

One final step I'll make is layering in a Translation object for our forms. This has a few purposes. First it will allow for translating labels, legends, etc., but to be honest I'm really doing because it's the simplest method of getting rid of the long error messages the Validators generate. Life is never easy, eh?

We'll start simple and only address error messages as a quick example. Add a new file at /translate/forms.php containing:



With the translation file in place (using the Zend_Translate Array adapter) we just need to tell Zend_Form where to find it. Zend_Form uses a static method for this, so I'll create a quick static check and helper function for our ZFBlog_Form class.



Easy as pie. Now all error messages will be replaced.

Step 6: Introducing Joe Bloggs

Before we go further, we're missing one essential aspect of Authentication. We don't have a user! Let's resolve that quickly. I'm not going to pounce on registration since a) this is a one-person blog, and b) I can add it later. So I'll use some filler data for a theoretical user instead. I'm cheap I know. Sorry .

Here's Joe. Rumour has it he's The Common Man (TM). If you prefer, Joe can be a Jane. Nobody intends hunting him/her down to check anyway...

INSERT INTO `authors` (`realname`, `username`, `password`, `email`) VALUES ('Joe Bloggs', 'joebloggs', '5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8', 'joe.bloggs@example.com');

The hashed password is "password" hashed using the SHA256 algorithm.

Run the SQL insert on your users table in the database to manually register Joe (or Jane).