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

finished docs on security and extending smarty

Browse Source
This commit is contained in:
Simon Wisselink
2023-08-07 01:44:57 +02:00
parent 8492bf5c61
commit d8b4496b7e
20 changed files with 380 additions and 846 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
docs/api/extending/block-tags.md
View File

@@ -0,0 +1,59 @@
# Custom block tags
Block tags are tags of the form: `{func} .. {/func}`. In other
words, they enclose a template block and operate on the contents of this
block.
Block functions take precedence over normal tags of the same name, that is, you
cannot have both custom tag `{func}` and block tag `{func}..{/func}`.
- By default, your function implementation is called twice by Smarty:
once for the opening tag, and once for the closing tag. (See
`$repeat` below on how to change this.)
- Only the opening tag of the block has attributes. All attributes are contained in the `$params`
variable as an associative array. The opening tag attributes are
also accessible to your function when processing the closing tag.
- The value of the `$content` variable depends on whether your
function is called for the opening or closing tag. In case of the
opening tag, it will be NULL, and in case of the closing tag it will
be the contents of the template block. Note that the template block
will have already been processed by Smarty, so all you will receive
is the template output, not the template source.
- The parameter `$repeat` is passed by reference to the function
implementation and provides a possibility for it to control how many
times the block is displayed. By default `$repeat` is TRUE at the
first call of the block function (the opening tag) and FALSE on all
subsequent calls to the block function (the block's closing tag).
Each time the function implementation returns with `$repeat` being
TRUE, the contents between `{func}...{/func}` are evaluated and the
function implementation is called again with the new block contents
in the parameter `$content`.
Example:
```php
<?php
function smarty_block_translate($params, $content, \Smarty\Template $template, &$repeat) {
// only output on the closing tag
if (!$repeat){
if (isset($content)) {
$lang = $params['lang'];
// do some intelligent translation thing here with $content
return $translation;
}
}
}
$smarty->registerPlugin(Smarty\Smarty::PLUGIN_BLOCK, 'translate', 'smarty_block_translate');
```
This can now be used in your templates as follows:
```smarty
{translate lang='nl'}
Quia omnis nulla omnis iusto est id et.
{/translate}
```

63
docs/api/extending/extensions.md
View File

@@ -0,0 +1,63 @@
# Creating an extension
In order to organize your custom tags and modifiers, you can create an Extension.
In fact, most of Smarty itself is organized into two extensions:
- the core extension, which provides the basic language tags such as `{if}`, `{for}` and `{assign}`.
- the default extension, which provides all default modifiers such as `|escape`, `|nl2br` and `|number_format`
and tags such as `{html_image}`, `{mailto}` and `{textformat}` that are enabled by default, but not necessarily universal.
> ** Note **
>
> There is also the 'BCPluginsAdapter' extension, which does not add any new functionality, but
> wraps calls to deprecated methods such as `Smarty\Smarty::addPluginsDir()` and `Smarty\Smarty::loadFilter()`.
In order to write your own custom extension, you must write a class that implements `Smarty\Extension\ExtensionInterface`.
However, it is usually easier to extend `Smarty\Extension\Base` which provides empty implementation for each of the methods
required by `Smarty\Extension\ExtensionInterface`. This allows you to only override the method(s) you need.
Example:
```php
<?php
use Smarty\Extension\Base;
class MyExtension extends Base {
public function getModifierCompiler(string $modifier): ?\Smarty\Compile\Modifier\ModifierCompilerInterface {
switch ($modifier) {
case 'array_escape': return new MyArrayEscapeModifierCompiler();
case 'array_unescape': return new MyArrayUnescapeModifierCompiler();
}
return null;
}
}
```
Another example, that would allow you to use any valid PHP callable as a modifier in your templates:
```php
<?php
use Smarty\Extension\Base;
class MyCallablePassThroughExtension extends Base {
public function getModifierCallback(string $modifierName) {
if (is_callable($modifierName)) {
return $modifierName;
}
return null;
}
}
```
Writing an extension allows you to add a group of tags, block tags and modifiers to the Smarty language.
It also allows you to register pre-, post- and output-filters in a structured way.
The files in `src/Extension/` in the `smarty/smarty` dir should give you all the information you need to start
writing your own extension.

10
docs/api/extending/introduction.md
View File

@@ -0,0 +1,10 @@
# Extending Smarty
By default, Smarty is already very complete and powerful. However, you can unlock its real potential by
extending Smarty.
There are various ways to extend Smarty for it to suit your needs. You can create custom
[tags](tags.md), [block tags](block-tags.md) and [modifiers](modifiers.md) by registering a method as a plugin.
If this becomes too messy, you can group your custom tags, modifiers, and more into an [Extension](extensions.md).

27
docs/api/extending/modifiers.md
View File

@@ -0,0 +1,27 @@
# Custom modifiers
Modifiers are little functions that are applied
to a variable in the template before it is displayed or used in some
other context. Smarty comes with a bunch of [modifiers](../../designers/language-modifiers/index.md), but you can
easily add your own.
In order to do so, you must write a function that accepts as its first parameter the value on which the
modifier is to operate. The rest of the parameters are optional, depending on what kind of operation is to be performed.
The modifier has to return the result of its processing.
For example:
```php
<?php
function smarty_modifier_substr($string, $offset, $length) {
return substr($string, $offset, $length);
}
$smarty->registerPlugin(Smarty\Smarty::PLUGIN_MODIFIER, 'substr', 'smarty_modifier_substr');
```
You can now use this in your templates as follows:
```smarty
{$applicationName|substr:0:20}
```

84
docs/api/extending/tags.md
View File

@@ -0,0 +1,84 @@
# Custom tags
You can add your own tags to the Smarty language.
## Runtime tags
Usually, you'll add a runtime tag. Adding a runtime tag requires you to provide a callback function that accepts
two parameters:
- `$params`: all attributes from the template as an associative array.
- `$template`: a `Smarty\Template` object representing the template where tag was used.
The output (return value) of the function will be substituted in place
of the tag in the template.
If the function needs to assign some variables to the template or use
some other Smarty-provided functionality, it can use the supplied
`$template` object to do so.
```php
<?php
function smarty_tag_eightball($params, \Smarty\Template $template): string {
$answers = [
'Yes',
'No',
'No way',
'Outlook not so good',
'Ask again soon',
'Maybe in your reality'
];
$result = array_rand($answers);
return $answers[$result];
}
$smarty->registerPlugin(Smarty\Smarty::PLUGIN_FUNCTION, 'eightball', 'smarty_tag_eightball');
```
Which can now be used in the template as:
```smarty
Question: Will we ever have time travel?
Answer: {eightball}.
```
## Compiler tags
Compiler tags are called only during compilation of the template.
They are useful for injecting PHP code or time-sensitive static content
into the template. If there is both a compiler function and a runtime tag registered under the same name,
the compiler function has precedence.
The compiler function is passed two parameters: the params array which
contains precompiled strings for the attribute values and the Smarty
object. It's supposed to return the code to be injected into the
compiled template including the surrounding PHP tags.
Example:
```php
<?php
function smarty_compiler_tplheader($params, Smarty $smarty) {
return "<?php\necho '" . $smarty->_current_file . " compiled at " . date('Y-m-d H:M'). "';\n?>";
}
$smarty->registerPlugin(Smarty\Smarty::PLUGIN_COMPILER, 'tplheader', 'smarty_compiler_tplheader');
```
This function can be called from the template as:
```smarty
{* this function gets executed at compile time only *}
{tplheader}
```
The resulting PHP code in the compiled template would be something like
this:
```php
<?php
echo 'index.tpl compiled at 2023-02-20 20:02';
```

17
docs/api/resources.md
View File

@@ -295,6 +295,23 @@ class HelloWorldResource extends Smarty\Resource\CustomPlugin {
$smarty->registerResource('helloworld', new HelloWorldResource());
```
If a Resource's templates should not be run through the Smarty
compiler, the Custom Resource may extend `\Smarty\Resource\UncompiledPlugin`.
The Resource Handler must then implement the function
`renderUncompiled(\Smarty\Template $_template)`. `$_template` is
a reference to the current template and contains all assigned variables
which the implementor can access via
`$_template->getSmarty()->getTemplateVars()`. These Resources simply echo
their rendered content to the output stream. The rendered output will be
output-cached if the Smarty instance was configured accordingly. See
`src/Resource/PhpPlugin.php` for an example.
If the Resource's compiled templates should not be cached on disk, the
Custom Resource may extend `\Smarty\Resource\RecompiledPlugin`. These Resources
are compiled every time they are accessed. This may be an expensive
overhead. See `src/Resource/StringEval.php` for an
example.
## Changing the default resource type
The default resource type is `file`. If you want to change it, use `Smarty::setDefaultResourceType`.

119
docs/api/security.md
View File

@@ -0,0 +1,119 @@
# Security
Security is good for situations when you have untrusted parties editing
the templates, and you want to reduce the risk of system
security compromises through the template language.
The settings of the security policy are defined by overriding public properties of an
instance of the \Smarty\Security class. These are the possible settings:
- `$secure_dir` is an array of template directories that are
considered secure. A directory configured using `$smarty->setTemplateDir()` 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 is used by
[`{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).
The expression `'#https?://.*smarty.net$#i'` would allow accessing
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.
- `$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 = [] ) 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".
If security is enabled, no private methods, functions or properties of
static classes or assigned objects can be accessed (beginning with
'_') by the template.
To customize the security policy settings you can extend the
\Smarty\Security class or create an instance of it.
```php
<?php
use Smarty\Smarty;
class My_Security_Policy extends \Smarty\Security {
public $allow_constants = false;
}
$smarty = new Smarty();
$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;
$smarty->enableSecurity($my_security_policy);
```
```php
<?php
use Smarty\Smarty;
$smarty = new Smarty();
// enable default security
$smarty->enableSecurity();
```
> **Note**
>
> Most security policy settings are only checked when the template gets
> compiled. For that reason you should delete all cached and compiled
> template files when you change your security settings.

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

@@ -1,113 +0,0 @@
# 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:
- `$secure_dir` is an array of template directories that are
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}`](../../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).
The expression `'#https?://.*smarty.net$#i'` would allow accessing
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.
- `$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 = [] ) 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".
If security is enabled, no private methods, functions or properties of
static classes or assigned objects can be accessed (beginning with
'_') by the template.
To customize the security policy settings you can extend the
\Smarty\Security class or create an instance of it.
```php
<?php
use Smarty\Smarty;
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
<?php
use Smarty\Smarty;
$smarty = new Smarty();
// enable default security
$smarty->enableSecurity();
```
> **Note**
>
> Most security policy settings are only checked when the template gets
> compiled. For that reason you should delete all cached and compiled
> template files when you change your security settings.

43
docs/programmers/plugins.md
View File

@@ -1,43 +0,0 @@
Extending Smarty With Plugins {#plugins}
=============================
## Table of contents
- [How Plugins Work](./plugins/plugins-howto.md)
- [Naming Conventions](./plugins/plugins-naming-conventions.md)
- [Writing Plugins](./plugins/plugins-writing.md)
- [Template Functions](./plugins/plugins-functions.md)
- [Modifiers](./plugins/plugins-modifiers.md)
- [Block Functions](./plugins/plugins-block-functions.md)
- [Compiler Functions](./plugins/plugins-compiler-functions.md)
- [Prefilters/Postfilters](./plugins/plugins-prefilters-postfilters.md)
- [Output Filters](./plugins/plugins-outputfilters.md)
- [Resources](./plugins/plugins-resources.md)
Version 2.0 introduced the plugin architecture that is used for almost
all the customizable functionality of Smarty. This includes:
- functions
- modifiers
- block functions
- compiler functions
- prefilters
- postfilters
- outputfilters
- resources
- inserts
With the exception of resources, backwards compatibility with the old
way of registering handler functions via register\_\* API is preserved.
If you did not use the API but instead modified the class variables
`$custom_funcs`, `$custom_mods`, and other ones directly, then you will
need to adjust your scripts to either use the API or convert your custom
functionality into plugins.

89
docs/programmers/plugins/plugins-block-functions.md
View File

@@ -1,89 +0,0 @@
Block Functions {#plugins.block.functions}
===============
void
smarty\_block\_
name
array
\$params
mixed
\$content
object
\$template
boolean
&\$repeat
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. Block functions take precedence over [custom
functions](#language.custom.functions) of the same name, that is, you
cannot have both custom function `{func}` and block function
`{func}..{/func}`.
- By default your function implementation is called twice by Smarty:
once for the opening tag, and once for the closing tag. (See
`$repeat` below on how to change this.)
- Starting with Smarty 3.1 the returned value of the opening tag call
is displayed as well.
- Only the opening tag of the block function may have
[attributes](#language.syntax.attributes). All attributes passed to
template functions from the template are contained in the `$params`
variable as an associative array. The opening tag attributes are
also accessible to your function when processing the closing tag.
- The value of the `$content` variable depends on whether your
function is called for the opening or closing tag. In case of the
opening tag, it will be NULL, and in case of the closing tag it will
be the contents of the template block. Note that the template block
will have already been processed by Smarty, so all you will receive
is the template output, not the template source.
- The parameter `$repeat` is passed by reference to the function
implementation and provides a possibility for it to control how many
times the block is displayed. By default `$repeat` is TRUE at the
first call of the block-function (the opening tag) and FALSE on all
subsequent calls to the block function (the block\'s closing tag).
Each time the function implementation returns with `$repeat` being
TRUE, the contents between `{func}...{/func}` are evaluated and the
function implementation is called again with the new block contents
in the parameter `$content`.
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File: block.translate.php
* Type: block
* Name: translate
* Purpose: translate a block of text
* -------------------------------------------------------------
*/
function smarty_block_translate($params, $content, \Smarty\Template $template, &$repeat)
{
// only output on the closing tag
if(!$repeat){
if (isset($content)) {
$lang = $params['lang'];
// do some intelligent translation thing here with $content
return $translation;
}
}
}
?>
See also: [`registerPlugin()`](#api.register.plugin),
[`unregisterPlugin()`](#api.unregister.plugin).

66
docs/programmers/plugins/plugins-compiler-functions.md
View File

@@ -1,66 +0,0 @@
Compiler Functions {#plugins.compiler.functions}
==================
Compiler functions are called only during compilation of the template.
They are useful for injecting PHP code or time-sensitive static content
into the template. If there is both a compiler function and a [custom
function](#language.custom.functions) registered under the same name,
the compiler function has precedence.
mixed
smarty\_compiler\_
name
array
\$params
object
\$smarty
The compiler function is passed two parameters: the params array which
contains precompiled strings for the attribute values and the Smarty
object. It\'s supposed to return the code to be injected into the
compiled template including the surrounding PHP tags.
<?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($params, Smarty $smarty)
{
return "<?php\necho '" . $smarty->_current_file . " compiled at " . date('Y-m-d H:M'). "';\n?>";
}
?>
This function can be called from the template as:
{* this function gets executed at compile time only *}
{tplheader}
The resulting PHP code in the compiled template would be something like
this:
<?php
echo 'index.tpl compiled at 2002-02-20 20:02';
?>
See also [`registerPlugin()`](#api.register.plugin),
[`unregisterPlugin()`](#api.unregister.plugin).

94
docs/programmers/plugins/plugins-functions.md
View File

@@ -1,94 +0,0 @@
Template Functions {#plugins.functions}
==================
void
smarty\_function\_
name
array
\$params
object
\$template
All [attributes](#language.syntax.attributes) passed to template
functions from the template are contained in the `$params` as an
associative array.
The output (return value) of the function will be substituted in place
of the function tag in the template, eg the
[`{fetch}`](#language.function.fetch) function. Alternatively, the
function can simply perform some other task without any output, eg the
[`{assign}`](#language.function.assign) function.
If the function needs to assign some variables to the template or use
some other Smarty-provided functionality, it can use the supplied
`$template` object to do so eg `$template->foo()`.
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File: function.eightball.php
* Type: function
* Name: eightball
* Purpose: outputs a random magic answer
* -------------------------------------------------------------
*/
function smarty_function_eightball($params, \Smarty\Template\ $template)
{
$answers = array('Yes',
'No',
'No way',
'Outlook not so good',
'Ask again soon',
'Maybe in your reality');
$result = array_rand($answers);
return $answers[$result];
}
?>
which can be used in the template as:
Question: Will we ever have time travel?
Answer: {eightball}.
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File: function.assign.php
* Type: function
* Name: assign
* Purpose: assign a value to a template variable
* -------------------------------------------------------------
*/
function smarty_function_assign($params, \Smarty\Template\ $template)
{
if (empty($params['var'])) {
trigger_error("assign: missing 'var' parameter");
return;
}
if (!in_array('value', array_keys($params))) {
trigger_error("assign: missing 'value' parameter");
return;
}
$template->assign($params['var'], $params['value']);
}
?>
See also: [`registerPlugin()`](#api.register.plugin),
[`unregisterPlugin()`](#api.unregister.plugin).

18
docs/programmers/plugins/plugins-howto.md
View File

@@ -1,18 +0,0 @@
How Plugins Work {#plugins.howto}
================
Plugins are always loaded on demand. Only the specific modifiers,
functions, resources, etc invoked in the templates scripts will be
loaded. Moreover, each plugin is loaded only once, even if you have
several different instances of Smarty running within the same request.
Pre/postfilters and output filters are a bit of a special case. Since
they are not mentioned in the templates, they must be registered or
loaded explicitly via API functions before the template is processed.
The order in which multiple filters of the same type are executed
depends on the order in which they are registered or loaded.
The [plugins directory](#variable.plugins.dir) can be a string
containing a path or an array containing multiple paths. To install a
plugin, simply place it in one of the directories and Smarty will use it
automatically.

86
docs/programmers/plugins/plugins-modifiers.md
View File

@@ -1,86 +0,0 @@
Modifiers {#plugins.modifiers}
=========
[Modifiers](#language.modifiers) are little functions that are applied
to a variable in the template before it is displayed or used in some
other context. Modifiers can be chained together.
mixed
smarty\_modifier\_
name
mixed
\$value
\[mixed
\$param1
, \...\]
The first parameter to the modifier plugin is the value on which the
modifier is to operate. The rest of the parameters are optional,
depending on what kind of operation is to be performed.
The modifier has to [return](https://www.php.net/return) the result of its
processing.
This plugin basically aliases one of the built-in PHP functions. It does
not have any additional parameters.
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File: modifier.capitalize.php
* Type: modifier
* Name: capitalize
* Purpose: capitalize words in the string
* -------------------------------------------------------------
*/
function smarty_modifier_capitalize($string)
{
return ucwords($string);
}
?>
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File: modifier.truncate.php
* Type: modifier
* Name: truncate
* Purpose: Truncate a string to a certain length if necessary,
* optionally splitting in the middle of a word, and
* appending the $etc string.
* -------------------------------------------------------------
*/
function smarty_modifier_truncate($string, $length = 80, $etc = '...',
$break_words = false)
{
if ($length == 0)
return '';
if (strlen($string) > $length) {
$length -= strlen($etc);
$fragment = substr($string, 0, $length+1);
if ($break_words)
$fragment = substr($fragment, 0, -1);
else
$fragment = preg_replace('/\s+(\S+)?$/', '', $fragment);
return $fragment.$etc;
} else
return $string;
}
?>
See also [`registerPlugin()`](#api.register.plugin),
[`unregisterPlugin()`](#api.unregister.plugin).

49
docs/programmers/plugins/plugins-naming-conventions.md
View File

@@ -1,49 +0,0 @@
Naming Conventions {#plugins.naming.conventions}
==================
Plugin files and functions must follow a very specific naming convention
in order to be located by Smarty.
**plugin files** must be named as follows:
> `
> type.name.php
> `
- Where `type` is one of these plugin types:
- function
- modifier
- block
- compiler
- prefilter
- postfilter
- outputfilter
- resource
- And `name` should be a valid identifier; letters, numbers, and
underscores only, see [php
variables](https://www.php.net/language.variables).
- Some examples: `function.html_select_date.php`, `resource.db.php`,
`modifier.spacify.php`.
**plugin functions** inside the PHP files must be named as follows:
> `smarty_type_name`
- The meanings of `type` and `name` are the same as above.
- An example modifier name `foo` would be
`function smarty_modifier_foo()`.
Smarty will output appropriate error messages if the plugin file it
needs is not found, or if the file or the plugin function are named
improperly.

48
docs/programmers/plugins/plugins-outputfilters.md
View File

@@ -1,48 +0,0 @@
Output Filters {#plugins.outputfilters}
==============
Output filter plugins operate on a template\'s output, after the
template is loaded and executed, but before the output is displayed.
string
smarty\_outputfilter\_
name
string
\$template\_output
object
\$template
The first parameter to the output filter function is the template output
that needs to be processed, and the second parameter is the instance of
Smarty invoking the plugin. The plugin is supposed to do the processing
and return the results.
<?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\Template\ $template)
{
return preg_replace('!(\S+)@([a-zA-Z0-9\.\-]+\.([a-zA-Z]{2,3}|[0-9]{1,3}))!',
'$1%40$2', $output);
}
?>
See also [`registerFilter()`](#api.register.filter),
[`unregisterFilter()`](#api.unregister.filter).

89
docs/programmers/plugins/plugins-prefilters-postfilters.md
View File

@@ -1,89 +0,0 @@
Prefilters/Postfilters {#plugins.prefilters.postfilters}
======================
Prefilter and postfilter plugins are very similar in concept; where they
differ is in the execution \-- more precisely the time of their
execution.
string
smarty\_prefilter\_
name
string
\$source
object
\$template
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.
string
smarty\_postfilter\_
name
string
\$compiled
object
\$template
Postfilters are used to process the compiled output of the template (the
PHP code) immediately after the compilation is done but before the
compiled template is saved to the filesystem. The first parameter to the
postfilter function is the compiled template code, possibly modified by
other postfilters. The plugin is supposed to return the modified version
of this code.
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File: prefilter.pre01.php
* Type: prefilter
* Name: pre01
* Purpose: Convert html tags to be lowercase.
* -------------------------------------------------------------
*/
function smarty_prefilter_pre01($source, \Smarty\Template\ $template)
{
return preg_replace('!<(\w+)[^>]+>!e', 'strtolower("$1")', $source);
}
?>
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File: postfilter.post01.php
* Type: postfilter
* Name: post01
* Purpose: Output code that lists all current template vars.
* -------------------------------------------------------------
*/
function smarty_postfilter_post01($compiled, \Smarty\Template\ $template)
{
$compiled = "<pre>\n<?php print_r(\$template->getTemplateVars()); ?>\n</pre>" . $compiled;
return $compiled;
}
?>
See also [`registerFilter()`](#api.register.filter) and
[`unregisterFilter()`](#api.unregister.filter).

130
docs/programmers/plugins/plugins-resources.md
View File

@@ -1,130 +0,0 @@
Resources {#plugins.resources}
=========
Resource plugins are meant as a generic way of providing template
sources or PHP script components to Smarty. Some examples of resources:
databases, LDAP, shared memory, sockets, and so on.
Custom Resources may be put in a file `resource.foobarxyz.php` within
your [`$plugins_dir`](#variable.plugins.dir), or registered on runtime
with [`registerResource()`](#api.register.resource). In either case you
will be able to access that resource by prepending its name to the
template you\'re addressing: `foobarxyz:yourtemplate.tpl`.
If a Resource\'s templates should not be run through the Smarty
compiler, the Custom Resource may extend `\Smarty\Resource\UncompiledPlugin`.
The Resource Handler must then implement the function
`renderUncompiled(\Smarty\Template $_template)`. `$_template` is
a reference to the current template and contains all assigned variables
which the implementor can access via
`$_template->getSmarty()->getTemplateVars()`. These Resources simply echo
their rendered content to the output stream. The rendered output will be
output-cached if the Smarty instance was configured accordingly. See
`src/Resource/PhpPlugin.php` for an example.
If the Resource\'s compiled templates should not be cached on disk, the
Custom Resource may extend `\Smarty\Resource\RecompiledPlugin`. These Resources
are compiled every time they are accessed. This may be an expensive
overhead. See `src/Resource/StringEval.php` for an
example.
<?php
use Smarty\Smarty;
/**
* MySQL Resource
*
* Resource Implementation based on the Custom API to use
* MySQL as the storage resource for Smarty's templates and configs.
*
* Table definition:
* <pre>CREATE TABLE IF NOT EXISTS `templates` (
* `name` varchar(100) NOT NULL,
* `modified` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
* `source` text,
* PRIMARY KEY (`name`)
* ) ENGINE=InnoDB DEFAULT CHARSET=utf8;</pre>
*
* Demo data:
* <pre>INSERT INTO `templates` (`name`, `modified`, `source`) VALUES ('test.tpl', "2010-12-25 22:00:00", '{$x="hello world"}{$x}');</pre>
*
* @author Rodney Rehm
*/
class My_Resource_Mysql extends \Smarty\Resource\CustomPlugin {
// PDO instance
protected $db;
// prepared fetch() statement
protected $fetch;
// prepared fetchTimestamp() statement
protected $mtime;
public function __construct() {
try {
$this->db = new PDO("mysql:dbname=test;host=127.0.0.1", "smarty", "smarty");
} catch (PDOException $e) {
throw new \Smarty\Exception('Mysql Resource failed: ' . $e->getMessage());
}
$this->fetch = $this->db->prepare('SELECT modified, source FROM templates WHERE name = :name');
$this->mtime = $this->db->prepare('SELECT modified FROM templates WHERE name = :name');
}
/**
* Fetch a template and its modification time from database
*
* @param string $name template name
* @param string $source template source
* @param integer $mtime template modification timestamp (epoch)
* @return void
*/
protected function fetch($name, &$source, &$mtime)
{
$this->fetch->execute(array('name' => $name));
$row = $this->fetch->fetch();
$this->fetch->closeCursor();
if ($row) {
$source = $row['source'];
$mtime = strtotime($row['modified']);
} else {
$source = null;
$mtime = null;
}
}
/**
* Fetch a template's modification time from database
*
* @note implementing this method is optional. Only implement it if modification times can be accessed faster than loading the comple template source.
* @param string $name template name
* @return integer timestamp (epoch) the template was modified
*/
protected function fetchTimestamp($name) {
$this->mtime->execute(array('name' => $name));
$mtime = $this->mtime->fetchColumn();
$this->mtime->closeCursor();
return strtotime($mtime);
}
}
$smarty = new Smarty();
$smarty->registerResource('mysql', new My_Resource_Mysql());
// using resource from php script
$smarty->display("mysql:index.tpl");
?>
And from within Smarty template:
{include file='mysql:extras/navigation.tpl'}
See also [`registerResource()`](#api.register.resource),
[`unregisterResource()`](#api.unregister.resource).

20
docs/programmers/plugins/plugins-writing.md
View File

@@ -1,20 +0,0 @@
Writing Plugins {#plugins.writing}
===============
Plugins can be either loaded by Smarty automatically from the filesystem
or they can be registered at runtime via one of the register\_\* API
functions. They can also be unregistered by using unregister\_\* API
functions.
For the plugins that are registered at runtime, the name of the plugin
function(s) does not have to follow the naming convention.
As a general rule, the currently evaluated template\'s
Smarty\_Internal\_Template object is always passed to the plugins as the
last parameter with two exceptions:
- modifiers do not get passed the Smarty\_Internal\_Template object at
all
- blocks get passed `$repeat` after the Smarty\_Internal\_Template
object to keep backwards compatibility to older versions of Smarty.

2
mkdocs.yml
View File

@@ -134,9 +134,9 @@ nav:
- 'Custom cache storage layers': 'api/caching/custom-storage-layers.md'
- 'Extending Smarty':
- 'Introduction': 'api/extending/introduction.md'
- 'Creating an Extension': 'api/extending/extensions.md'
- 'Custom tags': 'api/extending/tags.md'
- 'Custom block tags': 'api/extending/block-tags.md'
- 'Custom modifiers': 'api/extending/modifiers.md'
- 'Creating an extension': 'api/extending/extensions.md'
- 'Security': 'api/security.md'