diff options
Diffstat (limited to 'vendor/smarty/smarty/docs/programmers/advanced-features')
9 files changed, 588 insertions, 0 deletions
diff --git a/vendor/smarty/smarty/docs/programmers/advanced-features/advanced-features-objects.md b/vendor/smarty/smarty/docs/programmers/advanced-features/advanced-features-objects.md new file mode 100644 index 000000000..6b4870b51 --- /dev/null +++ b/vendor/smarty/smarty/docs/programmers/advanced-features/advanced-features-objects.md @@ -0,0 +1,99 @@ +Objects {#advanced.features.objects} +======= + +Smarty allows access to PHP [objects](&url.php-manual;object) through +the templates. + +> **Note** +> +> When you assign/register objects to templates, be sure that all +> properties and methods accessed from the template are for presentation +> purposes only. It is very easy to inject application logic through +> objects, and this leads to poor designs that are difficult to manage. +> See the Best Practices section of the Smarty website. + +There are two ways to access them. + +- One way is to [register objects](#api.register.object) to the + template, then use access them via syntax similar to [custom + functions](#language.custom.functions). + +- The other way is to [`assign()`](#api.assign) objects to the + templates and access them much like any other assigned variable. + +The first method has a much nicer template syntax. It is also more +secure, as a registered object can be restricted to certain methods or +properties. However, **a registered object cannot be looped over or +assigned in arrays of objects**, etc. The method you choose will be +determined by your needs, but use the first method whenever possible to +keep template syntax to a minimum. + +If security is enabled, no private methods or functions can be accessed +(beginningwith \'\_\'). If a method and property of the same name exist, +the method will be used. + +You can restrict the methods and properties that can be accessed by +listing them in an array as the third registration parameter. + +By default, parameters passed to objects through the templates are +passed the same way [custom functions](#language.custom.functions) get +them. An associative array is passed as the first parameter, and the +smarty object as the second. If you want the parameters passed one at a +time for each argument like traditional object parameter passing, set +the fourth registration parameter to FALSE. + +The optional fifth parameter has only effect with `format` being TRUE +and contains a list of methods that should be treated as blocks. That +means these methods have a closing tag in the template +(`{foobar->meth2}...{/foobar->meth2}`) and the parameters to the methods +have the same synopsis as the parameters for +[`block-function-plugins`](#plugins.block.functions): They get the four +parameters `$params`, `$content`, `$smarty` and `&$repeat` and they also +behave like block-function-plugins. + + + <?php + // the object + + class My_Object { + function meth1($params, $smarty_obj) { + return 'this is my meth1'; + } + } + + $myobj = new My_Object; + + // registering the object (will be by reference) + $smarty->registerObject('foobar',$myobj); + + // if we want to restrict access to certain methods or properties, list them + $smarty->registerObject('foobar',$myobj,array('meth1','meth2','prop1')); + + // if you want to use the traditional object parameter format, pass a boolean of false + $smarty->registerObject('foobar',$myobj,null,false); + + // We can also assign objects. assign_by_ref when possible. + $smarty->assign_by_ref('myobj', $myobj); + + $smarty->display('index.tpl'); + ?> + + + +And here\'s how to access your objects in `index.tpl`: + + + {* access our registered object *} + {foobar->meth1 p1='foo' p2=$bar} + + {* you can also assign the output *} + {foobar->meth1 p1='foo' p2=$bar assign='output'} + the output was {$output} + + {* access our assigned object *} + {$myobj->meth1('foo',$bar)} + + + +See also [`registerObject()`](#api.register.object) and +[`assign()`](#api.assign). diff --git a/vendor/smarty/smarty/docs/programmers/advanced-features/advanced-features-outputfilters.md b/vendor/smarty/smarty/docs/programmers/advanced-features/advanced-features-outputfilters.md new file mode 100644 index 000000000..393d7da23 --- /dev/null +++ b/vendor/smarty/smarty/docs/programmers/advanced-features/advanced-features-outputfilters.md @@ -0,0 +1,43 @@ +Output Filters {#advanced.features.outputfilters} +============== + +When the template is invoked via [`display()`](#api.display) or +[`fetch()`](#api.fetch), its output can be sent through one or more +output filters. This differs from +[`postfilters`](#advanced.features.postfilters) because postfilters +operate on compiled templates before they are saved to the disk, whereas +output filters operate on the template output when it is executed. + +Output filters can be either [registered](#api.register.filter) or +loaded from the [plugins directory](#variable.plugins.dir) by using the +[`loadFilter()`](#api.load.filter) method or by setting the +[`$autoload_filters`](#variable.autoload.filters) variable. Smarty will +pass the template output as the first argument, and expect the function +to return the result of the processing. + + + <?php + // put this in your application + function protect_email($tpl_output, Smarty_Internal_Template $template) + { + $tpl_output = + preg_replace('!(\S+)@([a-zA-Z0-9\.\-]+\.([a-zA-Z]{2,3}|[0-9]{1,3}))!', + '$1%40$2', $tpl_output); + return $tpl_output; + } + + // register the outputfilter + $smarty->registerFilter("output","protect_email"); + $smarty->display("index.tpl'); + + // now any occurrence of an email address in the template output will have + // a simple protection against spambots + ?> + + + +See also [`registerFilter()`](#api.register.filter), +[`loadFilter()`](#api.load.filter), +[`$autoload_filters`](#variable.autoload.filters), +[postfilters](#advanced.features.postfilters) and +[`$plugins_dir`](#variable.plugins.dir). diff --git a/vendor/smarty/smarty/docs/programmers/advanced-features/advanced-features-postfilters.md b/vendor/smarty/smarty/docs/programmers/advanced-features/advanced-features-postfilters.md new file mode 100644 index 000000000..d3bad546a --- /dev/null +++ b/vendor/smarty/smarty/docs/programmers/advanced-features/advanced-features-postfilters.md @@ -0,0 +1,40 @@ +Postfilters {#advanced.features.postfilters} +=========== + +Template postfilters are PHP functions that your templates are ran +through *after they are compiled*. Postfilters can be either +[registered](#api.register.filter) or loaded from the [plugins +directory](#variable.plugins.dir) by using the +[`loadFilter()`](#api.load.filter) function or by setting the +[`$autoload_filters`](#variable.autoload.filters) variable. Smarty will +pass the compiled template code as the first argument, and expect the +function to return the result of the processing. + + + <?php + // put this in your application + function add_header_comment($tpl_source, Smarty_Internal_Template $template) + { + return "<?php echo \"<!-- Created by Smarty! -->\n\"; ?>\n".$tpl_source; + } + + // register the postfilter + $smarty->registerFilter('post','add_header_comment'); + $smarty->display('index.tpl'); + ?> + + + +The postfilter above will make the compiled Smarty template `index.tpl` +look like: + + + <!-- Created by Smarty! --> + {* rest of template content... *} + + + +See also [`registerFilter()`](#api.register.filter), +[prefilters](#advanced.features.prefilters), +[outputfilters](#advanced.features.outputfilters), and +[`loadFilter()`](#api.load.filter). diff --git a/vendor/smarty/smarty/docs/programmers/advanced-features/advanced-features-prefilters.md b/vendor/smarty/smarty/docs/programmers/advanced-features/advanced-features-prefilters.md new file mode 100644 index 000000000..76229e633 --- /dev/null +++ b/vendor/smarty/smarty/docs/programmers/advanced-features/advanced-features-prefilters.md @@ -0,0 +1,36 @@ +Prefilters {#advanced.features.prefilters} +========== + +Template prefilters are PHP functions that your templates are ran +through *before they are compiled*. This is good for preprocessing your +templates to remove unwanted comments, keeping an eye on what people are +putting in their templates, etc. + +Prefilters can be either [registered](#api.register.filter) or loaded +from the [plugins directory](#variable.plugins.dir) by using +[`loadFilter()`](#api.load.filter) function or by setting the +[`$autoload_filters`](#variable.autoload.filters) variable. + +Smarty will pass the template source code as the first argument, and +expect the function to return the resulting template source code. + +This will remove all the html comments in the template source. + + + <?php + // put this in your application + function remove_dw_comments($tpl_source, Smarty_Internal_Template $template) + { + return preg_replace("/<!--#.*-->/U",'',$tpl_source); + } + + // register the prefilter + $smarty->registerFilter('pre','remove_dw_comments'); + $smarty->display('index.tpl'); + ?> + + + +See also [`registerFilter()`](#api.register.filter), +[postfilters](#advanced.features.postfilters) and +[`loadFilter()`](#api.load.filter). diff --git a/vendor/smarty/smarty/docs/programmers/advanced-features/advanced-features-security.md b/vendor/smarty/smarty/docs/programmers/advanced-features/advanced-features-security.md new file mode 100644 index 000000000..98817a433 --- /dev/null +++ b/vendor/smarty/smarty/docs/programmers/advanced-features/advanced-features-security.md @@ -0,0 +1,168 @@ +Security {#advanced.features.security} +======== + +Security is good for situations when you have untrusted parties editing +the templates eg via ftp, and you want to reduce the risk of system +security compromises through the template language. + +The settings of the security policy are defined by properties of an +instance of the Smarty\_Security class. These are the possible settings: + +- `$php_handling` determines how Smarty to handle PHP code embedded in + templates. Possible values are: + + - Smarty::PHP\_PASSTHRU -\> echo PHP tags as they are + + - Smarty::PHP\_QUOTE -\> escape tags as entities + + - Smarty::PHP\_REMOVE -\> remove php tags + + - Smarty::PHP\_ALLOW -\> execute php tags + + The default value is Smarty::PHP\_PASSTHRU. + + If security is enabled the [`$php_handling`](#variable.php.handling) + setting of the Smarty object is not checked for security. + +- `$secure_dir` is an array of template directories that are + considered secure. [`$template_dir`](#variable.template.dir) + concidered secure implicitly. The default is an empty array. + +- `$trusted_dir` is an array of all directories that are considered + trusted. Trusted directories are where you keep php scripts that are + executed directly from the templates with + [`{include_php}`](#language.function.include.php). The default is an + empty array. + +- `$trusted_uri` is an array of regular expressions matching URIs that + are considered trusted. This security directive used by + [`{fetch}`](#language.function.fetch) and + [`{html_image}`](#language.function.html.image). URIs passed to + these functions are reduced to `{$PROTOCOL}://{$HOSTNAME}` to allow + simple regular expressions (without having to deal with edge cases + like authentication-tokens). + + The expression `'#https?://.*smarty.net$#i'` would allow accessing + the follwing URIs: + + - `http://smarty.net/foo` + + - `http://smarty.net/foo` + + - `http://www.smarty.net/foo` + + - `http://smarty.net/foo` + + - `https://foo.bar.www.smarty.net/foo/bla?blubb=1` + + but deny access to these URIs: + + - `http://smarty.com/foo` (not matching top-level domain \"com\") + + - `ftp://www.smarty.net/foo` (not matching protocol \"ftp\") + + - `http://www.smarty.net.otherdomain.com/foo` (not matching end of + domain \"smarty.net\") + +- `$static_classes` is an array of classes that are considered + trusted. The default is an empty array which allows access to all + static classes. To disable access to all static classes set + \$static\_classes = null. + +- `$php_functions` is an array of PHP functions that are considered + trusted and can be used from within template. To disable access to + all PHP functions set \$php\_functions = null. An empty array ( + \$php\_functions = array() ) will allow all PHP functions. The + default is array(\'isset\', \'empty\', \'count\', \'sizeof\', + \'in\_array\', \'is\_array\',\'time\',\'nl2br\'). + +- `$php_modifiers` is an array of PHP functions that are considered + trusted and can be used from within template as modifier. To disable + access to all PHP modifier set \$php\_modifier = null. An empty + array ( \$php\_modifier = array() ) will allow all PHP functions. + The default is array(\'escape\',\'count\'). + +- `$streams` is an array of streams that are considered trusted and + can be used from within template. To disable access to all streams + set \$streams = null. An empty array ( \$streams = array() ) will + allow all streams. The default is array(\'file\'). + +- `$allowed_modifiers` is an array of (registered / autoloaded) + modifiers that should be accessible to the template. If this array + is non-empty, only the herein listed modifiers may be used. This is + a whitelist. + +- `$disabled_modifiers` is an array of (registered / autoloaded) + modifiers that may not be accessible to the template. + +- `$allowed_tags` is a boolean flag which controls if constants can + function-, block and filter plugins that should be accessible to the + template. If this array is non-empty, only the herein listed + modifiers may be used. This is a whitelist. + +- `$disabled_tags` is an array of (registered / autoloaded) function-, + block and filter plugins that may not be accessible to the template. + +- `$allow_constants` is a boolean flag which controls if constants can + be accessed by the template. The default is \"true\". + +- `$allow_super_globals` is a boolean flag which controls if the PHP + super globals can be accessed by the template. The default is + \"true\". + +- `$allow_php_tag` is a boolean flag which controls if {php} and + {include\_php} tags can be used by the template. The default is + \"false\". + +If security is enabled, no private methods, functions or properties of +static classes or assigned objects can be accessed (beginningwith +\'\_\') by the template. + +To customize the security policy settings you can extend the +Smarty\_Security class or create an instance of it. + + + <?php + require 'Smarty.class.php'; + + class My_Security_Policy extends Smarty_Security { + // disable all PHP functions + public $php_functions = null; + // remove PHP tags + public $php_handling = Smarty::PHP_REMOVE; + // allow everthing as modifier + public $php_modifiers = array(); + } + $smarty = new Smarty(); + // enable security + $smarty->enableSecurity('My_Security_Policy'); + ?> + + + <?php + require 'Smarty.class.php'; + $smarty = new Smarty(); + $my_security_policy = new Smarty_Security($smarty); + // disable all PHP functions + $my_security_policy->php_functions = null; + // remove PHP tags + $my_security_policy->php_handling = Smarty::PHP_REMOVE; + // allow everthing as modifier + $my_security_policy->php_modifiers = array(); + // enable security + $smarty->enableSecurity($my_security_policy); + ?> + + + <?php + require 'Smarty.class.php'; + $smarty = new Smarty(); + // enable default security + $smarty->enableSecurity(); + ?> + +> **Note** +> +> Most security policy settings are only checked when the template gets +> compiled. For that reasion you should delete all cached and compiled +> template files when you change your security settings. diff --git a/vendor/smarty/smarty/docs/programmers/advanced-features/advanced-features-static-classes.md b/vendor/smarty/smarty/docs/programmers/advanced-features/advanced-features-static-classes.md new file mode 100644 index 000000000..8ef79113c --- /dev/null +++ b/vendor/smarty/smarty/docs/programmers/advanced-features/advanced-features-static-classes.md @@ -0,0 +1,27 @@ +Static Classes {#advanced.features.static.classes} +============== + +You can directly access static classes. The syntax is the same as in +PHP. + +> **Note** +> +> Direct access to PHP classes is not recommended. This ties the +> underlying application code structure directly to the presentation, +> and also complicates template syntax. It is recommended to register +> plugins which insulate templates from PHP classes/objects. Use at your +> own discretion. See the Best Practices section of the Smarty website. + + + {assign var=foo value=myclass::BAR} <--- class constant BAR + + {assign var=foo value=myclass::method()} <--- method result + + {assign var=foo value=myclass::method1()->method2} <--- method chaining + + {assign var=foo value=myclass::$bar} <--- property bar of class myclass + + {assign var=foo value=$bar::method} <--- using Smarty variable bar as class name + + + diff --git a/vendor/smarty/smarty/docs/programmers/advanced-features/advanced-features-streams.md b/vendor/smarty/smarty/docs/programmers/advanced-features/advanced-features-streams.md new file mode 100644 index 000000000..d6f7a0de5 --- /dev/null +++ b/vendor/smarty/smarty/docs/programmers/advanced-features/advanced-features-streams.md @@ -0,0 +1,15 @@ +Streams {#advanced.features.streams} +======= + +You can also use streams to call variables. *{\$foo:bar}* will use the +*foo://bar* stream to get the template variable. + +Using a PHP stream for a template variable resource from within a +template. + + + {$foo:bar} + + + +See also [`Template Resources`](#resources) diff --git a/vendor/smarty/smarty/docs/programmers/advanced-features/advanced-features-template-inheritance.md b/vendor/smarty/smarty/docs/programmers/advanced-features/advanced-features-template-inheritance.md new file mode 100644 index 000000000..25295c38d --- /dev/null +++ b/vendor/smarty/smarty/docs/programmers/advanced-features/advanced-features-template-inheritance.md @@ -0,0 +1,128 @@ +Template Inheritance {#advanced.features.template.inheritance} +==================== + +Inheritance brings the concept of Object Oriented Programming to +templates, allowing you to define one (or more) base templates that can +be extended by child templates. Extending means that the child template +can override all or some of the parent named block areas. + +- The inheritance tree can be as deep as you want, meaning you can + extend a file that extends another one that extends another one and + so on. + +- The child templates can not define any content besides what\'s + inside [`{block}`](#language.function.block) tags they override. + Anything outside of [`{block}`](#language.function.block) tags will + be removed. + +- The content of [`{block}`](#language.function.block) tags from child + and parent templates can be merged by the `append` or `prepend` + [`{block}`](#language.function.block) tag option flags and + `{$smarty.block.parent}` or `{$smarty.block.child}` placeholders. + +- Template inheritance is a compile time process which creates a + single compiled template file. Compared to corresponding solutions + based on subtemplates included with the + [`{include}`](#language.function.include) tag it does have much + better performance when rendering. + +- The child template extends its parent defined with the + [`{extends}`](#language.function.extends) tag, which must be the + first line in the child template. Instead of using the + [`{extends}`](#language.function.extends) tags in the template files + you can define the whole template inheritance tree in the PHP script + when you are calling [`fetch()`](#api.fetch) or + [`display()`](#api.display) with the `extends:` template resource + type. The later provides even more flexibillity. + +> **Note** +> +> When `$compile_check` is enabled, all files in the inheritance tree +> are checked for modifications upon each invocation. You may want to +> disable `$compile_check` on production servers for this reason. + +> **Note** +> +> If you have a subtemplate which is included with +> [`{include}`](#language.function.include) and it contains +> [`{block}`](#language.function.block) areas it works only if the +> [`{include}`](#language.function.include) itself is called from within +> a surrounding [`{block}`](#language.function.block). In the final +> parent template you may need a dummy +> [`{block}`](#language.function.block) for it. + +layout.tpl (parent) + + + <html> + <head> + <title>{block name=title}Default Page Title{/block}</title> + {block name=head}{/block} + </head> + <body> + {block name=body}{/block} + </body> + </html> + + + +myproject.tpl (child) + + + {extends file='layout.tpl'} + {block name=head} + <link href="/css/mypage.css" rel="stylesheet" type="text/css"/> + <script src="/js/mypage.js"></script> + {/block} + + + + +mypage.tpl (grandchild) + + + {extends file='myproject.tpl'} + {block name=title}My Page Title{/block} + {block name=head} + <link href="/css/mypage.css" rel="stylesheet" type="text/css"/> + <script src="/js/mypage.js"></script> + {/block} + {block name=body}My HTML Page Body goes here{/block} + + + +To render the above use + + + $smarty->display('mypage.tpl'); + +The resulting output is + + + <html> + <head> + <title>My Page Title</title> + <link href="/css/mypage.css" rel="stylesheet" type="text/css"/> + <script src="/js/mypage.js"></script> + </head> + <body> + My HTML Page Body goes here + </body> + </html> + +Instead of using [`{extends}`](#language.function.extends) tags in the +template files you can define the inheritance tree in your PHP script by +using the [`extends:` resource](#resources.extends) type. + +The code below will return same result as the example above. + + + <?php + $smarty->display('extends:layout.tpl|myproject.tpl|mypage.tpl'); + ?> + + + +See also [`{block}`](#language.function.block), +[`{extends}`](#language.function.extends) and [`extends:` +resource](#resources.extends) diff --git a/vendor/smarty/smarty/docs/programmers/advanced-features/advanced-features-template-settings.md b/vendor/smarty/smarty/docs/programmers/advanced-features/advanced-features-template-settings.md new file mode 100644 index 000000000..df1f86a8c --- /dev/null +++ b/vendor/smarty/smarty/docs/programmers/advanced-features/advanced-features-template-settings.md @@ -0,0 +1,32 @@ +Changing settings by template {#advanced.features.template.settings} +============================= + +Normally you configure the Smarty settings by modifying the +[`Smarty class variables`](#api.variables). Furthermore you can register +plugins, filters etc. with [`Smarty functions`](#api.functions). +Modifications done to the Smarty object will be global for all +templates. + +However the Smarty class variables and functions can be accessed or +called by induvidual template objects. Modification done to a template +object will apply only for that template and its included subtemplates. + + + <?php + $tpl = $smarty->createTemplate('index.tpl); + $tpl->cache_lifetime = 600; + //or + $tpl->setCacheLifetime(600); + $smarty->display($tpl); + ?> + + + + + <?php + $tpl = $smarty->createTemplate('index.tpl); + $tpl->registerPlugin('modifier','mymodifier'); + $smarty->display($tpl); + ?> + + |