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

Rewrote docs on filters and resources.

Browse Source
This commit is contained in:
Simon Wisselink
2023-08-06 01:09:31 +02:00
parent 4550bd8dfd
commit 86b7d45399
17 changed files with 407 additions and 667 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
docs/api/filters/output-filters.md
View File

@@ -0,0 +1,35 @@
# Output filters
When a template is rendered, its output can be sent through one or more
output filters.
> **Note**
> This differs from [`prefilters`](prefilters.md) and
> [`postfilters`](postfilters.md) because, pre- and postfilters
> operate on compiled templates before they are saved to the disk, whereas
> output filters operate on the template output when it is executed.
Smarty will pass the template output as the first argument, and expect the function
to return the result of the processing.
Output filters can be either added as part of an [Extension](../extending/extensions.md) or
registered as shown below.
This will provide a rudimentary protection against spambots:
```php
<?php
function protect_email($tpl_output, \Smarty\Template\ $template)
{
return preg_replace(
'!(\S+)@([a-zA-Z0-9\.\-]+\.([a-zA-Z]{2,3}|[0-9]{1,3}))!',
'$1%40$2',
$tpl_output
);
}
// register the outputfilter
$smarty->registerFilter("output", "protect_email");
$smarty->display("index.tpl');
```

33
docs/api/filters/postfilters.md
View File

@@ -0,0 +1,33 @@
# Postfilters
Template postfilters are PHP functions that your templates are ran
through *after they are compiled*.
Smarty will
pass the compiled template code as the first argument, and expect the
function to return the result of the processing, which must also be valid PHP code.
Prefilters can be either added as part of an [Extension](../extending/extensions.md) or
registered as shown below.
```php
<?php
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');
```
The postfilter above will make the compiled Smarty template `index.tpl`
look like:
```smarty
<!-- Created by Smarty! -->
{* rest of template content... *}
```

26
docs/api/filters/prefilters.md
View File

@@ -0,0 +1,26 @@
# 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.
Smarty will pass the template source code as the first argument, and
expect the function to return the resulting template source code.
Prefilters can be either added as part of an [Extension](../extending/extensions.md) or
registered as shown below.
This will remove all the html comments in the template source:
```php
<?php
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');
```

2
docs/api/inheritance.md
View File

@@ -120,7 +120,7 @@ and parent templates can be merged by the `append` or `prepend`
## Extends resource type
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/resources-extends.md) type.
using the [`extends:` resource](resources.md#the-extends-resource) type.
The code below will return same result as the example above.

305
docs/api/resources.md
View File

@@ -0,0 +1,305 @@
# Template resources
## The filesystem resource
So far in our examples, we have used simple filenames or paths when loading a template.
For example, to load a template file called `homepage.tpl`, from the filesystem, you could write:
```php
<?php
use Smarty\Smarty;
$smarty = new Smarty();
$smarty->display('homepage.tpl');
```
The filesystem is the default resource. Templates, however, may come
from a variety of sources. When you render a template, or
when you include a template from within another template, you supply a
resource type, followed by `:` and the appropriate path and template name.
If a resource is not explicitly given, the default resource type is assumed.
The resource type for the filesystem is `file`, which means that the previous example
can be rewritten as follows:
```php
<?php
use Smarty\Smarty;
$smarty = new Smarty();
$smarty->display('file:homepage.tpl');
```
The file resource pulls templates source files from the directories
specified using `Smarty::setTemplateDir()` (see [Configuring Smarty](configuring.md)).
`setTemplateDir` accepts a single path, but can also ben called with an array of paths.
In that case, the list of directories is traversed in the order they appear in the array. The
first template found is the one to process.
### Templates from a specific directory
Smarty 3.1 introduced the bracket-syntax for specifying an element from
`Smarty::setTemplateDir()`. This allows websites
employing multiple sets of templates better control over which template
to access.
The bracket-syntax can be used as follows:
```php
<?php
// setup template directories
$smarty->setTemplateDir([
'./templates', // element: 0, index: 0
'./templates_2', // element: 1, index: 1
'10' => 'templates_10', // element: 2, index: '10'
'foo' => 'templates_foo', // element: 3, index: 'foo'
]);
/*
assume the template structure
./templates/foo.tpl
./templates_2/foo.tpl
./templates_2/bar.tpl
./templates_10/foo.tpl
./templates_10/bar.tpl
./templates_foo/foo.tpl
*/
// regular access
$smarty->display('file:foo.tpl');
// will load ./templates/foo.tpl
// using numeric index
$smarty->display('file:[1]foo.tpl');
// will load ./templates_2/foo.tpl
// using numeric string index
$smarty->display('file:[10]foo.tpl');
// will load ./templates_10/foo.tpl
// using string index
$smarty->display('file:[foo]foo.tpl');
// will load ./templates_foo/foo.tpl
// using "unknown" numeric index (using element number)
$smarty->display('file:[2]foo.tpl');
// will load ./templates_10/foo.tpl
```
And, from within a Smarty template:
```smarty
{include file="file:foo.tpl"}
{* will load ./templates/foo.tpl *}
{include file="file:[1]foo.tpl"}
{* will load ./templates_2/foo.tpl *}
{include file="file:[foo]foo.tpl"}
{* will load ./templates_foo/foo.tpl *}
```
### Using absolute paths
Templates outside the specified template directories
require the `file:` template resource type, followed by the absolute
path to the template (with leading slash).
```php
<?php
$smarty->display('file:/export/templates/index.tpl');
$smarty->display('file:/path/to/my/templates/menu.tpl');
````
And from within a Smarty template:
```smarty
{include file='file:/usr/local/share/templates/navigation.tpl'}
```
> **Note**
>
> With [`Security`](security.md) enabled, access to
> templates outside of the specified templates directories is
> not allowed unless you whitelist those directories.
### Windows file paths
If you are running on Windows, file paths usually include a drive
letter (such as `C:`) at the beginning of the pathname. Be sure to use `file:` in
the path to avoid namespace conflicts and get the desired results.
```php
<?php
$smarty->display('file:C:/export/templates/index.tpl');
$smarty->display('file:F:/path/to/my/templates/menu.tpl');
```
And from within Smarty template:
```smarty
{include file='file:D:/usr/local/share/templates/navigation.tpl'}
```
### Handling missing templates
If the file resource cannot find the requested template, it will check if there is
a default template handler to call. By default, there is none, and Smarty will return an error,
but you can register a default template handler calling `Smarty::registerDefaultTemplateHandler`
with any [callable](https://www.php.net/manual/en/language.types.callable.php).
```php
<?php
$smarty->registerDefaultTemplateHandler([$this, 'handleMissingTemplate']);
// ...
public function handleMissingTemplate($type, $name, &$content, &$modified, Smarty $smarty) {
if (/* ... */) {
// return corrected filepath
return "/tmp/some/foobar.tpl";
} elseif (/* ... */) {
// return a template directly
$content = "the template source";
$modified = time();
return true;
} else {
// tell smarty that we failed
return false;
}
}
```
## The string and eval resources
Smarty can render templates from a string by using the `string:` or
`eval:` resource.
- The `string:` resource behaves much the same as a template file. The
template source is compiled from a string and stores the compiled
template code for later reuse. Each unique template string will
create a new compiled template file. If your template strings are
accessed frequently, this is a good choice. If you have frequently
changing template strings (or strings with low reuse value), the
`eval:` resource may be a better choice, as it doesn\'t save
compiled templates to disk.
- The `eval:` resource evaluates the template source every time a page
is rendered. This is a good choice for strings with low reuse value.
If the same string is accessed frequently, the `string:` resource
may be a better choice.
> **Note**
>
> With a `string:` resource type, each unique string generates a
> compiled file. Smarty cannot detect a string that has changed, and
> therefore will generate a new compiled file for each unique string. It
> is important to choose the correct resource so that you do not fill
> your disk space with wasted compiled strings.
```php
<?php
$smarty->assign('foo', 'value');
$template_string = 'display {$foo} here';
$smarty->display('string:' . $template_string); // compiles for later reuse
$smarty->display('eval:' . $template_string); // compiles every time
```
From within a Smarty template:
```smarty
{include file="string:$template_string"} {* compiles for later reuse *}
{include file="eval:$template_string"} {* compiles every time *}
```
Both `string:` and `eval:` resources may be encoded with
[`urlencode()`](https://www.php.net/urlencode) or
[`base64_encode()`](https://www.php.net/urlencode). This is not necessary
for the usual use of `string:` and `eval:`, but is required when using
either of them in conjunction with the [`extends resource`](#the-extends-resource).
```php
<?php
$smarty->assign('foo','value');
$template_string_urlencode = urlencode('display {$foo} here');
$template_string_base64 = base64_encode('display {$foo} here');
$smarty->display('eval:urlencode:' . $template_string_urlencode); // will decode string using urldecode()
$smarty->display('eval:base64:' . $template_string_base64); // will decode string using base64_decode()
```
From within a Smarty template:
```smarty
{include file="string:urlencode:$template_string_urlencode"} {* will decode string using urldecode() *}
{include file="eval:base64:$template_string_base64"} {* will decode string using base64_decode() *}
```
## The extends resource
The `extends:` resource is used to define child/parent relationships. For details see section of
[Template inheritance](inheritance.md).
> **Note**
>
> Using the extends resource is usually not necessary. If you have a choice, it is normally more flexible and
> intuitive to handle inheritance chains from within the templates using the [{extends} tag](inheritance.md).
When `string:` and `eval:` templates are used, make sure they are properly url or base64 encoded.
The templates within an inheritance chain are not compiled separately. Only a single compiled template will be generated.
(If an `eval:` resource is found within an inheritance chain, its "don't save a compile file" property is superseded by
the `extends:` resource.)
Example:
```php
<?php
$smarty->display('extends:parent.tpl|child.tpl|grandchild.tpl');
// inheritance from multiple template sources
$smarty->display('extends:db:parent.tpl|file:child.tpl|grandchild.tpl|eval:{block name="fooBazVar_"}hello world{/block}');
```
## The stream resource
Smarty allow you to use [PHP streams](https://www.php.net/manual/en/function.stream-wrapper-register.php)
as a template resource. Smarty will first look for a registered template resource. If nothing is
found, it will check if a PHP stream is available. If a stream is available, Smarty will use it
to fetch the template.
For example,
```php
<?php
stream_wrapper_register('myresource', MyResourceStream::class);
$smarty->display('myresource:bar.tpl');
```
Or, from within a template:
```smarty
{include file="myresource:bar.tpl"}
```
## Adding your own resource type
You can create a class that extends `Smarty\Resource\CustomPlugin` to add your own resource type,
for example to load template from a database.
For example:
```php
<?php
class HelloWorldResource extends Smarty\Resource\CustomPlugin {
protected function fetch($name, &$source, &$mtime) {
$source = '{$x="hello world"}{$x}'; // load your template here based on $name
$mtime = time();
}
}
// ..
$smarty->registerResource('helloworld', new HelloWorldResource());
```
## Changing the default resource type
The default resource type is `file`. If you want to change it, use `Smarty::setDefaultResourceType`.
The following example will change the default resource type to `mysql`:
```php
<?php
$smarty->setDefaultResourceType('mysql');
```

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

@@ -1,37 +0,0 @@
# Output Filters
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.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-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;
}
// 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-functions/api-register-filter.md),
[`addExtension()`](../api-functions/add-extension.md) and
[postfilters](#advanced.features.postfilters).

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

@@ -1,35 +0,0 @@
# Postfilters
Template postfilters are PHP functions that your templates are ran
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;
}
// 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... *}
```
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).

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

@@ -1,31 +0,0 @@
# 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
[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);
}
// register the prefilter
$smarty->registerFilter('pre','remove_dw_comments');
$smarty->display('index.tpl');
```
See also [`registerFilter()`](../api-functions/api-register-filter.md),
[postfilters](advanced-features-postfilters.md), and
[`addExtension()`](../api-functions/add-extension.md).

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

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

19
docs/programmers/resources.md
View File

@@ -1,19 +0,0 @@
Resources
=========
The templates may come from a variety of sources. When you
[`display()`](./api-functions/api-display.md) or [`fetch()`](./api-functions/api-fetch.md) a template, or
when you include a template from within another template, you supply a
resource type, followed by the appropriate path and template name. If a
resource is not explicitly given, the value of
[`$default_resource_type`](./api-variables/variable-default-resource-type.md) (default:
\"file\") is assumed.
## Table of contents
- [File Template Resources](./resources/resources-file.md)
- [String Template Resources](./resources/resources-string.md)
- [Stream Template Resources](./resources/resources-streams.md)
- [Extends Template Resources](./resources/resources-extends.md)
- [Custom Template Resources](./resources/resources-custom.md)

113
docs/programmers/resources/resources-custom.md
View File

@@ -1,113 +0,0 @@
Custom Template Resources {#resources.custom}
=========================
You can retrieve templates using whatever possible source you can access
with PHP: databases, sockets, files, etc. You do this by writing
resource plugin functions and registering them with Smarty.
See [resource plugins](#plugins.resources) section for more information
on the functions you are supposed to provide.
> **Note**
>
> Note that you cannot override the built-in `file:` resource, but you
> can provide a resource that fetches templates from the file system in
> some other way by registering under another resource name.
<?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\Custom {
// 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'}

36
docs/programmers/resources/resources-extends.md
View File

@@ -1,36 +0,0 @@
Extends Template Resources {#resources.extends}
==========================
The `extends:` resource is used to define child/parent relationships for
template inheritance from the PHP script. For details see section of
[Template Inheritance](#advanced.features.template.inheritance).
As of Smarty 3.1 the `extends:` resource may use any available [template
resource](#resources), including `string:` and `eval:`. When [templates
from strings](#resources.string) are used, make sure they are properly
(url or base64) encoded. Is an `eval:` resource found within an
inheritance chain, its \"don\'t save a compile file\" property is
superseded by the `extends:` resource. The templates within an
inheritance chain are not compiled separately, though. Only a single
compiled template will be generated.
> **Note**
>
> Use this when inheritance is required programmatically. When inheriting
> within PHP, it is not obvious from the child template what inheritance
> took place. If you have a choice, it is normally more flexible and
> intuitive to handle inheritance chains from within the templates.
<?php
$smarty->display('extends:parent.tpl|child.tpl|grandchild.tpl');
// inheritance from multiple template sources
$smarty->display('extends:db:parent.tpl|file:child.tpl|grandchild.tpl|eval:{block name="fooBazVar_"}hello world{/block}');
?>
See also [Template Inheritance](#advanced.features.template.inheritance)
[`{block}`](#language.function.block) and
[`{extends}`](#language.function.extends).

154
docs/programmers/resources/resources-file.md
View File

@@ -1,154 +0,0 @@
File Template Resources {#resources.file}
=======================
Smarty ships with a built-in template resource for the filesystem. The
`file:` is the default resource. The resource key `file:` must only be
specified, if the
[`$default_resource_type`](#variable.default.resource.type) has been
changed.
If the file resource cannot find the requested template, the
[`$default_template_handler_func`](#variable.default.template.handler.func)
is invoked.
Templates from \$template\_dir {#templates.from.template.dir}
------------------------------
The file resource pulls templates source files from the directories
specified in [`$template_dir`](#variable.template.dir). The list of
directories is traversed in the order they appear in the array. The
first template found is the one to process.
<?php
$smarty->display('index.tpl');
$smarty->display('file:index.tpl'); // same as above
?>
From within a Smarty template
{include file='index.tpl'}
{include file='file:index.tpl'} {* same as above *}
Templates from a specific \$template\_dir {#templates.from.specified.template.dir}
-----------------------------------------
Smarty 3.1 introduced the bracket-syntax for specifying an element from
[`$template_dir`](#variable.template.dir). This allows websites
employing multiple sets of templates better control over which template
to access.
The bracket-syntax can be used from anywhere you can specify the `file:`
resource type.
<?php
// setup template directories
$smarty->setTemplateDir(array(
'./templates', // element: 0, index: 0
'./templates_2', // element: 1, index: 1
'10' => 'templates_10', // element: 2, index: '10'
'foo' => 'templates_foo', // element: 3, index: 'foo'
));
/*
assume the template structure
./templates/foo.tpl
./templates_2/foo.tpl
./templates_2/bar.tpl
./templates_10/foo.tpl
./templates_10/bar.tpl
./templates_foo/foo.tpl
*/
// regular access
$smarty->display('file:foo.tpl');
// will load ./templates/foo.tpl
// using numeric index
$smarty->display('file:[1]foo.tpl');
// will load ./templates_2/foo.tpl
// using numeric string index
$smarty->display('file:[10]foo.tpl');
// will load ./templates_10/foo.tpl
// using string index
$smarty->display('file:[foo]foo.tpl');
// will load ./templates_foo/foo.tpl
// using "unknown" numeric index (using element number)
$smarty->display('file:[2]foo.tpl');
// will load ./templates_10/foo.tpl
?>
From within a Smarty template
{include file="file:foo.tpl"}
{* will load ./templates/foo.tpl *}
{include file="file:[1]foo.tpl"}
{* will load ./templates_2/foo.tpl *}
{include file="file:[foo]foo.tpl"}
{* will load ./templates_foo/foo.tpl *}
Templates from any directory {#templates.from.any.dir}
----------------------------
Templates outside of the [`$template_dir`](#variable.template.dir)
require the `file:` template resource type, followed by the absolute
path to the template (with leading slash.)
> **Note**
>
> With [`Security`](#advanced.features.security) enabled, access to
> templates outside of the [`$template_dir`](#variable.template.dir) is
> not allowed unless you list those directories in `$secure_dir`.
<?php
$smarty->display('file:/export/templates/index.tpl');
$smarty->display('file:/path/to/my/templates/menu.tpl');
?>
And from within a Smarty template:
{include file='file:/usr/local/share/templates/navigation.tpl'}
Windows Filepaths {#templates.windows.filepath}
-----------------
If you are using a Windows machine, filepaths usually include a drive
letter (C:) at the beginning of the pathname. Be sure to use `file:` in
the path to avoid namespace conflicts and get the desired results.
<?php
$smarty->display('file:C:/export/templates/index.tpl');
$smarty->display('file:F:/path/to/my/templates/menu.tpl');
?>
And from within Smarty template:
{include file='file:D:/usr/local/share/templates/navigation.tpl'}

27
docs/programmers/resources/resources-streams.md
View File

@@ -1,27 +0,0 @@
Stream Template Resources {#resources.streams}
=========================
Streams allow you to use PHP streams as a template resource. The syntax
is much the same a traditional template resource names.
Smarty will first look for a registered template resource. If nothing is
found, it will check if a PHP stream is available. If a stream is
available, Smarty will use it to fetch the template.
> **Note**
>
> You can further define allowed streams with security enabled.
Using a PHP stream for a template resource from the display() function.
$smarty->display('foo:bar.tpl');
Using a PHP stream for a template resource from within a template.
{include file="foo:bar.tpl"}

73
docs/programmers/resources/resources-string.md
View File

@@ -1,73 +0,0 @@
String Template Resources {#resources.string}
=========================
Smarty can render templates from a string by using the `string:` or
`eval:` resource.
- The `string:` resource behaves much the same as a template file. The
template source is compiled from a string and stores the compiled
template code for later reuse. Each unique template string will
create a new compiled template file. If your template strings are
accessed frequently, this is a good choice. If you have frequently
changing template strings (or strings with low reuse value), the
`eval:` resource may be a better choice, as it doesn\'t save
compiled templates to disk.
- The `eval:` resource evaluates the template source every time a page
is rendered. This is a good choice for strings with low reuse value.
If the same string is accessed frequently, the `string:` resource
may be a better choice.
> **Note**
>
> With a `string:` resource type, each unique string generates a
> compiled file. Smarty cannot detect a string that has changed, and
> therefore will generate a new compiled file for each unique string. It
> is important to choose the correct resource so that you do not fill
> your disk space with wasted compiled strings.
<?php
$smarty->assign('foo','value');
$template_string = 'display {$foo} here';
$smarty->display('string:'.$template_string); // compiles for later reuse
$smarty->display('eval:'.$template_string); // compiles every time
?>
From within a Smarty template
{include file="string:$template_string"} {* compiles for later reuse *}
{include file="eval:$template_string"} {* compiles every time *}
Both `string:` and `eval:` resources may be encoded with
[`urlencode()`](https://www.php.net/urlencode) or
[`base64_encode()`](https://www.php.net/urlencode). This is not necessary
for the usual use of `string:` and `eval:`, but is required when using
either of them in conjunction with
[`Extends Template Resource`](#resources.extends)
<?php
$smarty->assign('foo','value');
$template_string_urlencode = urlencode('display {$foo} here');
$template_string_base64 = base64_encode('display {$foo} here');
$smarty->display('eval:urlencode:'.$template_string_urlencode); // will decode string using urldecode()
$smarty->display('eval:base64:'.$template_string_base64); // will decode string using base64_decode()
?>
From within a Smarty template
{include file="string:urlencode:$template_string_urlencode"} {* will decode string using urldecode() *}
{include file="eval:base64:$template_string_base64"} {* will decode string using base64_decode() *}

132
docs/programmers/resources/template-resources.md
View File

@@ -1,132 +0,0 @@
Resources {#resasdources}
=========
The templates may come from a variety of sources. When you
[`display()`](#api.display) or [`fetch()`](#api.fetch) a template, or
when you include a template from within another template, you supply a
resource type, followed by the appropriate path and template name. If a
resource is not explicitly given, the value of
[`$default_resource_type`](#variable.default.resource.type) is assumed.
Templates from other sources {#templates.from.elsewhere}
----------------------------
You can retrieve templates using whatever possible source you can access
with PHP: databases, sockets, files, etc. You do this by writing
resource plugin functions and registering them with Smarty.
See [resource plugins](#plugins.resources) section for more information
on the functions you are supposed to provide.
> **Note**
>
> Note that you cannot override the built-in `file:` resource, but you
> can provide a resource that fetches templates from the file system in
> some other way by registering under another resource name.
<?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\Custom {
// 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'}
Default template handler function {#default.template.handler.function}
---------------------------------
You can specify a function that is used to retrieve template contents in
the event the template cannot be retrieved from its resource. One use of
this is to create templates that do not exist on-the-fly.
See also [`Streams`](#advanced.features.streams)

13
mkdocs.yml
View File

@@ -123,19 +123,20 @@ nav:
- 'Objects': 'api/variables/objects.md'
- 'Static class methods': 'api/variables/static-class-methods.md'
- 'Template inheritance': 'api/inheritance.md'
- 'Filters':
- 'Output filters': 'api/filters/output-filters.md'
- 'Prefilters': 'api/filters/prefilters.md'
- 'Postfilters': 'api/filters/postfilters.md'
- 'Template resources': 'api/resources.md'
- 'Caching':
- 'Basics': 'api/caching/basics.md'
- 'Multiple caches per page': 'api/caching/multiple-caches-per-pages.md'
- 'Custom cache storage layers': 'api/caching/custom-storage-layers.md'
- 'Security': 'api/security.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'
- 'Filters':
- 'Prefilters': 'api/filters/prefilters.md'
- 'Postfilters': 'api/filters/postfilters.md'
- 'Output filters': 'api/filters/output-filters.md'
- 'Loading templates from resources': 'api/resources.md'
- 'Security': 'api/security.md'