He uses my tutorial as the starting point which enables him to concentrate on the Doctrine integration rather than the irrelevant details about setting a ZF2 application which is excellent.

He walks through 6 steps in order to do the integration:

This article shows how to set up and use Doctrine 2 in Zend Framework 2, by extending Rob’s Getting Started tutorial to use Doctrine instead of Zend_Db.

• Start with Akrabat’s tutorial
• Install Doctrine modules
• Configure the Album module to use Doctrine
• Create the Album entity
• Update the Album controller to use Doctrine instead of Zend_Db
• That’s it!

I highly recommend having a read if you're at all interested in using Doctrine 2 with Zend Framework 2.

The key new features are:

• Refactored Mail component
• Refactored Cache component
• MVC updates

Check out Matthew's blog post for the full details.

I've also updated my tutorial. This is a good time to get involved, try it out and let us know what you like/dislike.

Getting started with Zend Framework 2 (beta1), creates the same application as my ZF1 tutorial, so it should be very familiar, but this time, it's in the context of Zend Framework 2. As usual, it's a PDF too.

Please download it, try it out and let me know if you find any typos!

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();

        // Check if there was a error while loading file
        if ($this->_loadFileErrorStr !== null) {
            /**
             * @see Zend_Config_Exception
             */
            require_once 'Zend/Config/Exception.php';
            throw new Zend_Config_Exception($this->_loadFileErrorStr);
        }

        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.

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
{
    // ...

    public function fetchOutstanding($page, $numberPerPage = 25)
    {
        $mapper = new Application_Model_TaskMapper();
        $tasks = $mapper->fetchOutstanding();
        $tasks->setCurrentPageNumber($page);
        $tasks->setItemCountPerPage($numberPerPage);        
        return $tasks;
    }

    // ...

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);

        $taskService = new Application_Service_TaskService();
        $this->view->outstandingTasks = $taskService->fetchOutstanding($page);
        
        $messenger = $this->_helper->flashMessenger;
        $this->view->messages = $messenger->getMessages();
    }

    //...

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 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

class Application_Form_Details extends Zend_Form
{
    public function init()
    {
        $this->addPrefixPath('App_Form', 'App/Form/');

        // other elements before 
        
        $this->addElement('date', 'date_of_birth', array(
            'label' => 'Date of birth:'
        ));
        
        // other elements after

        $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';

    public function isValid ($value, $context = null)
    {
        if (is_array($value)) {
            $value = $value['year'] . '-' .
                $value['month'] . '-' .
                $value['day'];
            
            if($value == '--') {
                $value = null;
            }
        }

        return parent::isValid($value, $context);
    }

    public function getValue()
    {
        if(is_array($this->_value)) {
            $value = $this->_value['year'] . '-' .
                $this->_value['month'] . '-' .
                $this->_value['day'];

            if($value == '--') {
                $value = null;
            }
            $this->setValue($value);
        }

        return parent::getValue();
    }

}

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

// based on code from
// http://codecaine.co.za/posts/compound-elements-with-zend-form

class App_View_Helper_FormDate extends Zend_View_Helper_FormElement
{
    public function formDate ($name, $value = null, $attribs = null)
    {
        // separate value into day, month and year
        $day = '';
        $month = '';
        $year = '';
        if (is_array($value)) {
            $day = $value['day'];
            $month = $value['month'];
            $year = $value['year'];
        } elseif (strtotime($value)) {
            list($year, $month, $day) = explode('-', date('Y-m-d', strtotime($value)));
        }

        // build select options
        $dayAttribs = isset($attribs['dayAttribs']) ? $attribs['dayAttribs'] : array();
        $monthAttribs = isset($attribs['monthAttribs']) ? $attribs['monthAttribs'] : array();
        $yearAttribs = isset($attribs['yearAttribs']) ? $attribs['yearAttribs'] : array();

        $dayMultiOptions = array('' => '');
        for ($i = 1; $i < 32; $i ++)
        {
            $index = str_pad($i, 2, '0', STR_PAD_LEFT);
            $dayMultiOptions[$index] = str_pad($i, 2, '0', STR_PAD_LEFT);
        }
        $monthMultiOptions = array('' => '');
        for ($i = 1; $i < 13; $i ++)
        {
            $index = str_pad($i, 2, '0', STR_PAD_LEFT);
            $monthMultiOptions[$index] = date('F', mktime(null, null, null, $i, 01));
        }

        $startYear = date('Y');
        if (isset($attribs['startYear'])) {
            $startYear = $attribs['startYear'];
            unset($attribs['startYear']);
        }

        $stopYear = $startYear + 10;
        if (isset($attribs['stopYear'])) {
            $stopYear = $attribs['stopYear'];
            unset($attribs['stopYear']);
        }

        $yearMultiOptions = array('' => '');

        if ($stopYear < $startYear) {
            for ($i = $startYear; $i >= $stopYear; $i--) {
                $yearMultiOptions[$i] = $i;
            }
        } else {
            for ($i = $startYear; $i <= $stopYear; $i++) {
                $yearMultiOptions[$i] = $i;
            }
        }

        // return the 3 selects separated by &nbsp;
        return
            $this->view->formSelect(
                $name . '[day]',
                $day,
                $dayAttribs,
                $dayMultiOptions) . '&nbsp;' .
            $this->view->formSelect(
                $name . '[month]',
                $month,
                $monthAttribs,
                $monthMultiOptions) . '&nbsp;' .
            $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.

<?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

class App_View_Helper_Tabulate extends Zend_View_Helper_Abstract
{
    public function tabulate ($data, $attribs = array())
    {
        $attribString = '';
        foreach ($attribs as $key => $value) {
            $attribString .= ' ' . $key .'="' . $value . '"';
        }

        $header = array_shift($data);
        $html = "<table $attribString>\n<tr>\n";
        foreach ($header as $cell) {
            $escapedCell = $this->view->escape($cell);
            $html .= "<th>$escapedCell</th>\n";
        }
        $html .= "</tr>\n";
        foreach ($data as $row) {
            $html .= "<tr>\n";
            foreach ($row as $cell) {
                $escapedCell = $this->view->escape($cell);
                $html .= "<td>$escapedCell</td>\n";
            }
            $html .= "</tr>\n";
        }

        $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.

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);

        if (isset($options['doctype'])) {
            $view->doctype()->setDoctype(strtoupper($options['doctype']));
            if (isset($options['charset']) && $view->doctype()->isHtml5()) {
                $view->headMeta()->setCharset($options['charset']);
            }
        }
        if (isset($options['contentType'])) {
            $view->headMeta()->appendHttpEquiv('Content-Type', $options['contentType']);
        }
        
        $viewRenderer = new Zend_Controller_Action_Helper_ViewRenderer();
        $viewRenderer->setView($view);
        Zend_Controller_Action_HelperBroker::addHelper($viewRenderer);
        return $view;
    }

}

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.

Let's explain, by using code from the tutorial.

In the layout.phtml file, we link to a CSS file like this:

<?php echo $this->headLink()->prependStylesheet($this->baseUrl().'/css/site.css'); ?> 

This code uses a baseUrl() view helper that looks like this

<?php 
class Zend_View_Helper_BaseUrl 
{ 
    function baseUrl() 
    { 
        $fc = Zend_Controller_Front::getInstance(); 
        return $fc->getBaseUrl(); 
    } 
}

When you go to http://localhost/zf-tutorial/ you get an page that looks like this:

However, if you go to http://localhost/zf-tutorial/index.php, you get this:

This happens because the baseURL used in the href of the CSS link in the second case is /zf-tutorial/public/index.php/css/site.css rather than the correct /zf-tutorial/public/css/site.css.

Solution using mod_rewrite

One way to fix this is to use a mod_rewrite rule in your .htaccess file:

RewriteCond %{THE_REQUEST} ^[A-Z]{3,9} /([^/]+/)*index.php 
RewriteRule ^index.php(.*)$ /zf-tutorial/public$1 [R=301,L]

I did have to put the full subdirectory into the rewrite rule to get it to work.

The quick and dirty solution

At the top of your index.php file take out the index.php from the REQUEST_URI:

$_SERVER["REQUEST_URI"] = str_replace('index.php','',$_SERVER["REQUEST_URI"]);

This obviously works, but feels a bit "hacky"! There's probably other ways to solve it too, but once I found the rewrite rule, I stuck with it.

This is how to handle errors in a Front Controller plugin:

1. Prefer preDispatch() over dispatchLoopStartup() as it is called from within the dispatch loop
2. Catch the exception and the modify the request so that the error controller's error action is dispatched.
3. Create an error handler object so that the error action works as expected.

This is the code:

<?php

class Application_Plugin_Foo extends Zend_Controller_Plugin_Abstract
{
    public function preDispatch(Zend_Controller_Request_Abstract $request)
    { 
        try {

            // do something that throws an exception

        } catch (Exception $e) {
            // Repoint the request to the default error handler
            $request->setModuleName('default');
            $request->setControllerName('error');
            $request->setActionName('error');

            // Set up the error handler
            $error = new Zend_Controller_Plugin_ErrorHandler();
            $error->type = Zend_Controller_Plugin_ErrorHandler::EXCEPTION_OTHER;
            $error->request = clone($request);
            $error->exception = $e;
            $request->setParam('error_handler', $error);
        }
    }

}

That's it.