smarty-php/smarty
1
0
Fork 0
mirror of https://github.com/smarty-php/smarty.git synced 2025-10-08 18:21:03 +02:00
Code Issues Packages Projects Releases Wiki Activity

Further WIP improving docs

Browse Source
This commit is contained in:
Simon Wisselink
2023-03-09 23:16:18 +01:00
parent 7a323b7345
commit 5db8fd2533
58 changed files with 519 additions and 913 deletions
Download Patch File Download Diff File Expand all files Collapse all files

84
docs/programmers/advanced-features/advanced-features-objects.md
View File

@@ -1,5 +1,4 @@
Objects {#advanced.features.objects}
=======
# Objects
Smarty allows access to PHP [objects](https://www.php.net/object) through
the templates.
@@ -14,11 +13,11 @@ the templates.
There are two ways to access them.
- One way is to [register objects](#api.register.object) to the
- One way is to [register objects](../api-functions/api-register-object.md) to the
template, then use access them via syntax similar to [custom
functions](#language.custom.functions).
functions](../../designers/language-custom-functions/index.md).
- The other way is to [`assign()`](#api.assign) objects to the
- The other way is to [`assign()`](../api-functions/api-assign.md) 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
@@ -29,14 +28,14 @@ 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
(beginning with \'\_\'). If a method and property of the same name exist,
(beginning with '_'). 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
passed the same way [custom functions](../../designers/language-custom-functions/index.md) 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
@@ -47,53 +46,50 @@ 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
[`block-function-plugins`](../plugins/plugins-block-functions.md): They get the four
parameters `$params`, `$content`, `$smarty` and `&$repeat` and they also
behave like block-function-plugins.
```php
<?php
// the object
<?php
// the object
class My_Object {
function meth1($params, $smarty_obj) {
return 'this is my meth1';
}
class My_Object {
function meth1($params, $smarty_obj) {
return 'this is my meth1';
}
}
$myobj = new My_Object;
$myobj = new My_Object;
// registering the object (will be by reference)
$smarty->registerObject('foobar',$myobj);
// 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 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);
// 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);
// We can also assign objects. assign_by_ref when possible.
$smarty->assign_by_ref('myobj', $myobj);
$smarty->display('index.tpl');
?>
$smarty->display('index.tpl');
```
And here's how to access your objects in `index.tpl`:
```smarty
{* 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)}
```
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).
See also [`registerObject()`](../api-functions/api-register-object.md) and
[`assign()`](../api-functions/api-assign.md).

54
docs/programmers/advanced-features/advanced-features-outputfilters.md
View File

@@ -1,41 +1,37 @@
Output Filters {#advanced.features.outputfilters}
==============
# Output Filters
When the template is invoked via [`display()`](#api.display) or
[`fetch()`](#api.fetch), its output can be sent through one or more
When the template is invoked via [`display()`](../api-functions/api-display.md) or
[`fetch()`](../api-functions/api-fetch.md), its output can be sent through one or more
output filters. This differs from
[`postfilters`](#advanced.features.postfilters) because postfilters
[`postfilters`](advanced-features-postfilters.md) 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. Smarty will
Output filters can be either [registered](../api-functions/api-register-filter.md)
or added as part of a [custom extension](extending-smarty.md). Smarty will
pass the template output as the first argument, and expect the function
to return the result of the processing.
```php
<?php
// put this in your application
function protect_email($tpl_output, \Smarty\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;
}
<?php
// put this in your application
function protect_email($tpl_output, \Smarty\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
?>
// 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),
[postfilters](#advanced.features.postfilters) and
[`$plugins_dir`](#variable.plugins.dir).
See also [`registerFilter()`](../api-functions/api-register-filter.md),
[`addExtension()`](../api-functions/add-extension.md) and
[postfilters](#advanced.features.postfilters).

52
docs/programmers/advanced-features/advanced-features-postfilters.md
View File

@@ -1,39 +1,35 @@
Postfilters {#advanced.features.postfilters}
===========
# 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. Smarty will
through *after they are compiled*.
Postfilters can be
[registered](../api-functions/api-register-filter.md) or added as part of a [custom extension](extending-smarty.md). Smarty will
pass the compiled template code as the first argument, and expect the
function to return the result of the processing.
```php
<?php
// put this in your application
function add_header_comment($tpl_source, \Smarty\Template\ $template)
{
return "<?php echo \"<!-- Created by Smarty! -->\n\"; ?>\n".$tpl_source;
}
<?php
// put this in your application
function add_header_comment($tpl_source, \Smarty\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');
?>
// 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:
```smarty
<!-- Created by Smarty! -->
{* rest of template content... *}
```
<!-- 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).
See also [`registerFilter()`](../api-functions/api-register-filter.md),
[prefilters](advanced-features-prefilters.md),
[outputfilters](advanced-features-outputfilters.md), and
[`addExtension()`](../api-functions/add-extension.md).

38
docs/programmers/advanced-features/advanced-features-prefilters.md
View File

@@ -1,35 +1,31 @@
Prefilters {#advanced.features.prefilters}
==========
# 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.
Prefilters can be
[registered](../api-functions/api-register-filter.md) or added as part of a [custom extension](extending-smarty.md).
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
<?php
// put this in your application
function remove_dw_comments($tpl_source, \Smarty\Template\ $template)
{
return preg_replace("/<!--#.*-->/U",'',$tpl_source);
}
<?php
// put this in your application
function remove_dw_comments($tpl_source, \Smarty\Template\ $template)
{
return preg_replace("/<!--#.*-->/U",'',$tpl_source);
}
// register the prefilter
$smarty->registerFilter('pre','remove_dw_comments');
$smarty->display('index.tpl');
```
// 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).
See also [`registerFilter()`](../api-functions/api-register-filter.md),
[postfilters](advanced-features-postfilters.md), and
[`addExtension()`](../api-functions/add-extension.md).

83
docs/programmers/advanced-features/advanced-features-security.md
View File

@@ -1,21 +1,20 @@
Security {#advanced.features.security}
========
# Security
Security is good for situations when you have untrusted parties editing
the templates e.g. 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:
instance of the \Smarty\Security class. These are the possible settings:
- `$secure_dir` is an array of template directories that are
considered secure. [`$template_dir`](#variable.template.dir)
considered secure. A [template dir](../../api/configuring.md#setting-the-template-path--s-) is
considered secure implicitly. 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
[`{fetch}`](../../designers/language-custom-functions/language-function-fetch.md) and
[`{html_image}`](../../designers/language-custom-functions/language-function-html-image.md). 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).
@@ -24,33 +23,27 @@ instance of the Smarty\_Security class. These are the possible settings:
the following 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.
$static_classes = null.
- `$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\').
set $streams = null. An empty array ( $streams = [] ) 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
@@ -69,49 +62,49 @@ instance of the Smarty\_Security class. These are the possible settings:
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\".
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\".
"true".
If security is enabled, no private methods, functions or properties of
static classes or assigned objects can be accessed (beginning with
\'\_\') by the template.
'_') by the template.
To customize the security policy settings you can extend the
Smarty\_Security class or create an instance of it.
\Smarty\Security class or create an instance of it.
```php
<?php
<?php
use Smarty\Smarty;
use Smarty\Smarty;
class My_Security_Policy extends \Smarty\Security {
public $allow_constants = false;
}
$smarty = new Smarty();
// enable security
$smarty->enableSecurity('My_Security_Policy');
```
class My_Security_Policy extends \Smarty\Security {
public $allow_constants = false;
}
$smarty = new Smarty();
// enable security
$smarty->enableSecurity('My_Security_Policy');
?>
```php
<?php
use Smarty\Smarty;
$smarty = new Smarty();
$my_security_policy = new \Smarty\Security($smarty);
$my_security_policy->allow_constants = false;
// enable security
$smarty->enableSecurity($my_security_policy);
```
<?php
use Smarty\Smarty;
$smarty = new Smarty();
$my_security_policy = new \Smarty\Security($smarty);
$my_security_policy->allow_constants = false;
// enable security
$smarty->enableSecurity($my_security_policy);
?>
<?php
use Smarty\Smarty;
$smarty = new Smarty();
// enable default security
$smarty->enableSecurity();
?>
```php
<?php
use Smarty\Smarty;
$smarty = new Smarty();
// enable default security
$smarty->enableSecurity();
```
> **Note**
>

34
docs/programmers/advanced-features/advanced-features-static-classes.md
View File

@@ -1,7 +1,6 @@
Static Classes {#advanced.features.static.classes}
==============
# Static Classes
You can directly access static classes. The syntax is the same as in
You can directly access static classes. The syntax is roughly the same as in
PHP.
> **Note**
@@ -12,16 +11,29 @@ PHP.
> plugins which insulate templates from PHP classes/objects. Use at your
> own discretion. See the Best Practices section of the Smarty website.
## Examples
{assign var=foo value=myclass::BAR} <--- class constant BAR
**class constant BAR**
```smarty
{assign var=foo value=myclass::BAR}
```
{assign var=foo value=myclass::method()} <--- method result
**method result**
```smarty
{assign var=foo value=myclass::method()}
```
{assign var=foo value=myclass::method1()->method2} <--- method chaining
**method chaining**
```smarty
{assign var=foo value=myclass::method1()->method2}
```
{assign var=foo value=myclass::$bar} <--- property bar of class myclass
**property bar of class myclass**
```smarty
{assign var=foo value=myclass::$bar}
```
{assign var=foo value=$bar::method} <--- using Smarty variable bar as class name
**using Smarty variable bar as class name**
```smarty
{assign var=foo value=$bar::method}
```

14
docs/programmers/advanced-features/advanced-features-streams.md
View File

@@ -1,15 +1,13 @@
Streams {#advanced.features.streams}
=======
# Streams
You can also use streams to call variables. *{\$foo:bar}* will use the
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.
```smarty
{$foo:bar}
```
{$foo:bar}
See also [`Template Resources`](#resources)
See also [`Template Resources`](../resources.md)

106
docs/programmers/advanced-features/advanced-features-template-inheritance.md
View File

@@ -1,5 +1,4 @@
Template Inheritance {#advanced.features.template.inheritance}
====================
# Template Inheritance
Inheritance brings the concept of Object Oriented Programming to
templates, allowing you to define one (or more) base templates that can
@@ -10,26 +9,26 @@ can override all or some of the parent named block areas.
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
- The child templates can not define any content besides what's
inside [`{block}`](../../designers/language-builtin-functions/language-function-block.md) tags they override.
Anything outside of [`{block}`](../../designers/language-builtin-functions/language-function-block.md) tags will
be removed.
- The content of [`{block}`](#language.function.block) tags from child
- The content of [`{block}`](../../designers/language-builtin-functions/language-function-block.md) tags from child
and parent templates can be merged by the `append` or `prepend`
[`{block}`](#language.function.block) tag option flags and
[`{block}`](../../designers/language-builtin-functions/language-function-block.md) 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
[`{include}`](../../designers/language-builtin-functions/language-function-include.md) 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
[`{extends}`](../../designers/language-builtin-functions/language-function-extends.md) tag, which must be the
first line in the child template. Instead of using the
[`{extends}`](#language.function.extends) tags in the template files
[`{extends}`](../../designers/language-builtin-functions/language-function-extends.md) 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
@@ -44,85 +43,86 @@ can override all or some of the parent named block areas.
> **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
> [`{include}`](../../designers/language-builtin-functions/language-function-include.md) and it contains
> [`{block}`](../../designers/language-builtin-functions/language-function-block.md) areas it works only if the
> [`{include}`](../../designers/language-builtin-functions/language-function-include.md) itself is called from within
> a surrounding [`{block}`](../../designers/language-builtin-functions/language-function-block.md). In the final
> parent template you may need a dummy
> [`{block}`](#language.function.block) for it.
> [`{block}`](../../designers/language-builtin-functions/language-function-block.md) for it.
layout.tpl (parent)
<html>
```smarty
<html>
<head>
<title>{block name=title}Default Page Title{/block}</title>
{block name=head}{/block}
</head>
<body>
{block name=body}{/block}
{block name=body}{/block}
</body>
</html>
</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}
```smarty
{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}
```smarty
{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');
```php
<?php
$smarty->display('mypage.tpl');
```
The resulting output is
<html>
```smarty
<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
My HTML Page Body goes here
</body>
</html>
</html>
```
Instead of using [`{extends}`](#language.function.extends) tags in the
Instead of using [`{extends}`](../../designers/language-builtin-functions/language-function-extends.md) tags in the
template files you can define the inheritance tree in your PHP script by
using the [`extends:` resource](#resources.extends) type.
using the [`extends:` resource](../resources/resources-extends.md) type.
The code below will return same result as the example above.
```php
<?php
$smarty->display('extends:layout.tpl|myproject.tpl|mypage.tpl');
```
<?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)
See also [`{block}`](../../designers/language-builtin-functions/language-function-block.md),
[`{extends}`](../../designers/language-builtin-functions/language-function-extends.md) and [`extends:`
resource](../resources/resources-extends.md)

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

@@ -1,32 +0,0 @@
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 individual 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);
?>

3
docs/programmers/advanced-features/extending-smarty.md Normal file
View File

@@ -0,0 +1,3 @@
# Extending Smarty
@TODO