Rob Allen's DevNotes

One thing that is different between Zend_Config_Xml and Zend_Config_Ini is that with Zend_Config_Xml you can pass in an XML string as the first parameter of the constructor and it will work. This doesn't work with Zend_Config_Ini as we use parse_ini_file() under the hood.

With PHP 5.3 however there is is a new function called parse_ini_string() which will allow us to load arbitrary ini string into Zend_Config objects. This can't go into Zend Framework 1 though due to our PHP 5.2.4 minimum version requirement.

As I needed this for a project, I extended Zend_Config_Ini to support this feature, which means simply overloading a single method

class App_Config_Ini extends Zend_Config_Ini
{
/**
* Load the INI file from disk using parse_ini_file(). Use a private error
* handler to convert any loading errors into a Zend_Config_Exception
*
* @param string $filename
* @throws Zend_Config_Exception
* @return array
*/
protected function _parseIniFile($filename)
{
set_error_handler(array($this, '_loadFileErrorHandler'));
if (substr($filename, -4) == '.ini') {
$iniArray = parse_ini_file($filename, true);
} else {
$iniArray = parse_ini_string($filename, true);
}
restore_error_handler();

return $iniArray;
}
}

The actual change is to see if the last 4 characters of the filename are ".ini" and if they aren't then use parse_ini_string() instead of parse_ini_file(). The rest of the code is just error handling.

This is one area where I really like it when a class implements methods that done just one thing.

One area of displaying lists on web pages that I've generally disliked doing is pagination as it's a bit of a faff. Recently, I needed to do just this though as I couldn't delegate it as my colleague was too busy on other work. As a result, I thought that I should look into Zend_Paginator this time. Turns out that it's really easy to use and the documentation is great too.

The really useful thing about Zend_Paginator is that it uses adapters to collect its data. There are a variety of adapters, including array, dbSelect, dbTableSelect and iterator. The interesting ones for me being dbSelect and dbTableSelect as I use Zend_Db based data access layers.

This is how I used it with a Zend_Db based data mapper within TodoIt.

Setting up the paginator

My current method looks like this:
class Application_Model_TaskMapper
{
public function fetchOutstanding()
{
$db = $this->getDbAdapter();
$select = $db->select();
$select->from($this->_tableName);
$select->where('date_completed IS NULL');
$select->order(array('due_date ASC', 'id DESC'));
$rows = $db->fetchAll($select);
foreach ($rows as $row) {
$task = new Application_Model_Task($row);
$tasks[] = $task;
}
return $tasks;
}

// etc


This is pretty standard code for a data mapper. We select the data from the database and convert it to an array of entities. For the paginator to do its stuff though, we have to pass it the select object so that it can set the limit() on the select object.

The code therefore becomes:
public function fetchOutstanding()
{
$db = $this->getDbAdapter();
$select = $db->select();
$select->from($this->_tableName);
$select->where('date_completed IS NULL');
$select->order(array('date_completed DESC', 'id DESC'));

$adapter = new Zend_Paginator_Adapter_DbSelect($select);
$paginator = new Zend_Paginator($adapter);
return $paginator;
}

As you can see, we create an instance of Zend_Paginator_Adapter_DbSelect which takes the $select object and the instantiate a Zend_Paginator and return it. The Zend_Paginator object implements Interator, so you can use it exactly like an array in a foreach loop and hence, in theory, your view script doesn't need to change.

However, the code that consumes TaskMapper expects an array of Task objects, not an array of arrays. To tell the paginator to create our objects, we extend Zend_Paginator_Adapter_DbSelect and override getItems() like this:

class Application_Model_Paginator_TaskAdapter extends Zend_Paginator_Adapter_DbSelect
{
/**
* Returns an array of items for a page.
*
* @param integer $offset Page offset
* @param integer $itemCountPerPage Number of items per page
* @return array
*/
public function getItems($offset, $itemCountPerPage)
{
$rows = parent::getItems($offset, $itemCountPerPage);

$tasks = array();
foreach ($rows as $row) {
$task = new Application_Model_Task($row);
$tasks[] = $task;
}
return $tasks;
}
}

Here, we've used the entity-creation code that was in our original implementation of fetchOutstanding() and placed it in getItems().

Obviously we have to update fetchOutstanding() to use our new adapter, so we replace
$adapter = new Zend_Paginator_Adapter_DbSelect($select); with $adapter = new Application_Model_Paginator_TaskAdapter($select);

Now, when we iterate over the pagination object, we get instances of Task and all is well with the world.

Using the paginator

Now that we have a paginator in place, we need to use it. Specifically we need to tell the paginator which page number we want to view and how many items are on a page. Within TodoIt, this is done in the ServiceLayer object and looks something like this:

class Application_Service_TaskService
{
// ...

// ...

Clearly the $page parameter comes via the URL at some point, so the controller looks something like this:

class IndexController extends Zend_Controller_Action
{
public function indexAction()
{
$page = $this->_getParam('page', 1);

//...

and then the view uses a foreach as you'd expect.

Adding the paging controls

Finally, to complete a paged list, we have to provide the user a mechanism to select the next and previous pages along with maybe jumping to a specific page. This is done using a separate view script that you pass to the paginator. In your view script, you put something like:


<?php echo $this->paginationControl($this-> outstandingTasks,
'Sliding',
'pagination_control.phtml'); ?>

The first parameter is your paginator object. The second is the 'scrolling style' to use. There are four choices documented in the manual: All, Elastic, Jumping and Sliding. Personally, I have chosen to not display the page numbers themselves, so it doesn't matter which one I pick. The last parameter is the partial view script that you want to be rendered. This allows you to have complete customisation of the HTML.

Here's what I'm using which is based heavily on and example in the documentation:
<?php if ($this->pageCount): ?>
<div class="pagination-control">
<!-- Previous page link -->
<?php if (isset($this->previous)): ?>
<a href="<?php echo $this->url(array('page' => $this->previous)); ?>">
Previous
</a> |
<?php else: ?>
<span class="disabled">&lt; Previous</span> |
<?php endif; ?>

<!-- Next page link -->
<?php if (isset($this->next)): ?>
<a href="<?php echo $this->url(array('page' => $this->next)); ?>">
Next &gt;
</a>
<?php else: ?>
<span class="disabled">Next &gt;</span>
<?php endif; ?>
<span class="pagecount">
Page <?php echo $this->current; ?> of <?php echo $this->pageCount; ?>
</span>
</div>
<?php endif; ?>

And that's it; I now have paginated tasks in TodoIt and as you can see, Zend_Paginator is very easy to use and, more importantly, simple to customise to your own needs.

A while ago I needed to ask a user for their date of birth on a Zend_Form. The design showed three separate select elements to do this:

A little bit of googling found this site http://codecaine.co.za/posts/compound-elements-with-zend-form which has not unfortunately disappeared, so the code in this article owes a lot of the author of that article.

It turns out to be remarkably simple to create a single Zend Form element that is rendered as multiple form elements. We create an element object and a view helper object and we're done. Usage then looks like:

<?php

$this->addElement('submit', 'Go');
}
}

Obviously, this form lives in application/forms/Detail.php and is rendered as usual in a view script. In our form definition, we have added an element called 'date' and with the addition of the addPrefixPath call have told the form that in addition to using the standard Zend Framework form elements, also look in library/App/Form. (Incidentally, we can also now override any supplied form element by simply dropping a replacement into the libraryApp/Form folder.)

The date form element lives in library/App/Form/Element/Date.php as Zend_Form knows to look in a subfolder for App/Form called Elements for any element objects and will look in the Decorator/ sub folder for decorator objects.

The Date element looks like this:
// Based on code from
// http://codecaine.co.za/posts/compound-elements-with-zend-form
class App_Form_Element_Date extends Zend_Form_Element_Xhtml
{
public $helper = 'formDate';

}

There's quote a lot going on here, but it should be fairly clear. Firstly we specify the name of the view helper to use when rendering this element to be formDate which we will write. We know this element is going to consist of three select boxes and so these will end up being an array of posted data for day, month and year. As a result, we need to override isValid() to turn our array back into a string and then call up to the parent's isValid() in order to do the actual validation required. We also need to override getValue() in the same way to ensure that it is also a string. Again we call up to the parent's getValue() as that does filtering.

That's all there is to the element itself, so now we turn out attention to the view helper that will render the element. This lives in library/App/View/Helpers/FormDate.php and as per my view helpers post, we need to tell the view about that folder via application.ini:

autoloadernamespaces[] = "App_"
resources.view.helperPath.App_View_Helper = "App/View/Helper"


The formDate view helper code looks like this:

<?php

// return the 3 selects separated by  
return
$this->view->formSelect(
$name . '[day]',
$day,
$dayAttribs,
$dayMultiOptions) . ' ' .
$this->view->formSelect(
$name . '[month]',
$month,
$monthAttribs,
$monthMultiOptions) . ' ' .
$this->view->formSelect(
$name . '[year]',
$year,
$yearAttribs,
$yearMultiOptions
);
}
}


Again, there's a fair amount of code, but I expect that it's pretty self-explanatory. Essentially, we have a lot of set up in order to render three select boxes; one for the day, month and year. I decided to use month names but it's easy enough to change to numbers. In terms of configuration, you need to be able to specify the start and stop year numbers. These are then passed in as options when calling addElement.

That's about it. Two separate files is all you need to create a Zend_Form element object that is implemented via compound elements. It also follows that you can do the same for any other conceptual element that you want to be rendered as multiple elements in the page.

I can't seem to find an article here that consolidates my thoughts on Zend Framework's view helper system, so I thought I'd better correct that. Zend Framework's Zend_View component supports helper methods known as view helpers. They are used like this in a view script:

<?php echo $this->myHelper('myParam1'); ?>

Behind the scenes, this is implemented as a method within a class something like this:

<?php

class Zend_View_Helper_MyHelper extends Zend_View_Helper_Abstract
{
public function myHelper($myParam1)
{
$html = '';
// some logic that fills in $html.
return $html;
}
}

Note that by convention, view helpers return the string and then the view script echos it and the Zend_View_Helper_ section of the class name is known as the prefix.

A typical Zend Framework project using Zend_Application, such as that generated using the zf command line tool, will have a folder called helpers within the views folder for each module. There will also be a helpers folder within the layouts folder too. If you place your view helper in one of these helpers folders, then the prefix is Zend_View_Helper_.

We can also tell the view object about our own view helper folder. Typically this will live in the library/App/View/Helper/ folder and so, you probably want a prefix of App_View_Helper_. To do this, we simply add this line to application.ini:

resources.view.helperPath.App_View_Helper_ = "App/View/Helper/"

The view helper now lives in App/View/Helper/MyHelper.php and looks like this:

<?php

class App_View_Helper_MyHelper extends Zend_View_Helper_Abstract
{
public function myHelper($myParam1)
{
$html = '';
// some logic that fills in $html.
return $html;
}
}

Due to the way Zend Framework's plugin loader works, our view script doesn't change at all as the view object's plugin loader will look across all registered paths to find the view helper specified in the view script.

I tend to prefer using the App folder over the helpers folder within layouts as I like to have one place to go to for my "site-wide" classes and so my App folder contains front controller plugins, validators, filters, form elements as well.

As you have extended Zend_View_Helper_Abstract for creating your own helper, you have access to the view object itself too. This is helpful for accessing other view helpers, such as escape. My personal preference is for my view helpers to manage their own escaping as requires as that way I can include html tags within my helper.

For example, suppose we want to create a table from an array that looks like this:

$data = array();
$data[] = array('Name', 'Email');
$data[] = array('Alison', 'alison@example.com');
$data[] = array('Bert', 'bert@example.com');
$data[] = array('Charlie', 'charlie@example.com');

Our view script may look like this:

<?php echo $this->tabulate($this->data, array('class'=>'tabulated')); ?>

(assuming our designer wants a class name attached to the table for styling.)

The view helper itself would then look something like:

<?php

$html .= '</table>';
return $html;
}
}

As you can see, we cannot escape the output of the view helper, so the view helper has to do its own escaping via the view property.

If you end up using the same set of view helpers on each project you do, then consider putting then into a vendor library. This is the same concept as using the App folder, but you use a different name (I use Akrabat) and store them in a separate vcs repository. This allows you easy reuse. You add a new line to application.ini to pick them up:

resources.view.helperPath.Akrabat_View_Helper_ = "Akrabat/View/Helper/"

and you're done. Note that the order of the helperPath in application.ini is important. You want the vendor path before the App path so that you can override your vendor ones specifically within a project if you need to.

resources.view.helperPath.Akrabat_View_Helper_ = "Akrabat/View/Helper/"
resources.view.helperPath.App_View_Helper_ = "App/View/Helper/"

Plugin helper path order is one of the more frustrating things about the plugin loaders used within Zend Framework and affects form elements, validators, filters and view helpers to name but a few. So if you discover that a view helper isn't being called when you think it ought to be, then check that it's not being overridden further down the chain. You can of course use this to your advantage and override a default Zend Framework view helper by simply creating an App version with the same name.

Let's say that you want to use your own view object within your Zend Framework application.

Creating the view object is easy enough in library/App/View.php:

class App_View extends Zend_View
{
// custom methods here
}

along with adding the App_ namespace to the the autoloader in application.ini:
autoloadernamespaces[] = "App_"

All we need to now is get Zend_Application to bootstrap with our new view class. There are two ways of doing this: within Bootstrap.php or using a custom resource.

_initView() in Bootstrap.php

At first blush, the code looks quite easy. In application/Bootstrap.php, we add our own method that creates the view object and assigns it to the viewRenderer:


class Bootstrap extends Zend_Application_Bootstrap_Bootstrap
{
protected function _initView()
{
$view = new App_View();

$viewRenderer = new Zend_Controller_Action_Helper_ViewRenderer();
$viewRenderer->setView($view);
Zend_Controller_Action_HelperBroker::addHelper($viewRenderer);
return $view;
}
}


As we have named the method _initView(), our method will take precedence over the built in View resource and be used instead. However, this implementation will ignore any view options that are configured in application.ini using the resources.view key, so a better method is this:

class Bootstrap extends Zend_Application_Bootstrap_Bootstrap
{
protected function _initView()
{
$resources = $this->getOption('resources');
$options = array();
if (isset($resources['view'])) {
$options = $resources['view'];
}
$view = new App_View($options);

}

This version takes into account your configuration settings and behaves the same as the View resource provided by Zend Framework. The only difference is that we're now using App_View.

Custom resource

Another option is to override Zend_Application_Resource_View with our own view resource. In this case, we create a class called App_Resource_View stored in library/App/Resource/View.php. We only need to override one method, getView():

class App_Resource_View extends Zend_Application_Resource_View
{
public function getView()
{
if (null === $this->_view) {
$options = $this->getOptions();
$this->_view = new App_View($options);

if (isset($options['doctype'])) {
$this->_view->doctype()->setDoctype(strtoupper($options['doctype']));
if (isset($options['charset']) && $this->_view->doctype()->isHtml5()) {
$this->_view->headMeta()->setCharset($options['charset']);
}
}
if (isset($options['contentType'])) {
$this->_view->headMeta()->appendHttpEquiv('Content-Type', $options['contentType']);
}
}
return $this->_view;
}
}

Essentially, all I have done is replace the class of the view object to be App_View and left everything else alone so that it behaves the same as the default View resource.

To get Zend_Application to load our custom resource, we just add one line to application.ini:

pluginPaths.App_Resource = "App/Resource"

We now have a reusable resource that will load our own View class and can easily take it from project to project.