PHP General

There's nothing quite like having a functioning application emerge out of the controlled chaos we know as The Development Process. In Part 8 of the ongoing saga describing how to build a real world blog application using the Zend Framework we finally reach the point at which we concentrate on blog entries. At the end of this Part, we will be able to create and edit entries in preparation for Part 9 when we will explore displaying them to the world!

Previously: Example Zend Framework Blog Application Tutorial - Part 7: Authorisation with Zend_Acl and Revised Styling

The reason displaying entries is not addressed here is simple. Display requires a lot of Zend_View work which is deserving of an article to itself before we go too far. A few of you have already noted in comments about our suspicious lack of View Helper usage . By now a few uncomfortable flaws should be becoming apparent in how some template content is becoming duplicated.

So, on with the show already!

Step 1: Adding an Entry Controller and Add Action Template

The first step to creating new entries will be writing an Admin_EntryController class (the prefix is needed since it's situated in the Admin Module) with an addAction() method and matching template.

The template will utilise a new Zend_Form object for gathering the input used to create a new entry, as well as offering an editing View.

We'll start with the Controller, added at /application/admin/controllers/EntryController.php:



The EntryController needs four basic methods. We intend creating, editing and deleting entries, as well as listing all entries to an Author to select those options.

We'll concentrate on the addAction() method first, so let's add an appropriate template at /application/admin/views/scripts/entry/add.phtml which has an old friend referred to:



Let's accompany our blog entry forms with a little Jonathan Swift for inspiration . We once again meet a validation problem message identical to the one in our login form. As we're duplicating this message we're going to have to consider a means later on of isolating such commonly used feedback messages for reuse somewhere in Part 9.

To keep our styling synchronised with our intended form output, add the following to /public/css/style.css:



This should provide a decent styling for textareas for most browsers. Perhaps even Safari which I noticed recently is displaying some of my text fields poorly.

Step 2: Assembling the Entry Form with Zend_Form

We've already had a fairly detailed look at Zend_Form back in Part 6 when we wrote a subclass to contain some standard and specific decorator arrays for form elements, and created our Login Form example. The same principles used there also apply here with very few changes. Once again we are using the shorter array-based syntax over multiple method calls. One of the differences to take note of is that I've used two new options attribs and value which no form developer could live without!

We'll start with a new class called ZFBlog_Form_EntryAdd located at /library/ZFBlog/Form/EntryAdd.php:



I threw in a sprinkling of Zend_Date above to format the current date to a format compatible with a MySQL database. Zend_Date is also used in the background by the Zend_Validator_Date class which is why the date formatting is identical to both. Note that the formatting is not the PHP regular style used by the date() function, but instead uses ISO format specifiers. This offers a great deal of flexibility if you want something other than MySQL formatted dates.

Finally note that there is no "required" flag for the "entrybodyextended" element since an extended body is optional.

We're not quite done yet. Our two textareas, as discussed way back in Part 1, are being designed to accept HTML input since I really can't be bothered to play with custom formatting tags and such. This obviously raises the risk that I, another author, or someone who's guessed my password may, either by mistake or intent, add some Cross-Site Scripting (XSS) into the mix and introduce a devastating security exploit. We can't have that now!

Step 3: Filtering Entries using a HTMLPurifier based Custom Filter

What we will do now is attach a custom filter to the textareas containing our Entry data that cleans up any HTML input, removes XSS, and as a bonus converts any non-HTML input into formatted HTML. This, for example, covers our text paragraphs by wrapping them in <p> tags.

My favourite library for achieving this is HTMLPurifier which I consider one of those much under utilised libraries in PHP. To my knowledge, there is nothing out there to beat its comprehensive feature list. Its finest feature is that it actually understands HTML across multiple standards. Input is tokenised, parsed, passed through a whitelist (the opposite of a detection blacklist), reformed as perfectly correct valid output, and then it can optionally wrap stuff like plain text in paragraphs. All for your preferred DTD. Either you're using HTMLPurifier, or you are using something second or third rate, and I have no qualms whatsoever in stating that as a fact. I cannot praise this library more highly.

To start, you'll need to download a copy of HTMLPurifer 3.1.0rc1 (which is the latest release at the time of writing) and copy the contents of the package's /library directory into our blog application's /library. Since HTMLPurifer follows the PEAR Convention for class naming and file location, we need make no changes to our include_path. If you prefer, you can also install HTMLPurifer from its PEAR channel as described on the download page. Although it's a release candidate I haven't run into any problems using it other than my unexplainable habit of mispelling HTMLPurifier as HTMLPurifer which has led to a few frustrating hair pulling moments!

HTMLPurifier's perfection is not without a performance cost. To improve performance it will utilise a HTML definition cache. Add a new base directory at /cache/htmlpurifier and grant permissions sufficient to let the webserver write files there. Don't get too caught up over performance as security isn't an area you want to needlessly play Scrooge with . The performance cost is really only noticeable if using it for post-processing of output being sent to visitors. The cache coupled with the fact HTMLPurifier is used only in the backend Administration eliminates any such cost for the purposes of our application.

Let's introduce our custom filter classes. I'm saving them using a mirror directory structure of the Zend Framework as usual. Here a standard one I usually use with HTMLPurifier saved to /library/ZFBlog/Filter/HTMLPurifier.php:



HTMLPurifier options have three distinct elements we can pass to this filter as an array. We could stop here, passing filter options for every form, but this is a very general filter class whose sole purpose is to pass options into HTMLPurifier, so let's add a subclass of this specifically for HTML textual input with predefined options at /library/ZFBlog/Filter/HtmlBody.php:



This new subclass passes specific options to HTMLPurifier. We provide the path to the cache directory created previously, inform the library our output should conform to XHTML 1.0 Strict, add a whitelist of allowed tags and attributes, and finally enable two optional formatting helpers to auto paragraph output (wrapped with <p> tags) and transform URLs into hyperlinks. If ZFBlog_Filter_HtmlBody needs further adjustment we can pass it options when attaching this filter to our form elements.

This really is how HTMLPurifer works. By using sensible defaults, configuration before use is extremely simple.

With our two custom filters in tow, we now need to make sure the Zend Framework can actually find them! We've done this previously actually when registering a custom decorator path with Zend_Form. Let's repeat the process. Here's an updated ZFBlog_Form class from /library/ZFBlog/Form.php:



Now Zend_Form can use our custom filters. The last thing we do is attach our new HtmlBody custom filter to our new form along with a few other filters for good measure:



Let's get this form attached to a View now.

Continue reading "Example Zend Framework Blog Application Tutorial: Part 8: Creating and Editing Blog Entries with a dash of HTMLPurifier"

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.


Continue reading "Example Zend Framework Blog Application Tutorial - Part 7: Authorisation with Zend_Acl and Revised Styling"