smarty-php/smarty
1
0
Fork 0
mirror of https://github.com/smarty-php/smarty.git synced 2025-07-29 07:27:14 +02:00
Code Issues Packages Projects Releases Wiki Activity

Feature/add docs (#689)

Browse Source 
* Add converted docs repo

* Set theme jekyll-theme-minimal

* Removed BC docs, added TOC

* Added TOCs, rewrote most important links in documentation. Linked README to new Github Pages site

* some link fixes
This commit is contained in:
Simon Wisselink
2021-12-03 11:59:22 +01:00
committed by GitHub
parent baebd59bb4
commit 428a701b18
226 changed files with 13978 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

99
docs/programmers/advanced-features/advanced-features-objects.md Normal file
View File

@ -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).

43
docs/programmers/advanced-features/advanced-features-outputfilters.md Normal file
View File

@ -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).

40
docs/programmers/advanced-features/advanced-features-postfilters.md Normal file
View File

@ -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).

36
docs/programmers/advanced-features/advanced-features-prefilters.md Normal file
View File

@ -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).

168
docs/programmers/advanced-features/advanced-features-security.md Normal file
View File

@ -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.

27
docs/programmers/advanced-features/advanced-features-static-classes.md Normal file
View File

@ -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

15
docs/programmers/advanced-features/advanced-features-streams.md Normal file
View File

@ -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)

128
docs/programmers/advanced-features/advanced-features-template-inheritance.md Normal file
View File

@ -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)

32
docs/programmers/advanced-features/advanced-features-template-settings.md Normal file
View File

@ -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);
?>