Installing Twig

This really couldn’t get a lot simpler with pear:

    $ pear channel-discover pear.twig-project.org
    $ pear install twig/Twig

or, you can use the Git or Subversion repos as detailed on the projects website: http://www.twig-project.org/doc/intro.html

The Application Resource

Setting up a ZF application resource for twig is a snip! The minimal config required to set up a Twig instance, is exactly that, minimal!

Simple create the class “Core_Resource_Twig” and place it in library/Core/Resource/Twig.php and consider the following code:

<?php

class Core_Resource_Twig extends Zend_Application_Resource_ResourceAbstract
{
    /**
     * @var Twig_Environment
     */
    protected $twig;

    public function init()
    {
        $options = $this->getOptions();
        $loader = new Twig_Loader_Filesystem($options['templateDir']);
        $this->twig = new Twig_Environment(
                $loader,
                $options['options']
        );
        return $this->twig;
    }
}

All we are doing here, is creating an instance of the Filesystem Twig loader, which loads templates from files, and then passing that in to the Twig Environment, along with the rest of the options from our config, which in brief, would now look something like this:

[production]
autoloaderNamespaces[] = "Twig_"
pluginPaths.Core_Resource = APPLICATION_PATH "/../library/Core/Resource"

; FRONT CONTROLLER
resources.frontController.moduleDirectory = APPLICATION_PATH "/modules"
resources.frontController.controllerDirectory.default = APPLICATION_PATH "/controllers"
resources.frontController.noViewRenderer = true

; TWIG
resources.twig.templateDir = APPLICATION_PATH "/templates"
resources.twig.options.cache = APPLICATION_PATH "/../cache/twig"

[development : production]
resources.twig.options.debug = true
resources.twig.options.auto_reload = true

That now gives us two things, a configured Twig instance, and an application resource to hold it, which will be present in the invoke args in your controller. so for the next step, we stitch it together, and make it more useable, to make things super simple, a base controller class is useful here. The reason for a base controller class rather than an action helper is simple, performance, and simplicity; no need for the complexity or auto-rendering anything, we will simply call a method at the end of each action.

Given that we are now using twig, this has two benefits, we avoid the overhead of how ZF looks up the view name to decide which view template to render, which is a part of the bottleneck of ZF, and additionally, it matches more closely to the other documentation you’ll find on Twig elsewhere, and we are doing things in a slightly different manner to how we would use Zend_View, so why try to emulate it, when we are using something very different!

<?php

abstract class Core_Controller extends Zend_Controller_Action
{
    public function twig($template, array $vars)
    {
        $twig = $this->getBootstrap()->getResource('twig');

        $template = $twig->loadTemplate($template);
        $this->getResponse()->appendBody(
            $template->render($vars),
            'default'
        );
    }
}

Rendering the template

Now that we have our base controller class, we can now use our template, in this manner from our action:

<?php

class IndexController extends Core_Controller
{
    /**
     * @var Core_Service_Posts
     */
    protected $service;

    public function init()
    {
        $this->service = new Core_Service_Posts();
    }

    public function indexAction()
    {
        $recent = $this->service->recentPosts();
        $this->twig('home.twig', array(
            'recent' => $recent,
        ));
    }

    public function viewAction()
    {
        $id = $this->getRequest()->getParam('id', false);
        if (false === $id) {
            throw new Core_InvalidIdException('No ID Present');
        }

        $paste = $this->service->byId($id);

        $this->twig('view-post.twig', array(
            'post' => $paste,
        ));
    }

}

In this example, you have the indexAction, taking the service for the posts for the application, and passing the recent posts to the template, and in the view action, taking the selected post, and passes it to the template, with the selection of template for the action being passed as the first argument to our twig method we added to the base controller class.

And now, you can find examples and documentation on how to put together your twig templates here http://www.twig-project.org/documentation.

This part of the Framework causes the dispatch to loop. This is a costly process, as it involves quite alot. It also adds some further issues to your application design, such as where you should put code. for example if you have some code in your predispatch, and your looping through two actions in that controller, that code will be run twice. This is obviously, not good, and quite un-needed. Further complications can be added when it comes time to add ACL or authentication.

There is an even worse part of this feature, the Action View Helper. This helper basically creates an additional dispatch, copying the request object, and creating a loop-within-a-loop . The setting up of the dispatch process is a costly one, anyone who has profiled their code will have seen just how much of the process of a Zend Framework application this eats up. Creating a whole extra dispatch must be a bad idea, even the Zend Framework Performance Guide notes this fact

So, lets go through some reasons for this being bad.

Why its bad

Performance

Every time you go through the dispatch process, there are a number of things which are done, which will be completly un-nessicary for your action, namely calling preDispatch and postDispatch for each action which is called. This often results in questions in #zftalk of “Why is my ACL being called twice?”. If you have an ACL being built in your preDispatch (as many people quite rightly do) this means if you have 3 calls to different actions, your ACL will be built, and queried 3 times, and if you haven’t cached your ACL object, this may incur extra overhead from calls to database queries.

This is even more apparent if you use the action helper, as the request is copied, and a new dispatch created (profile your code and see just how much overhead this involves, its a lot!).

Unnecessary Complexity

Trying to follow the application flow through an application which utilises the action stack adds a level of complexity which need not be there.

If you want to see what’s going on at a URL, you should be able to go to that action, and see which model methods are being invoked, and what is being passed to the view.

Design Issues

This is the biggest reason for not using the action stack. If you are using the action stack, you are almost certainly a long way from a true “MVC” design. The units of code you are using in your actions, probably belongs in the model.

Your model should encapsulate all the code to extract data, insert data, and manipulate objects, so all your controller action should include is a bunch of calls to the model to fetch data, or insert/update it, but in the form of single method calls only. remember you should be directing the data to the model, not manipulating it.

Why it is good

Illusion of DRY coding

The action stack can lead you into a false sense of security that your writing nice “DRY” code. You are in fact writing dry code, but usually in the wrong place, in fact, if your code is not abstracted into your model, it will end up no-longer being dry, as you will end up with two actions with overlapping functionality, and as such, overlapping code!

The way forward

Fat Models, Thin Controllers

Your controllers should be minimalist. they exist only to direct data, and to provide some interface to HTTP actions such as redirects.

The bulk of the code in your application should be in your model. For example, if you are writing a blog application, and the action you are writing produces a list of posts. This should require in the action, nothing more than a call to $model->getPosts(); possibly passing one or more paramaters from the URL (such as year and month) as parameters to the method.

This not only allows you to do away with the action stack, but also allows your code to be portable throughout the application, in true DRY style.

There is an upcomming book, which has a very good overview of how these kinds of models should be written. You can read it here

View Helpers

View helpers can be useful for items which you frequently need, or for items which are simply too small to justify writing a whole view script for them. there is a good example in the performance guide.

When you want to perform some logic before rendering a view script, a view helper can also be useful to help keep your layout or view free of large switches or if statements. For example this can be something like rendering a login form when a user is not logged in (which would require no view script, only a Zend_Form object), and a menu when they are, or be useful to set up some context for a view partial before rendering it, so that your controller does not have to pass a variable to the view when it would be some default value.

(Partial) Views

Partial views do the leg work of replacing the actionstack. In your partial views, you should call read-only methods of the model, to build items such as menus. this could be something like $model->getSideBarMenuItems(); which would return a dataset to loop through and render.

Some other notes

There has been an issue raised in the Zend Framework JIRA (ZF-5840) with regard to removing the action view helper for ZF version 2.0. This is somewhere you may wish to post your opinion on this subject (keep it specific!), or vote to have it removed .

This proposal has now been accepted and is available in the incubator.

During the process of refining the proposal, Ralph Schindler suggested renameing the validator, and splitting it in two, to make it as verbose as possible (i.e. the name says exactly what it does). So, an abstract class has been added, and the DbMatch name dropped. The validators are  now called Zend_Validate_Db_RecordExists and Zend_Validate_Db_NoRecordExists. check the wiki page for more information.

The code i have proposed should allow you to check if a value exists in a given field of a given table, and be easy to attach to your forms.

If you want to see this in the Zend Framework, or want to see the source see the proposals page in the ZF Wiki.

You can find the Zend_Validate_DbMatch proposal in full here