Sometimes, Integrations Come with Setbacks

In a previous post here at engfers.com, we talked about how to fully integrate the PHP templating engine, Smarty, with the Zend Framework by replacing the implementation of the viewRenderer’s Zend_View_Interface with a Zend_View_Smarty implementation.

Unfortunately, by using this solution, any reference to the $this pointer in the template land references the Smarty object instead of Zend_View.

Well, the Smarty object doesn’t contain the nice “url-ifier” ($this->url()). With the “url-ifier” (Zend_Controller_Action_Helper_Url), one could specify the module, controller, action and request parameters as an associative array parameter, and it would generate a nice and pretty url for you.

Well, we wanted that functionality back!

Hacks

At first thought, one might be tempted to use the {php}...{/php} template tags in Smarty. Don’t do it! It’ll totally invalidate the whole point of using Smarty and it’s ugly as snot.

Another creative way to accomplish this is to do some sort of fancy template variable assignment that gives you access to some method, object or whatever; don’t do this either.

The correct way to accomplish the task at hand is to make a Smarty plugin that emulates the functionality of whatever Zend_Controller_Action_Helper_Url did.

The Smarty Plugin

Read the comments section in the code and see the examples section for template implementations.

The Code: function.zend_url.php

Just copy this and plop it in your $smarty->plugins_dir and call it function.zend_url.php

// @depends Zend_Controller_Front from Zend Framework

/**
 * Type:     function
 * Name:     zend_url
 * Purpose:  Generate a url based on the default front
 *  controller's router rules. It's just a proxy method to
 *  the router's assemble() method. This was meant to
 *  replace view calls to $this->url();
 *
 * Parameters:
 *  module (optional)
 *    - module name
 *  controller (optional)
 *    - controlle name
 *  action (optional)
 *    - action name
 *  zend_url_name (optional)
 *    - see Zend_Controller_Router_Interface::assemble()
 *  zend_url_reset (optional)
 *    - see Zend_Controller_Router_Interface::assemble()
 *  zend_url_encode (optional)
 *    - see Zend_Controller_Router_Interface::assemble()
 *
 * Other url parameters can be passed via 'key="value"'
 *
 * Example:
 * {zend_url module="myapp" controller="blog"
 *    action="edit" postId="232" user="admin"}
 *
 * @author David Engfer
 *
 * @param array containg attrubtes
 * @param Smarty
 */
function smarty_function_zend_url($params, &$smarty) {
    // Defaults as specified by assemble()
    $urlParams = array();
    $name = null;
    $reset = false;
    $encode = true;

    // Capture the module
    if (isset($params['module'])) {
        $urlParams['module'] = $params['module'];
        unset($params['module']);
    }

    // Capture the controller
    if (isset($params['controller'])) {
        $urlParams['controller'] = $params['controller'];
        unset($params['controller']);
    }

    // Capture the action
    if (isset($params['action'])) {
        $urlParams['action'] = $params['action'];
        unset($params['action']);
    }

    // Capture if a route name is specified
    if (isset($params['zend_url_name'])) {
        print_r ($params['zend_url_name']);
        $name = $params['zend_url_name'];
        unset($params['zend_url_name']);
    }

    // Capture if resetting the route is specified
    if (isset($params['zend_url_reset'])) {
        $reset = $params['zend_url_reset'] == "true"
        ? true
        : false;
        unset($params['zend_url_reset']);
    }

    // Capture if encoding parameters is specified
    if (isset($params['zend_url_encode'])) {
        $encode = $params['zend_url_encode'] == "false"
            ? false
            : true;
        unset($params['zend_url_encode']);
    }

    // Grab rest of the params and add them to urlParams
    foreach ( $params as $key => $val ) {
        $urlParams[ $key ] = $val;
        unset( $params[ $key ] );
    }

    // Assemble the url and pass it back
    return Zend_Controller_Front::getInstance()
        ->getRouter()->assemble(
            $urlParams,
            $name,
            $reset,
            $encode );
}

Example Usage:

If we were on the page http://servername/blog/post/index/231 (post/index.tpl), the following would generate:

{zend_url}

• http://servername/blog/post/index

{zend_url action="edit" id="231"}

• http://servername/blog/post/edit/id/231

{zend_url module="blog2" controller="user" action="edit"
   name="john"}

• http://servername/blog2/user/edit/name/john

There are many articles and enough documentation out there on how to include the Smarty PHP templating engine into your Zend Framework action controllers; however, there was no solution out there describing how to truly incorporate Smarty as the default view renderer, so I decided to figure it out and show you how.no

Partial Implementations

One day, I realized that the phtml view files for my Zend Framework project looked like unmaintainable scary hack (with <?php … ?> tags and shorttags abound), so I wanted to refactor my code to make it a bit more maintainable and readable.

I stumbled upon an article in the Zend Devzone about Integrating Smarty with the Zend Framework. After reading the article and checking Smarty out, I decided that I wanted to use Smarty as my view renderer.

I found several articles “on the webz” on “integrating” the two; however, all of the “integrations” required you to specify the output template file name at the end of each controller action method as you can see below (it was more like an inclusion than an integration)…

I also found on the Zend Framework Documentation page for “50.3.2.2. Template Systems Using Zend_View_Interface” where they actually have an example implementation of a Zend_View_Smarty class which implemented the Zend_View_Interface (which is the closest I could find to my desired Zend + Smary incorporation).

However, at the bottom of the section, they talk about how to use this example Zend_View_Smary, but again I was disappointed to find out I would have to call render() at the end of every controller’s action method! See below…

Since no one described how to fully incorporate, I thought I would do it myself and let you know my results.

The Proper Marriage of Zend Framework and Smarty

Well, why couldn’t I just call render() at the end of each controller’s action?

Call me lazy; call me a stickler. However, I really liked how the Zend_Controller_Action’s default view renderer used the names of controllers and actions to automatically determine what .phtml file to display; I thought it was really nifty.

As you can see above, the default view renderer would assume there was a “views/scripts/” directory inside your application module which would contain directories of .phtml files, where the directory names were the same name as the controller, and the .phtml files under those directories would be the name of each respective controller’s actions.

I wanted to see that same sort of automatic determination of the view script when I used the Smarty templating engine as my view renderer.

This also included not making the extra call to render() at the end of each controller’s action methods.

It ended up being easier than I thought.

Zend_View_Smarty Class

I used the Zend_View_Smarty class from the Zend Documentation page, mentioned earlier, as the view.

It just required three lines of code to be changed for it to work. In the setScriptPath() method, the smarty template_dir is set; well, I also wanted it to set the cache_dir, config_dir and compile_dir properties to be in the same relative directory as the current $path passed in.

class Zend_View_Smarty implements Zend_View_Interface {
    ...

    /**
     * Set the path to the templates
     *
     * @param string $path The directory to set as the path.
     * @return void
     */
    public function setScriptPath($path) {
        if (is_readable($path)) {
            $this->_smarty->template_dir = $path;

            // Convert the smarty paths into view paths
            $this->_smarty->compile_dir = dirname( $path )
                    . '/' . $this->_smarty->compile_dir;
            $this->_smarty->cache_dir = dirname( $path )
                    . '/' . $this->_smarty->cache_dir;
            $this->_smarty->config_dir = dirname( $path )
                    . '/' . $this->_smarty->config_dir;
            return;
        }

        throw new Exception('Invalid path provided');
    }

    ...
}

Time to Use Them…

Now you want actually use the class.

1) Create config ini file…

; Config properties for Smarty templates
[Smarty]
debugging = false
force_compile = true
compile_check = true

;; Location to smarty plugins
plugins_dir = ../library/my_smarty_plugins

;; Caching
caching = false
cache_lifetime = -1

;; Dir Names to be converted to :moduleDir relative paths
cache_dir = cache
config_dir = config
template_dir = templates
compile_dir = templates_c

2) Edit your bootstrap file to contain the following…

$smartyCfg = new Zend_Config_Ini( $configFile, 'Smarty', true );

include_once( 'Smarty/Smarty.class.php');
// Path to zend_view_smary.php
require_once( 'app/view/Zend_View_Smarty.php' );
$view = new Zend_View_Smarty(null, $smartyCfg );

// Use a modified view helper to render view scripts using Smarty
Zend_Loader::loadClass('Zend_Controller_Action_Helper_ViewRenderer');
$helper = new Zend_Controller_Action_Helper_ViewRenderer($view);

// Set the base script path RELATIVE TO THIS FILE
$helper->setViewBasePathSpec(':moduleDir/views/'
                              . $smartyCfg->template_dir);
// Change view suffix from phtml to tpl
$helper->setViewSuffix('tpl');

// Replace the default View Renderer with the Smarty modified one
Zend_Controller_Action_HelperBroker::removeHelper('viewRenderer');
Zend_Controller_Action_HelperBroker::addHelper($helper);

The important parts to take away from the above code are the following:

$helper->setViewBasePathSpec(':moduleDir/views/'
                              . $smartyCfg->template_dir);

If this line is incorrect, you most likely will be having some problems.

Any path spec makes use of the following variables that get replaced at dispatch time:

• :moduleDir
  • Replaced with the modules dir + / + module name
• :module
  • Replaced with dispatched module name
• :controller
  • Replaced with dispatched controller name
• :action
  • Replaced with dispatched action name
• :suffix
  • Replaced with view

In the examples below, you will see that I map to “:moduleDir/views/” + “templates” for my base spec path.

$helper->setViewSuffix('tpl');

This line will switch the default view file suffix from .phtml to .tpl.

An Example…

The directory setup

The IndexController looks like most other simple controllers you have made…

class IndexController extends Zend_Controller_Action {
    public function indexAction(){
        $this->view->name = "Frank Sinatra";

        $this->view->fruits = array(
            "apples",
            "bananas",
            "papayas",
            "peaches"
        );
    }
}

The index action will look for an index.tpl file (via :action.:suffix) in the index/ directory (via :controller) of your views/ directory (via :moduleDir).

{include file="header.tpl"}

<div><b>This is the result of
          IndexController::indexAction()</b></div>

<br/>

<div>Hello {$name}!</div>

<br/>

<div>Here is {$name}'s favorite fruits:
<ul>
  {section name="favFruits" loop="$fruits"}
    <li>{$fruits[favFruits]}</li>
  {/section}
</ul>
</div>

{include file="footer.tpl"}

Combine it with the header.tpl

<html>

<head>
  <title>Test Zend_View_Smarty App</title>
</head>

<body>

Header Content
<hr/>

and the footer.tpl

<hr/>
Footer Content

</body>
</html>

The final output works just as normal.

Download The Example…

If you can think of any other features and or suggestions, let me know and I’ll add it into the view/controller-action classes. Thanks!

ZendSmarty_v4.zip