One of the nicest parts about working with the Smarty Template Engine is it’s extensibility. The developers of Smarty had the foresight to recognize that their needs didn’t necessarily match the needs of all developers so they built into Smarty a plugin/module system to allow developers to extend Smarty to meet their needs.

There are plenty of options available when it comes to creating a Smarty plugin though I’ve only had to work with first 4 of the below 7 plugin types.

The available plugin types are template, modifiers, block functions, compiler functions, prefilters, postfilters, outputfilters, resources and inserts. Be sure to check out the Naming Conventions before attempting any of the techniques layed out here.

Naming Conventions

It’s important to note the naming convention for Smary Plugins. There are two conventions to pay attention to: files and functions.

An example of naming a file is:

type.name.php

where “type” is the plugin type and name is the name of the function in the file. Don’t worry about this too much though because Smarty will let you know when you mess up on the naming conventions. A couple examples of names for plugins would be:

function.plugin1.php
modifier.plugin2.php
block.plugin3.php
etc…

The convention for the functions is similar except all Smarty plugin functions must begin with “smarty” followed by the type then the name.

<?php
smarty_modifier_plugin_name(){
}
?>

Writing a Smarty Modifier Plugin

There’s a cool tutorial on Morning Caffeine that goes into a little detail on how to create a smarty modifier plugin.

Modifiers are basically php functions (custom or predefined) which work with variables, custom functions and strings. That means, you can actually call php functions as modifiers. Applying a modifier is very easy, all you need to specify the value followed by pipe and the modifier name.

Here’s an example Smarty Modifier Plugin:

<?php
/**
 * Smarty plugin
 * @package Smarty
 * @subpackage plugins
 */
 
function smarty_modifier_test_plugin($str)
{
	if(!$str){
		$str = 'N/A';
	}
	return $str;
}

In your Smarty template you just use it like so:

{'Hello Here!'|test_plugin}

Writing a Smarty Template Plugin

Writing a Smarty Template Plugin requires a little more planning than a Smarty Modifier Plugin. The Smarty Manual explains this pretty well:

The output (return value) of the function will be substituted in place of the function tag in the template (fetch() function, for example). Alternatively, the function can simply perform some other task without any output (assign() function).

So a Smarty Template Plugin essentially requires no variables or hooks from the Smarty object to work (unlike Smarty Modifier Plugins).

Here’s an example of how to create one:

function smarty_function_fun_with_string($params, &$smarty)
{
	if (empty($params)) {
		$smarty->_trigger_fatal_error(" param 'bad_word' cannot be empty ");
		return;
	}
	return str_repeat($params.$params,$params);
}

{fun_with_string bad_word='Fuck You!' delim='<br>' repeat='5'}

Smarty Block Functions

Block functions are functions of the form: {func} .. {/func}. In other words, they enclose a template block and operate on the contents of this block.

Smarty Block Functions are a lot more complicated than any of the other plugin types because of how they are parsed. Block functions are called twice to account for both the opening and closing tags so your function needs to take that into account or you’ll see some unexpected output 😊

There’s a great example of one from the Smarty manual so I’m just going to use that:

<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File:     block.translate.php
* Type:     block
* Name:     translate
* Purpose:  translate a block of text
* -------------------------------------------------------------
*/
function smarty_block_translate($params, $content, &$smarty, &$repeat)
{
    if (isset($content)) {
        $lang = $params;
        // do some intelligent translation thing here with $content
        return $translation;
    }
}
?>

And you would call the plugin from the template like so:

{translate lang="br"}
Hello, world!
{/translate}

Smarty Compiler Functions

As the name suggests compiler functions are Smarty Plugins that get executed at compile time of the template. They’re good for executing time sensitive data into a template.

<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File:     compiler.tplheader.php
* Type:     compiler
* Name:     tplheader
* Purpose:  Output header containing the source file name and
*           the time it was compiled.
* -------------------------------------------------------------
*/
function smarty_compiler_tplheader($tag_arg, &$smarty)
{
    return "\necho '" . $smarty->_current_file . " compiled at " . date('Y-m-d H:M'). "';";
}
?>

And it get’s executed like:

{tplheader}

Smarty Prefilter Plugins

The Smarty Manual says it best:

Prefilters are used to process the source of the template immediately before compilation. The first parameter to the prefilter function is the template source, possibly modified by some other prefilters. The plugin is supposed to return the modified source. Note that this source is not saved anywhere, it is only used for compilation.

Prefilter Plugins don’t have any template variable to replace so they have to be initialized explicitly.

<?php
$smarty->register_prefilter('pre01');
?>

It’s important to note that the prefilter plugin has to be declared before registering the filter or you’ll get Smarty errors all over the place.

Smarty Postfilter Plugins

On the other side of the spectrum from Prefilter plugins are Smarty Postfilter Plugins. Postfilter plugins are exactly identical in every way to Prefilter plugins except for when they are executed. Postfilters are, as the name suggests, executed at the end of the template compilation.

Smarty Output Plugins

Output filter plugins operate on a template’s output, after the template is loaded and executed, but before the output is displayed.

<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File:     outputfilter.protect_email.php
* Type:     outputfilter
* Name:     protect_email
* Purpose:  Converts @ sign in email addresses to %40 as
*           a simple protection against spambots
* -------------------------------------------------------------
*/
function smarty_outputfilter_protect_email($output, &$smarty)
{
     return preg_replace('!(\S+)@(+\.({2,3}|{1,3}))!',
                         '$1%40$2', $output);
}
?>

Smarty Resource Plugins

Resource plugins are useful for supplying Smarty with access to external resources like databases, shared memory, LDAP and sockets.

According to the Smarty manual:

There are a total of 4 functions that need to be registered for each type of resource. Every function will receive the requested resource as the first parameter and the Smarty object as the last parameter. The rest of parameters depend on the function.

bool smarty_resource_name_source (string $rsrc_name, string &$source, object &$smarty)

bool smarty_resource_name_timestamp (string $rsrc_name, int &$timestamp, object &$smarty)

bool smarty_resource_name_secure (string $rsrc_name, object &$smarty)

bool smarty_resource_name_trusted (string $rsrc_name, object &$smarty)

The first function is supposed to retrieve the resource. Its second parameter is a variable passed by reference where the result should be stored. The function is supposed to return true if it was able to successfully retrieve the resource and false otherwise.

The second function is supposed to retrieve the last modification time of the requested resource (as a UNIX timestamp). The second parameter is a variable passed by reference where the timestamp should be stored. The function is supposed to return true if the timestamp could be succesfully determined, and false otherwise.

The third function is supposed to return true or false, depending on whether the requested resource is secure or not. This function is used only for template resources but should still be defined.

The fourth function is supposed to return true or false, depending on whether the requested resource is trusted or not. This function is used for only for PHP script components requested by include_php tag or insert tag with src attribute. However, it should still be defined even for template resources.

With the code looking like so:

<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File:     resource.db.php
* Type:     resource
* Name:     db
* Purpose:  Fetches templates from a database
* -------------------------------------------------------------
*/
function smarty_resource_db_source($tpl_name, &$tpl_source, &$smarty)
{
    // do database call here to fetch your template,
    // populating $tpl_source
    $sql = new SQL;
    $sql->query("select tpl_source
                   from my_table
                  where tpl_name='$tpl_name'");
    if ($sql->num_rows) {
        $tpl_source = $sql->record;
        return true;
    } else {
        return false;
    }
} 
 
function smarty_resource_db_timestamp($tpl_name, &$tpl_timestamp, &$smarty)
{
    // do database call here to populate $tpl_timestamp.
    $sql = new SQL;
    $sql->query("select tpl_timestamp
                   from my_table
                  where tpl_name='$tpl_name'");
    if ($sql->num_rows) {
        $tpl_timestamp = $sql->record;
        return true;
    } else {
        return false;
    }
} 
 
function smarty_resource_db_secure($tpl_name, &$smarty)
{
    // assume all templates are secure
    return true;
} 
 
function smarty_resource_db_trusted($tpl_name, &$smarty)
{
    // not used for templates
}
?>

Smarty Insert Plugins

Lastly, we have Smarty Insert Plugins. Insert plugins are only good for use in the Smarty Insert tag. For example:

{insert name="time" format="%A"}

With the php code:

<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File:     insert.time.php
* Type:     time
* Name:     time
* Purpose:  Inserts current date/time according to format
* -------------------------------------------------------------
*/
function smarty_insert_time($params, &$smarty)
{
    if (empty($params)) {
        $smarty->trigger_error("insert time: missing 'format' parameter");
        return;
    } 
 
    $datetime = strftime($params);
    return $datetime;
}
?>