Smarty 3.1 Notes ================ Smarty 3.1 is a departure from 2.0 compatibility. Most notably, all backward compatibility has been moved to a separate class file named SmartyBC.class.php. If you require compatibility with 2.0, you will need to use this class. Some differences from 3.0 are also present. 3.1 begins the journey of requiring setters/getters for property access. So far this is only implemented on the five directory properties: template_dir, plugins_dir, configs_dir, compile_dir and cache_dir. These properties are now protected, it is required to use the setters/getters instead. That said, direct property access will still work, however slightly slower since they will now fall through __set() and __get() and in turn passed through the setter/getter methods. 3.2 will exhibit a full list of setter/getter methods for all (currently) public properties, so code-completion in your IDE will work as expected. There is absolutely no PHP allowed in templates any more. All deprecated features of Smarty 2.0 are gone. Again, use the SmartyBC class if you need any backward compatibility. Internal Changes Full UTF-8 Compatibility The plugins shipped with Smarty 3.1 have been rewritten to fully support UTF-8 strings if Multibyte String is available. Without MBString UTF-8 cannot be handled properly. For those rare cases where templates themselves have to juggle encodings, the new modifiers to_charset and from_charset may come in handy. Plugin API and Performance All Plugins (modifiers, functions, blocks, resources, default_template_handlers, etc) are now receiving the Smarty_Internal_Template instance, where they were supplied with the Smarty instance in Smarty 3.0. *. As The Smarty_Internal_Template mimics the behavior of Smarty, this API simplification should not require any changes to custom plugins. The plugins shipped with Smarty 3.1 have been rewritten for better performance. Most notably {html_select_date} and {html_select_time} have been improved vastly. Performance aside, plugins have also been reviewed and generalized in their API. {html_select_date} and {html_select_time} now share almost all available options. The escape modifier now knows the $double_encode option, which will prevent entities from being encoded again. The capitalize modifier now know the $lc_rest option, which makes sure all letters following a captial letter are lower-cased. The count_sentences modifier now accepts (.?!) as legitimate endings of a sentence - previously only (.) was accepted The new unescape modifier is there to reverse the effects of the escape modifier. This applies to the escape formats html, htmlall and entity. default_template_handler_func The invocation of $smarty->$default_template_handler_func had to be altered. Instead of a Smarty_Internal_Template, the fifth argument is now provided with the Smarty instance. New footprint: /** * Default Template Handler * * called when Smarty's file: resource is unable to load a requested file * * @param string $type resource type (e.g. "file", "string", "eval", "resource") * @param string $name resource name (e.g. "foo/bar.tpl") * @param string &$content template's content * @param integer &$modified template's modification time * @param Smarty $smarty Smarty instance * @return string|boolean path to file or boolean true if $content and $modified * have been filled, boolean false if no default template * could be loaded */ function default_template_handler_func($type, $name, &$content, &$modified, Smarty $smarty) { if (false) { // return corrected filepath return "/tmp/some/foobar.tpl"; } elseif (false) { // return a template directly $content = "the template source"; $modified = time(); return true; } else { // tell smarty that we failed return false; } } Stuff done to the compiler Many performance improvements have happened internally. One notable improvement is that all compiled templates are now handled as PHP functions. This speeds up repeated templates tremendously, as each one calls an (in-memory) PHP function instead of performing another file include/scan. New Features Template syntax {block}..{/block} The {block} tag has a new hide option flag. It does suppress the block content if no corresponding child block exists. EXAMPLE: parent.tpl {block name=body hide} child content "{$smarty.block.child}" was inserted {block} In the above example the whole block will be suppressed if no child block "body" is existing. {setfilter}..{/setfilter} The new {setfilter} block tag allows the definition of filters which run on variable output. SYNTAX: {setfilter filter1|filter2|filter3....} Smarty3 will lookup up matching filters in the following search order: 1. varibale filter plugin in plugins_dir. 2. a valid modifier. A modifier specification will also accept additional parameter like filter2:'foo' 3. a PHP function {/setfilter} will turn previous filter setting off again. {setfilter} tags can be nested. EXAMPLE: {setfilter filter1} {$foo} {setfilter filter2} {$bar} {/setfilter} {$buh} {/setfilter} {$blar} In the above example filter1 will run on the output of $foo, filter2 on $bar, filter1 again on $buh and no filter on $blar. NOTES: - {$foo nofilter} will suppress the filters - These filters will run in addition to filters defined by registerFilter('variable',...), autoLoadFilter('variable',...) and defined default modifier. - {setfilter} will effect only the current template, not included subtemplates. Resource API Smarty 3.1 features a new approach to resource management. The Smarty_Resource API allows simple, yet powerful integration of custom resources for templates and configuration files. It offers simple functions for loading data from a custom resource (e.g. database) as well as define new template types adhering to the special non-compiling (e,g, plain php) and non-compile-caching (e.g. eval: resource type) resources. See demo/plugins/resource.mysql.php for an example custom database resource. Note that old-fashioned registration of callbacks for resource management has been deprecated but is still possible with SmartyBC. CacheResource API In line with the Resource API, the CacheResource API offers a more comfortable handling of output-cache data. With the Smarty_CacheResource_Custom accessing databases is made simple. With the introduction of Smarty_CacheResource_KeyValueStore the implementation of resources like memcache or APC became a no-brainer; simple hash-based storage systems are now supporting hierarchical output-caches. See demo/plugins/cacheresource.mysql.php for an example custom database CacheResource. See demo/plugins/cacheresource.memcache.php for an example custom memcache CacheResource using the KeyValueStore helper. Note that old-fashioned registration of $cache_handler is not possible anymore. As the functionality had not been ported to Smarty 3.0.x properly, it has been dropped from 3.1 completely. Locking facilities have been implemented to avoid concurrent cache generation. Enable cache locking by setting $smarty->cache_locking = true; Relative Paths in Templates (File-Resource) As of Smarty 3.1 {include file="../foo.tpl"} and {include file="./foo.tpl"} will resolve relative to the template they're in. Relative paths are available with {include file="..."} and {extends file="..."}. As $smarty->fetch('../foo.tpl') and $smarty->fetch('./foo.tpl') cannot be relative to a template, an exception is thrown. Addressing a specific $template_dir Smarty 3.1 introduces the $template_dir index notation. $smarty->fetch('[foo]bar.tpl') and {include file="[foo]bar.tpl"} require the template bar.tpl to be loaded from $template_dir['foo']; Smarty::setTemplateDir() and Smarty::addTemplateDir() offer ways to define indexes along with the actual directories. Mixing Resources in extends-Resource Taking the php extends: template resource one step further, it is now possible to mix resources within an extends: call like $smarty->fetch("extends:file:foo.tpl|db:bar.tpl"); To make eval: and string: resources available to the inheritance chain, eval:base64:TPL_STRING and eval:urlencode:TPL_STRING have been introduced. Supplying the base64 or urlencode flags will trigger decoding the TPL_STRING in with either base64_decode() or urldecode(). extends-Resource in template inheritance Template based inheritance may now inherit from php's extends: resource like {extends file="extends:foo.tpl|db:bar.tpl"}. New Smarty property escape_html $smarty->escape_html = true will autoescape all template variable output by calling htmlspecialchars({$output}, ENT_QUOTES, SMARTY_RESOURCE_CHAR_SET). NOTE: This is a compile time option. If you change the setting you must make sure that the templates get recompiled. New option at Smarty property compile_check The automatic recompilation of modified templates can now be controlled by the following settings: $smarty->compile_check = COMPILECHECK_OFF (false) - template files will not be checked $smarty->compile_check = COMPILECHECK_ON (true) - template files will always be checked $smarty->compile_check = COMPILECHECK_CACHEMISS - template files will be checked if caching is enabled and there is no existing cache file or it has expired Automatic recompilation on Smarty version change Templates will now be automatically recompiled on Smarty version changes to avoide incompatibillities in the compiled code. Compiled template checked against the current setting of the SMARTY_VERSION constant. default_config_handler_func() Analogous to the default_template_handler_func() default_config_handler_func() has been introduced. default_plugin_handler_func() An optional default_plugin_handler_func() can be defined which gets called by the compiler on tags which can't be resolved internally or by plugins. The default_plugin_handler() can map tags to plugins on the fly. New getters/setters The following setters/getters will be part of the official documentation, and will be strongly recommended. Direct property access will still work for the foreseeable future... it will be transparently routed through the setters/getters, and consequently a bit slower. array|string getTemplateDir( [string $index] ) replaces $smarty->template_dir; and $smarty->template_dir[$index]; Smarty setTemplateDir( array|string $path ) replaces $smarty->template_dir = "foo"; and $smarty->template_dir = array("foo", "bar"); Smarty addTemplateDir( array|string $path, [string $index]) replaces $smarty->template_dir[] = "bar"; and $smarty->template_dir[$index] = "bar"; array|string getConfigDir( [string $index] ) replaces $smarty->config_dir; and $smarty->config_dir[$index]; Smarty setConfigDir( array|string $path ) replaces $smarty->config_dir = "foo"; and $smarty->config_dir = array("foo", "bar"); Smarty addConfigDir( array|string $path, [string $index]) replaces $smarty->config_dir[] = "bar"; and $smarty->config_dir[$index] = "bar"; array getPluginsDir() replaces $smarty->plugins_dir; Smarty setPluginsDir( array|string $path ) replaces $smarty->plugins_dir = "foo"; Smarty addPluginsDir( array|string $path ) replaces $smarty->plugins_dir[] = "bar"; string getCompileDir() replaces $smarty->compile_dir; Smarty setCompileDir( string $path ) replaces $smarty->compile_dir = "foo"; string getCacheDir() replaces $smarty->cache_dir; Smarty setCacheDir( string $path ) replaces $smarty->cache_dir;