You’d never think a guy could write so much about a blog application but to date after 6 parts we have covered a mass of detail from initial setup of our project’s directory structure to Authentication of users. To date the feedback has been overwhelmingly positive to this series and I’m presently collecting comments regarding improvements for later inclusion.

Today’s entry concerns authorisation. We previously covered how to authenticate an author to the blog, but we still have nothing ensuring only authenticated authors can access the new Administration Module. This is the domain of Zend_Acl, an implementation of an Access Control List system which limits access to resources by the roles assigned to a user.

In the final section of this entry, we take a small detour into the world of CSS (which rarely works out for me ) where I’ll apply some small changes to our Layouts and add two new stylesheets. Once these are added, our infant blog application will look slightly more presentable than it’s current nakedness.

Step 1: Understanding Access Control Lists (ACL)

It can be a bit confusing to face off against ACL if you’re new to the subject. In essence all ACL does is keep track of resources and roles.

As to what a resource is, it is anything to which access can be allowed or denied. For our blog application, I could decide that the Administration Module is itself one resource. From there I can restrict all access to that entire Module, including all it’s Controller classes and Action methods (which are part of that single Resource). Or perhaps I could determine that only one Action method in the whole Module is a specific Resource, bearing in mind that Resources are nestable (i.e. a basket is a Resource, and each egg it holds are also discrete Resources). Since each Resource can be given differing access rules, you can globally prevent non-author users from accessing the Administration Module, but maybe allow some registered users access to specific Actions in that Module as an exception to the global rule.

A lot of the time managing global rules, and then applying exception rules, is how ACL works in practice.

Explaining a Role is even simpler. Any visitor to the application can be assigned a Role which ACL rules may use to define that user’s access to Resources. Typically the first Role everyone will receive is “guest”. From there you can escalate Roles to offer a visitors a greater degree of access to Resources. Any user can be given multiple Roles even. For example, if an author visits the blog they start with the role of “guest” but after authentication we might grant them the additional role of “author”. If Roles dictate specific but limited responsibilities (perhaps there’s an “author” and “editor” Roles) you might decide to start tracking roles more elaborately, in a database possibly.

Going a bit further, if our Administration Module is a Resource called “admin” then we can decide that the only Role with access to it will be the “author” Role. Since our user has been authenticated and granted the “author” Role (either post-authentication or permanently recorded on the database), they can access the Administration Module.

Finally is the concept of Privileges. Just because you can access a Resource, does not instantly mean you should have total uncontrolled access to it. You can limit control over a Resource using Privileges. Perhaps an Author can access the Admin Module (represented by an Admin Resource) but we want to deny Authors the privilege of deleting entries from the database.

Step 2: A Little Planning Goes A Long Way

Before we leap into the fray like a demented action hero, let’s set out exactly what we’re aiming for.

Since our blog is a relatively simple application, we really only need two Roles to start with. We’ll call these guest and author. This may change in the future, perhaps we could allow for multiple Authors but one Editor capable of editing all posts. In that case we’d need to pick apart how that’s implemented. But for now, two Roles is just fine.

As for Resources, the first is the public facing facade of our application where entries are displayed, logins performed, and comments made. The second is the Administration Module. Again, we could be more elaborate but let’s not overcomplicate the application until we’re forced to . This suggests we only have two Resources: the Default Module and the Administration Module. Remember that the Default Module comprises everything not assigned to a specific Module (like our Admin Module with its own separate tree of Controllers and Views).

The rules falling out form this quick analysis are simple.

1. Guests can access the Default Module
2. Authors can access the Default Module
3. Guests cannot access the Administration Module
4. Authors can access the Administration Module

Step 3: Storing Rules in a Class

There is no specific backend storage for Zend_Acl which since it is a serialisable class can be simply serialised and stored in anything from a database to a file for later consumption. To keep things simple I’ll just implement a class defining the relationship between Roles and Resources as described above. You’ll note we are not using Privileges, since access to a Resource assumes the accessing Role has all possible Privileges by default.

Start by creating a new file at /library/ZFBlog/Acl.php:

One confusing point I’ve seen asked is whether Resources explicitly refer to Modules, Controllers or Actions. They don’t - the names used here are pure convention. A resource is a virtual item. Zend_Acl doesn’t know if a Resource is a Module, Controller or Action since that’s a decision we make when we check the ACL rules later. What we’ll do then is detect what Module a request for, and specifically carry out an ACL check for the Resource created here to refer to that Module, i.e. the connection between a real Module name and an ACL Virtual Resource is determined entirely by us at checking time.

Probably the biggest area of confusion is that its so common to consider Resources as Controllers, and Privileges as Actions, that people don’t realise this is pure convention. Someone seeing $this->allow('author', 'entry', array('create', 'edit', 'delete')) would interpret that Authors are allowed access to the Entry Controller with privileges sufficient to create, edit or delete entries. That is only the case if, and when, your ACL logic determines this is how the rule is interpreted.

To prove a point, where do Modules fit? They don’t. There is no Module parameter for Zend_Acl::allow(). You could append ACL interpretive logic where a Resource called “admin|entry” refers to the Entry Controller of an Admin Module which once again emphasises that a Resource is completely virtual. It is only what you interpret it to be and has no preconceived relationship with MVC. For all you care a Resource could be absolutely anything that is accessible only by passing through the ACL checkpoint.

Step 4: Implementing ACL using a custom Front Controller Plugin

The problem with ACL is that it’s one of those always-on checks. Every single request needs to be checked to ensure that the requesting user has a Role which allows them to access the Resource (i.e. the Module, Controller or Action) being requested.

By stringing together the requirements (interacts with request data, operates on all requests, occurs prior to Controller execution) we realise that the best way of accomplishing this is to add a Front Controller plugin implementing the preDispatch() method.

Create a new file at /library/ZFBlog/Controller/Plugin/Acl.php.

Once again we’re using the PEAR Convention and we will continue to mirror the organisation of Zend Framework classes.

Look Ma, it’s another plugin!

If you haven’t already guessed from reading this series so far, a lot of great things happen when you take the time to write plugins and helpers for the Zend Framework.

This Front Controller Plugin is really simple. It checks whether the current user is authenticated or not. If they are authenticated, it assumes they are an Author - not a Guest. Now assumptions are not very pretty, but it’s a blog with two roles. If you had a slightly more complex scenario (say we had Guest, Author and Editor roles) you could instead maintain Roles in the database for querying by this plugin. For example, add a new “role” field to our author table on the database - the data from it will get stored by Zend_Auth during authentication which, as you see, is accessible by this plugin .

After Roles are assumed, we grab the name of the current Module and since we have a convention that Resource names map one-for-one to Module names, it’s a simple check to see if the current user’s Role allows them access to that Resource. If it does, we simply do nothing and let control pass back to the Front Controller. If access is denied we have two branches - authenticated users are just kicked back to the index page (part of our default Module) while unauthenticated users are redirected to the login page for Authors.

Note: Setting the Module name on the request object for forwarding is required when using Modules. That includes setting references to non-moduled controllers/actions with the Module name of “default”.

Of course there are more complex scenarios again. What if the resource is not a Module, but a specific Action on a specific Controller within a Module? Obviously such a simple plugin as above would fall flat and need to be scraped off the floor. Again this is not dictated to you by the Zend Framework manual. It’s usually typical to make use of Privileges in Resources and interpret these as Actions. And as explained earlier you can use a “admin|entry” convention for the Module/Controller pairing.

Step 5: Initialising the Front Controller Plugin

Before our plugin is even used, we need to register it with the Front Controller. This is another change to our Bootstrap class! The new method setupAcl is at the bottom of the file.

In case they are needed for a more specific use case in a controller, I’ve added both the authentication and authorisation objects as Front Controller parameters.

Go boot up http://zfblog/admin for a test drive. If you have previously logged in, you can logout using http://zfblog/author/logout manually (it’s not part of our View yet).

Step 6: And Now For Something Completely Different…

With ACL implemented I find myself at a loose end. So I spent some time putting together two new stylesheets to add some colour and life to this application. You’ll need two new files:

/public/css/style.css
/public/css/ie.css

The first may already exist from an earlier Part of this series.

Edit style.css to contain the following CSS. I won’t explain it - this, thankfully, is not a CSS blog .

Now edit ie.css.

Now repeat after me: “Paddy is not a designer!”. I can’t say this is the most spectacular CSS ever written when it’s probably more in the opposite direction. But it works. I’m pretty sure it does anyway. Fingers crossed! There might be some IE7 issues because my conditional doesn’t specify a version so check back with subversion in a while if so.

We’re not done yet. We need to make two more edits to each of our previous Layout templates. Here’s the amended excerpt for each. It is identical for both /application/views/layouts/common.phtml and /application/admin/views/layouts/admin.phtml. Now since it’s identical we know we have some duplication in our layouts, which is undesirable, but we’ll fix that another day.

Just make matters worse, I added some small changes to our previous AuthorController and it’s related login template.

/application/controllers/AuthorController.php

The main change here was to add additional View variables to flag some conditions to the view template as used below. I tend to use flags a lot with Views since they are simple booleans and delegate the translation of these flags into some meaning to the View itself. It’s a really obvious gimmick I know but there are still lots of people who assign actual text without a second thought.

/application/views/scripts/author/login.phtml

Lastly I made another tiny change to the template for our Administration Modules index page:

/application/admin/views/scripts/index/index.phtml

Upon authentication, as noted in our AuthorController:loginAction() method, users are forwarded to the Admin Module index page. This addition merely informs the user they were authenticated which explain why they’ve ended up there .

Step 7: A Small Administration Template Update

Hindsight is great, but unfortunately you can’t make use of it on a live blog, so I’ll make a few quick changes now. What we’ll do is create a simple Administration Menu in the left column of our Administration Module’s templates.

Open up the file /application/admin/views/scripts/index/index.phtml and edit as follows:

The change merely replaces the early menu block with a simple greeting using the Author’s real name as stored from previous authentication.

Open up the file /application/admin/views/layouts/admin.phtml and edit as follows:

If editing the menu in looks odd, don’t worry yet. Those who really don’t like it can add it as a template partial or pass an array of menu data into a custom View Helper (I’ll be doing something similar in the near future to tidy up layouts). Finally, edit our stylesheet at /public/css/style.css to include the following styles for the now modified column.

Try out the application once more. It should now look a bit more presentable.

Conclusion

Implementing an ACL solution with Zend_Acl hasn’t proven difficult, in part due to the simplicity of our immediate needs. I would reiterate that remembering that Resources are not Controllers/Action, but merely virtual values which can be mapped or interpreted as such, is quite important. Using a 1:1 mapping is simply a common convention.

Since we’re on the cusp of entering the realm to create new blog entries, an update to styling is welcome. It’s not the final styling obviously, but looking at the minimalistic monotone output in my browser was becoming tiring .

In the next edition of this series we’ll visit the task of creating, editing and displaying new blog entries.

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.