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

Docs on caching

Browse Source
This commit is contained in:
Simon Wisselink
2023-08-07 00:14:54 +02:00
parent 019fe3f5e7
commit 8492bf5c61
13 changed files with 361 additions and 754 deletions
Download Patch File Download Diff File Expand all files Collapse all files

184
docs/api/caching/basics.md
View File

@@ -0,0 +1,184 @@
# Caching
Caching is used to speed up the rendering of a template by saving and re-using the output.
If a cached version of the call is available, that is displayed instead of
regenerating the output. Caching can speed things up tremendously,
especially templates with longer computation times.
Since templates can include or extend other templates, one
cache file could conceivably be made up of several template files,
config files, etc.
> ** Note **
>
> Since templates are dynamic, it is important to be careful what you are
> caching and for how long. For instance, if you are displaying the front
> page of your website that does not change its content very often, it
> might work well to cache this page for an hour or more. On the other
> hand, if you are displaying a page with a timetable containing new
> information by the minute, it would not make sense to cache this page.
## Setting Up Caching
The first thing to do is enable caching by calling `Smarty::setCaching()` with either
`\Smarty\Smarty::CACHING_LIFETIME_CURRENT` or `\Smarty\Smarty::CACHING_LIFETIME_SAVED`.
Or with `\Smarty\Smarty::CACHING_OFF` to disable caching again.
```php
<?php
use Smarty\Smarty;
$smarty = new Smarty;
// enable caching, using the current lifetime (see below)
$smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
// enable caching, using the lifetime set when the cache was saved (see below)
$smarty->setCaching(Smarty::CACHING_LIFETIME_SAVED);
// disable caching
$smarty->setCaching(Smarty::CACHING_OFF);
$smarty->display('index.tpl');
```
With caching enabled, the function call to `$smarty->display('index.tpl')` will
render the template as usual, but also saves a copy of its output. On the
next call to `$smarty->display('index.tpl')`, the cached copy will be used
instead of rendering the template again.
> **Note**
>
> By default, Smarty saved its caches as files in a dir called `cache` relative to the current
> directory. The default directory can be changed using `$smarty->setCacheDir('/some/cache/dir');`
> The files are named similar
> to the template name. Although they end in the `.php` extension, they
> are not intended to be directly executable. Do not edit these files!
## Cache lifetime
Each cached page has a limited lifetime. The default value is 3600
seconds, or one hour. After that time expires, the cache is regenerated.
You can change the lifetime as follows:
```php
<?php
use Smarty\Smarty;
$smarty = new Smarty;
$smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
// or $smarty->setCaching(Smarty::CACHING_LIFETIME_SAVED);
// set the cache_lifetime to 5 minutes
$smarty->setCacheLifetime(5 * 60);
```
Setting caching to a value of `\Smarty\Smarty::CACHING_LIFETIME_CURRENT` tells Smarty to use
the current lifetime to determine if the cache has expired.
A value of `\Smarty\Smarty::CACHING\_LIFETIME\_SAVED` tells Smarty to use the lifetime value at the time the
cache was generated. This way you can set the just before rendering a template to have granular control over
when that particular cache expires.
An example:
```php
<?php
use Smarty\Smarty;
$smarty = new Smarty;
// retain current cache lifetime for each specific display call
$smarty->setCaching(Smarty::CACHING_LIFETIME_SAVED);
// set the cache_lifetime for index.tpl to 5 minutes
$smarty->setCacheLifetime(300);
$smarty->display('index.tpl');
// set the cache_lifetime for home.tpl to 1 hour
$smarty->setCacheLifetime(3600);
$smarty->display('home.tpl');
// NOTE: the following $cache_lifetime setting will not work when $caching
// is set to Smarty::CACHING_LIFETIME_SAVED.
// The cache lifetime for home.tpl has already been set
// to 1 hour, and will no longer respect the value of $cache_lifetime.
// The home.tpl cache will still expire after 1 hour.
$smarty->setCacheLifetime(30); // 30 seconds
$smarty->display('home.tpl');
```
## Compile check
By default, every template file and config file that is involved with the cache file
is checked for modification. If any of the files have been modified
since the cache was generated, the cache is immediately regenerated.
This is a computational overhead, so for optimum performance, disable this on a production environment:
```php
<?php
use Smarty\Smarty;
$smarty = new Smarty;
$smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
$smarty->setCompileCheck(Smarty::COMPILECHECK_OFF);
$smarty->display('index.tpl');
```
## Checking if a template is cached
Smarty's `isCached() method can be used to test if a
template has a valid cache or not. If you have a cached template that
requires something like a database fetch, you can use this to skip that
process.
```php
<?php
use Smarty\Smarty;
$smarty = new Smarty;
$smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
if (!$smarty->isCached('index.tpl')) {
// No cache available, do variable assignments here.
$smarty->assign('data', do_expensive_database_calls());
}
$smarty->display('index.tpl');
```
## Nocache-blocks
You can keep parts of a page dynamic (disable caching) with the
[`{nocache}{/nocache}`](../../designers/language-builtin-functions/language-function-nocache.md) block function,
or by using the `nocache` parameter for most template functions.
Let's say the whole page can be cached except for a banner that is
displayed down the side of the page. By using a [`{nocache}{/nocache}`](../../designers/language-builtin-functions/language-function-nocache.md)
block for the banner, you can
keep this element dynamic within the cached content.
## Clearing the cache
You can clear all the cache files with Smarty's `clearAllCache()` method, or individual cache
files with the `clearCache()` method.
```php
<?php
use Smarty\Smarty;
$smarty = new Smarty;
$smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
// clear only cache for index.tpl
$smarty->clearCache('index.tpl');
// clear out all cache files
$smarty->clearAllCache();
// clear out all cache files older than one hour
$smarty->clearAllCache(3600);
// or, clear all expired caches
$smarty->clearAllCache(Smarty::CLEAR_EXPIRED);
```

36
docs/api/caching/custom-storage-layers.md
View File

@@ -0,0 +1,36 @@
# Custom cache storage layers
As an alternative to using the default file-based caching mechanism, you
can specify a custom cache implementation that will be used to read,
write and clear cached files.
With a custom cache implementation you could replace the slow filesystem by a
faster storage engine, centralize the cache to be accessible to multiple
servers.
Smarty requires implementations to extend `\Smarty\Cacheresource\Base`, but encourages you to either extend
`\Smarty\Cacheresource\Custom` or `\Smarty\Cacheresource\KeyValueStore`.
- `\Smarty\Cacheresource\Custom` is a simple API directing all read, write,
clear calls to your implementation. This API allows you to store
wherever and however you deem fit.
- `\Smarty\Cacheresource\KeyValueStore` allows you to turn any
KeyValue-Store (like APC or Memcache) into a full-featured
CacheResource implementation. Everything around deep
cache-groups like "a|b|c" is being handled for you in a way that
guarantees clearing the cache-group "a" will clear all nested groups
as well - even though KeyValue-Stores don't allow this kind of
hierarchy by nature.
Custom CacheResources must be registered on
runtime with `Smarty\Smarty::setCacheResource()`:
```php
<?php
use Smarty\Smarty;
$smarty = new Smarty();
$smarty->setCacheResource(new My_CacheResource_Mysql());
```

0
docs/api/caching/multiple-caches-per-pages.md
View File

137
docs/api/caching/multiple-caches-per-template.md Normal file
View File

@@ -0,0 +1,137 @@
# Multiple caches per template
## Introduction
You can have multiple cache files for a single call to
`display()` or `fetch()`.
Let's say that
a call to `$smarty->display('index.tpl')` may have several different output
contents depending on some condition, and you want separate caches for
each one. You can do this by passing a `$cache_id` as the second
parameter to the function call:
```php
<?php
use Smarty\Smarty;
$smarty = new Smarty;
$smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
$my_cache_id = (int) $_GET['article_id'];
$smarty->display('index.tpl', $my_cache_id);
```
Above, we are passing the variable `$my_cache_id` to
[`display()`](#api.display) as the `$cache_id`. For each unique value of
`$my_cache_id`, a separate cache will be generated for `index.tpl`. In
this example, `article_id` was passed in the URL and is used as the
`$cache_id`.
> **Note**
>
> Be very cautious when passing values from a client (web browser) into
> Smarty or any PHP application. Although the above example of using the
> article_id from the URL looks handy, it could have bad consequences.
> The `$cache_id` is used to create a directory on the file system, so
> if the user decided to write a script that sends random article_id's at a rapid pace,
> this could possibly cause problems at the server level.
> Be sure to sanitize any data passed in before using it. In this example, you might want to check if
> the article_id is a valid ID in the database.
Be sure to pass the same `$cache_id` as the second parameter to
`isCached()` and `clearCache()`.
```php
<?php
use Smarty\Smarty;
$smarty = new Smarty;
$smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
$my_cache_id = (int) $_GET['article_id'];
if (!$smarty->isCached('index.tpl', $my_cache_id)) {
// ...
}
$smarty->display('index.tpl', $my_cache_id);
```
## Clearing specific caches
You can clear all caches for a particular `$cache_id` by passing NULL as
the first parameter to `clearCache()`.
```php
<?php
use Smarty\Smarty;
$smarty = new Smarty;
$smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
// clear all caches with "sports" as the $cache_id
$smarty->clearCache(null, 'sports');
$smarty->display('index.tpl', 'sports');
```
In this manner, you can "group" your caches together by giving them the
same `$cache_id`.
## Advanced cache grouping
You can do more elaborate grouping by setting up `$cache_id` groups.
This is accomplished by separating each sub-group with a vertical bar
`|` in the `$cache_id` value. You can have as many sub-groups as you
like.
- You can think of cache groups like a directory hierarchy. For
instance, a cache group of `'a|b|c'` could be thought of as the
directory structure `'/a/b/c/'`.
- `clearCache(null, 'a|b|c')` would be like removing the files
`'/a/b/c/*'`. `clearCache(null, 'a|b')` would be like removing the
files `'/a/b/*'`.
- If you specify a template name such as
`clearCache('foo.tpl', 'a|b|c')` then Smarty will attempt to remove
`'/a/b/c/foo.tpl'`.
- You CANNOT remove a specified template name under multiple cache
groups such as `'/a/b/*/foo.tpl'`, the cache grouping works
left-to-right ONLY. You will need to group your templates under a
single cache group hierarchy to be able to clear them as a group.
Cache grouping should not be confused with your template directory
hierarchy, the cache grouping has no knowledge of how your templates are
structured. So for example, if you have a template structure like
`themes/blue/index.tpl` and you want to be able to clear all the cache
files for the "blue" theme, you will need to create a cache group
structure that mimics your template file structure, such as
`display('themes/blue/index.tpl', 'themes|blue')`, then clear them with
`clearCache(null, 'themes|blue')`.
```php
<?php
use Smarty\Smarty;
$smarty = new Smarty;
$smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
// clear all caches with 'sports|basketball' as the first two cache_id groups
$smarty->clearCache(null, 'sports|basketball');
// clear all caches with "sports" as the first cache_id group. This would
// include "sports|basketball", or "sports|(anything)|(anything)|(anything)|..."
$smarty->clearCache(null, 'sports');
// clear the foo.tpl cache file with "sports|basketball" as the cache_id
$smarty->clearCache('foo.tpl', 'sports|basketball');
$smarty->display('index.tpl', 'sports|basketball');
```

2
docs/designers/language-builtin-functions/language-function-nocache.md
View File

@@ -17,4 +17,4 @@ Today's date is
The above code will output the current date on a cached page.
See also the [caching section](../../programmers/caching.md).
See also the [caching section](../../api/caching/basics.md).

9
docs/getting-started.md
View File

@@ -33,13 +33,8 @@ $smarty = new Smarty();
Now that the library files are in place, it's time to set up the Smarty
directories for your application.
Smarty requires four directories which are by default named
[`templates`](./programmers/api-variables/variable-template-dir.md),
[`configs`](./programmers/api-variables/variable-config-dir.md),
[`templates_c`](./programmers/api-variables/variable-compile-dir.md)
and
[`cache`](./programmers/api-variables/variable-cache-dir.md)
relative to the current working directory.
Smarty requires four directories which are by default named `templates`, `configs`, `templates_c` and `cache`
relative to the current working directory.
The defaults can be changed as follows:

24
docs/programmers/caching.md
View File

@@ -1,24 +0,0 @@
Caching
=======
Caching is used to speed up a call to [`display()`](./api-functions/api-display.md) or
[`fetch()`](./api-functions/api-fetch.md) by saving its output to a file. If a cached
version of the call is available, that is displayed instead of
regenerating the output. Caching can speed things up tremendously,
especially templates with longer computation times. Since the output of
[`display()`](./api-functions/api-display.md) or [`fetch()`](./api-functions/api-fetch.md) is cached, one
cache file could conceivably be made up of several template files,
config files, etc.
Since templates are dynamic, it is important to be careful what you are
caching and for how long. For instance, if you are displaying the front
page of your website that does not change its content very often, it
might work well to cache this page for an hour or more. On the other
hand, if you are displaying a page with a timetable containing new
information by the minute, it would not make sense to cache this page.
## Table of contents
- [Setting Up Caching](./caching/caching-setting-up.md)
- [Multiple Caches Per Page](./caching/caching-multiple-caches.md)
- [Controlling Cacheability of Output](./caching/caching-groups.md)
- [Custom Cache Implementation](./caching/caching-custom.md)

128
docs/programmers/caching/caching-cacheable.md
View File

@@ -1,128 +0,0 @@
Controlling Cacheability of Output {#caching.cacheable}
==================================
If caching is enabled normally the whole final output of the page gets
cached. However Smarty3 offers several options how to exclude sections
of your output from caching.
> **Note**
>
> Be sure any variables used within a non-cached section are also
> assigned from PHP when the page is loaded from the cache.
Cacheability of Template Section {#cacheability.sections}
--------------------------------
A larger section of your template can easily excluded from caching by
using the [`{nocache}`](#language.function.nocache) and
[`{/nocache}`](#language.function.nocache) tags.
Today's date is
{nocache}
{$smarty.now|date_format}
{/nocache}
The above code will output the current date on a cached page.
Cacheability of Tags {#cacheability.tags}
--------------------
Caching for an individual tag can be disabled by adding the \"nocache\"
option flag to the tag.
Today's date is
{$smarty.now|date_format nocache}
Cacheability of Variables {#cacheability.variables}
-------------------------
You can [`assign()`](#api.assign) variables as not cachable. Any tag
which uses such variable will be automatically executed in nocache mode.
> **Note**
>
> If a tag is executed in nocache mode you must make sure that all other
> variables used by that tag are also assigned from PHP when the page is
> loaded from the cache.
> **Note**
>
> The nocache status of an assigned variable will effect the compiled
> template code. If you change the status you must manually delete
> existing compiled and cached template files to force a recompile.
// assign $foo as nocahe variable
$smarty->assign('foo',time(),true);
Dynamic time value is {$foo}
Cacheability of Plugins {#cacheability.plugins}
-----------------------
The cacheability of plugins can be declared when registering them. The
third parameter to [`registerPlugin()`](#api.register.plugin) is called
`$cacheable` and defaults to TRUE.
When registering a plugin with `$cacheable=false` the plugin is called
everytime the page is displayed, even if the page comes from the cache.
> **Note**
>
> The `$cacheable` status will affect the compiled template code. If you
> change the status you must manually delete existing compiled and
> cached template files to force a recompile.
Example `index.php`:
<?php
$smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
function smarty_block_dynamic($param, $content, $smarty) {
return $content;
}
$smarty->registerPlugin('block','dynamic', 'smarty_block_dynamic', false);
$smarty->display('index.tpl');
?>
where `index.tpl` is:
Page created: {'0'|date_format:'%D %H:%M:%S'}
{dynamic}
Now is: {'0'|date_format:'%D %H:%M:%S'}
... do other stuff ...
{/dynamic}
When reloading the page you will notice that both dates differ. One is
"dynamic" one is "static". You can do everything between
`{dynamic}...{/dynamic}` and be sure it will not be cached like the rest
of the page.
> **Note**
>
> The above example shall just demonstrate how a dynamic block plugins
> works. See
> [`Cacheability of Template Section`](#cacheability.sections) on how to
> disable caching of a template section by the built-in
> [`{nocache}`](#language.function.nocache) and
> [`{/nocache}`](#language.function.nocache) tags.

296
docs/programmers/caching/caching-custom.md
View File

@@ -1,296 +0,0 @@
Custom Cache Implementation {#caching.custom}
===========================
As an alternative to using the default file-based caching mechanism, you
can specify a custom cache implementation that will be used to read,
write and clear cached files.
> **Note**
>
> In Smarty2 this used to be a callback function called
> `$cache_handler_func`. Smarty3 replaced this callback by the
> `Smarty_CacheResource` module.
With a custom cache implementation you\'re likely trying to achieve at
least one of the following goals: replace the slow filesystem by a
faster storage engine, centralize the cache to be accessible to multiple
servers.
Smarty allows CacheResource implementations to use one of the APIs
`\Smarty\Cacheresource\Custom` or `\Smarty\Cacheresource\KeyValueStore`.
`\Smarty\Cacheresource\Custom` is a simple API directing all read, write,
clear calls to your implementation. This API allows you to store
wherever and however you deem fit. The
`\Smarty\Cacheresource\KeyValueStore` API allows you to turn any \"dumb\"
KeyValue-Store (like APC, Memcache, ...) into a full-featured
CacheResource implementation. That is, everything around deep
cache-groups like \"a\|b\|c\" is being handled for you in way that
allows clearing the cache-group \"a\" and all nested groups are cleared
as well - even though KeyValue-Stores don\'t allow this kind of
hierarchy by nature.
Custom CacheResources may be put in a file `cacheresource.foobarxyz.php`
within your [`$plugins_dir`](#variable.plugins.dir), or registered on
runtime with [`registerCacheResource()`](#api.register.cacheresource).
In either case you need to set [`$caching_type`](#variable.caching.type)
to invoke your custom CacheResource implementation.
<?php
use Smarty\Smarty;
$smarty = new Smarty();
$smarty->caching_type = 'mysql';
/**
* MySQL CacheResource
*
* CacheResource Implementation based on the Custom API to use
* MySQL as the storage resource for Smarty's output caching.
*
* Table definition:
* <pre>CREATE TABLE IF NOT EXISTS `output_cache` (
* `id` CHAR(40) NOT NULL COMMENT 'sha1 hash',
* `name` VARCHAR(250) NOT NULL,
* `cache_id` VARCHAR(250) NULL DEFAULT NULL,
* `compile_id` VARCHAR(250) NULL DEFAULT NULL,
* `modified` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
* `content` LONGTEXT NOT NULL,
* PRIMARY KEY (`id`),
* INDEX(`name`),
* INDEX(`cache_id`),
* INDEX(`compile_id`),
* INDEX(`modified`)
* ) ENGINE = InnoDB;</pre>
*
* @author Rodney Rehm
*/
class My_CacheResource_Mysql extends \Smarty\Cacheresource\Custom {
// PDO instance
protected $db;
protected $fetch;
protected $fetchTimestamp;
protected $save;
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, content FROM output_cache WHERE id = :id');
$this->fetchTimestamp = $this->db->prepare('SELECT modified FROM output_cache WHERE id = :id');
$this->save = $this->db->prepare('REPLACE INTO output_cache (id, name, cache_id, compile_id, content)
VALUES (:id, :name, :cache_id, :compile_id, :content)');
}
/**
* fetch cached content and its modification time from data source
*
* @param string $id unique cache content identifier
* @param string $name template name
* @param string $cache_id cache id
* @param string $compile_id compile id
* @param string $content cached content
* @param integer $mtime cache modification timestamp (epoch)
* @return void
*/
protected function fetch($id, $name, $cache_id, $compile_id, &$content, &$mtime)
{
$this->fetch->execute(array('id' => $id));
$row = $this->fetch->fetch();
$this->fetch->closeCursor();
if ($row) {
$content = $row['content'];
$mtime = strtotime($row['modified']);
} else {
$content = null;
$mtime = null;
}
}
/**
* Fetch cached content's modification timestamp from data source
*
* @note implementing this method is optional. Only implement it if modification times can be accessed faster than loading the complete cached content.
* @param string $id unique cache content identifier
* @param string $name template name
* @param string $cache_id cache id
* @param string $compile_id compile id
* @return integer|boolean timestamp (epoch) the template was modified, or false if not found
*/
protected function fetchTimestamp($id, $name, $cache_id, $compile_id)
{
$this->fetchTimestamp->execute(array('id' => $id));
$mtime = strtotime($this->fetchTimestamp->fetchColumn());
$this->fetchTimestamp->closeCursor();
return $mtime;
}
/**
* Save content to cache
*
* @param string $id unique cache content identifier
* @param string $name template name
* @param string $cache_id cache id
* @param string $compile_id compile id
* @param integer|null $exp_time seconds till expiration time in seconds or null
* @param string $content content to cache
* @return boolean success
*/
protected function save($id, $name, $cache_id, $compile_id, $exp_time, $content)
{
$this->save->execute(array(
'id' => $id,
'name' => $name,
'cache_id' => $cache_id,
'compile_id' => $compile_id,
'content' => $content,
));
return !!$this->save->rowCount();
}
/**
* Delete content from cache
*
* @param string $name template name
* @param string $cache_id cache id
* @param string $compile_id compile id
* @param integer|null $exp_time seconds till expiration or null
* @return integer number of deleted caches
*/
protected function delete($name, $cache_id, $compile_id, $exp_time)
{
// delete the whole cache
if ($name === null && $cache_id === null && $compile_id === null && $exp_time === null) {
// returning the number of deleted caches would require a second query to count them
$query = $this->db->query('TRUNCATE TABLE output_cache');
return -1;
}
// build the filter
$where = array();
// equal test name
if ($name !== null) {
$where[] = 'name = ' . $this->db->quote($name);
}
// equal test compile_id
if ($compile_id !== null) {
$where[] = 'compile_id = ' . $this->db->quote($compile_id);
}
// range test expiration time
if ($exp_time !== null) {
$where[] = 'modified < DATE_SUB(NOW(), INTERVAL ' . intval($exp_time) . ' SECOND)';
}
// equal test cache_id and match sub-groups
if ($cache_id !== null) {
$where[] = '(cache_id = '. $this->db->quote($cache_id)
. ' OR cache_id LIKE '. $this->db->quote($cache_id .'|%') .')';
}
// run delete query
$query = $this->db->query('DELETE FROM output_cache WHERE ' . join(' AND ', $where));
return $query->rowCount();
}
}
<?php
use Smarty\Smarty;
$smarty = new Smarty();
$smarty->caching_type = 'memcache';
/**
* Memcache CacheResource
*
* CacheResource Implementation based on the KeyValueStore API to use
* memcache as the storage resource for Smarty's output caching.
*
* Note that memcache has a limitation of 256 characters per cache-key.
* To avoid complications all cache-keys are translated to a sha1 hash.
*
* @author Rodney Rehm
*/
class My_CacheResource_Memcache extends \Smarty\Cacheresource\KeyValueStore {
/**
* memcache instance
* @var Memcache
*/
protected $memcache = null;
public function __construct()
{
$this->memcache = new Memcache();
$this->memcache->addServer( '127.0.0.1', 11211 );
}
/**
* Read values for a set of keys from cache
*
* @param array $keys list of keys to fetch
* @return array list of values with the given keys used as indexes
* @return boolean true on success, false on failure
*/
protected function read(array $keys)
{
$_keys = $lookup = array();
foreach ($keys as $k) {
$_k = sha1($k);
$_keys[] = $_k;
$lookup[$_k] = $k;
}
$_res = array();
$res = $this->memcache->get($_keys);
foreach ($res as $k => $v) {
$_res[$lookup[$k]] = $v;
}
return $_res;
}
/**
* Save values for a set of keys to cache
*
* @param array $keys list of values to save
* @param int $expire expiration time
* @return boolean true on success, false on failure
*/
protected function write(array $keys, $expire=null)
{
foreach ($keys as $k => $v) {
$k = sha1($k);
$this->memcache->set($k, $v, 0, $expire);
}
return true;
}
/**
* Remove values from cache
*
* @param array $keys list of keys to delete
* @return boolean true on success, false on failure
*/
protected function delete(array $keys)
{
foreach ($keys as $k) {
$k = sha1($k);
$this->memcache->delete($k);
}
return true;
}
/**
* Remove *all* values from cache
*
* @return boolean true on success, false on failure
*/
protected function purge()
{
return $this->memcache->flush();
}
}

60
docs/programmers/caching/caching-groups.md
View File

@@ -1,60 +0,0 @@
Cache Groups {#caching.groups}
============
You can do more elaborate grouping by setting up `$cache_id` groups.
This is accomplished by separating each sub-group with a vertical bar
`|` in the `$cache_id` value. You can have as many sub-groups as you
like.
- You can think of cache groups like a directory hierarchy. For
instance, a cache group of `'a|b|c'` could be thought of as the
directory structure `'/a/b/c/'`.
- `clearCache(null,'a|b|c')` would be like removing the files
`'/a/b/c/*'`. `clearCache(null,'a|b')` would be like removing the
files `'/a/b/*'`.
- If you specify a [`$compile_id`](#variable.compile.id) such as
`clearCache(null,'a|b','foo')` it is treated as an appended cache
group `'/a/b/c/foo/'`.
- If you specify a template name such as
`clearCache('foo.tpl','a|b|c')` then Smarty will attempt to remove
`'/a/b/c/foo.tpl'`.
- You CANNOT remove a specified template name under multiple cache
groups such as `'/a/b/*/foo.tpl'`, the cache grouping works
left-to-right ONLY. You will need to group your templates under a
single cache group hierarchy to be able to clear them as a group.
Cache grouping should not be confused with your template directory
hierarchy, the cache grouping has no knowledge of how your templates are
structured. So for example, if you have a template structure like
`themes/blue/index.tpl` and you want to be able to clear all the cache
files for the "blue" theme, you will need to create a cache group
structure that mimics your template file structure, such as
`display('themes/blue/index.tpl','themes|blue')`, then clear them with
`clearCache(null,'themes|blue')`.
<?php
use Smarty\Smarty;
$smarty = new Smarty;
$smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
// clear all caches with 'sports|basketball' as the first two cache_id groups
$smarty->clearCache(null,'sports|basketball');
// clear all caches with "sports" as the first cache_id group. This would
// include "sports|basketball", or "sports|(anything)|(anything)|(anything)|..."
$smarty->clearCache(null,'sports');
// clear the foo.tpl cache file with "sports|basketball" as the cache_id
$smarty->clearCache('foo.tpl','sports|basketball');
$smarty->display('index.tpl','sports|basketball');
?>

87
docs/programmers/caching/caching-multiple-caches.md
View File

@@ -1,87 +0,0 @@
Multiple Caches Per Page {#caching.multiple.caches}
========================
You can have multiple cache files for a single call to
[`display()`](#api.display) or [`fetch()`](#api.fetch). Let\'s say that
a call to `display('index.tpl')` may have several different output
contents depending on some condition, and you want separate caches for
each one. You can do this by passing a `$cache_id` as the second
parameter to the function call.
<?php
use Smarty\Smarty;
$smarty = new Smarty;
$smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
$my_cache_id = $_GET['article_id'];
$smarty->display('index.tpl', $my_cache_id);
?>
Above, we are passing the variable `$my_cache_id` to
[`display()`](#api.display) as the `$cache_id`. For each unique value of
`$my_cache_id`, a separate cache will be generated for `index.tpl`. In
this example, `article_id` was passed in the URL and is used as the
`$cache_id`.
> **Note**
>
> Be very cautious when passing values from a client (web browser) into
> Smarty or any PHP application. Although the above example of using the
> article\_id from the URL looks handy, it could have bad consequences.
> The `$cache_id` is used to create a directory on the file system, so
> if the user decided to pass an extremely large value for article\_id,
> or write a script that sends random article\_id\'s at a rapid pace,
> this could possibly cause problems at the server level. Be sure to
> sanitize any data passed in before using it. In this instance, maybe
> you know the article\_id has a length of ten characters and is made up
> of alpha-numerics only, and must be a valid article\_id in the
> database. Check for this!
Be sure to pass the same `$cache_id` as the second parameter to
[`isCached()`](#api.is.cached) and [`clearCache()`](#api.clear.cache).
<?php
use Smarty\Smarty;
$smarty = new Smarty;
$smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
$my_cache_id = $_GET['article_id'];
if(!$smarty->isCached('index.tpl',$my_cache_id)) {
// No cache available, do variable assignments here.
$contents = get_database_contents();
$smarty->assign($contents);
}
$smarty->display('index.tpl',$my_cache_id);
?>
You can clear all caches for a particular `$cache_id` by passing NULL as
the first parameter to [`clearCache()`](#api.clear.cache).
<?php
use Smarty\Smarty;
$smarty = new Smarty;
$smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
// clear all caches with "sports" as the $cache_id
$smarty->clearCache(null,'sports');
$smarty->display('index.tpl','sports');
?>
In this manner, you can "group" your caches together by giving them the
same `$cache_id`.

150
docs/programmers/caching/caching-setting-up.md
View File

@@ -1,150 +0,0 @@
Setting Up Caching {#caching.setting.up}
==================
The first thing to do is enable caching by setting
[`$caching`](#variable.caching) to one of
`\Smarty\Smarty::CACHING_LIFETIME_CURRENT` or `Smarty::CACHING_LIFETIME_SAVED`.
<?php
use Smarty\Smarty;
$smarty = new Smarty;
// uses the value of $smarty->cacheLifetime() to determine
// the number of seconds a cache is good for
$smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
$smarty->display('index.tpl');
?>
With caching enabled, the function call to `display('index.tpl')` will
render the template as usual, but also saves a copy of its output to a
file (a cached copy) in the [`$cache_dir`](#variable.cache.dir). On the
next call to `display('index.tpl')`, the cached copy will be used
instead of rendering the template again.
> **Note**
>
> The files in the [`$cache_dir`](#variable.cache.dir) are named similar
> to the template name. Although they end in the `.php` extension, they
> are not intended to be directly executable. Do not edit these files!
Each cached page has a limited lifetime determined by
[`$cache_lifetime`](#variable.cache.lifetime). The default value is 3600
seconds, or one hour. After that time expires, the cache is regenerated.
It is possible to give individual caches their own expiration time by
setting [`$caching`](#variable.caching) to
`\Smarty\Smarty::CACHING_LIFETIME_SAVED`. See
[`$cache_lifetime`](#variable.cache.lifetime) for more details.
<?php
use Smarty\Smarty;
$smarty = new Smarty;
// retain current cache lifetime for each specific display call
$smarty->setCaching(Smarty::CACHING_LIFETIME_SAVED);
// set the cache_lifetime for index.tpl to 5 minutes
$smarty->setCacheLifetime(300);
$smarty->display('index.tpl');
// set the cache_lifetime for home.tpl to 1 hour
$smarty->setCacheLifetime(3600);
$smarty->display('home.tpl');
// NOTE: the following $cache_lifetime setting will not work when $caching
// is set to Smarty::CACHING_LIFETIME_SAVED.
// The cache lifetime for home.tpl has already been set
// to 1 hour, and will no longer respect the value of $cache_lifetime.
// The home.tpl cache will still expire after 1 hour.
$smarty->setCacheLifetime(30); // 30 seconds
$smarty->display('home.tpl');
?>
If [`$compile_check`](#variable.compile.check) is enabled (default),
every template file and config file that is involved with the cache file
is checked for modification. If any of the files have been modified
since the cache was generated, the cache is immediately regenerated.
This is a computational overhead, so for optimum performance set
[`$compile_check`](#variable.compile.check) to FALSE.
<?php
use Smarty\Smarty;
$smarty = new Smarty;
$smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
$smarty->setCompileCheck(false);
$smarty->display('index.tpl');
?>
If [`$force_compile`](#variable.force.compile) is enabled, the cache
files will always be regenerated. This effectively disables caching,
however this also seriously degrades performance.
[`$force_compile`](#variable.force.compile) is meant to be used for
[debugging](#chapter.debugging.console) purposes. The appropriate way to
disable caching is to set [`$caching`](#variable.caching) to
\Smarty\Smarty::CACHING\_OFF.
The [`isCached()`](#api.is.cached) function can be used to test if a
template has a valid cache or not. If you have a cached template that
requires something like a database fetch, you can use this to skip that
process.
<?php
use Smarty\Smarty;
$smarty = new Smarty;
$smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
if(!$smarty->isCached('index.tpl')) {
// No cache available, do variable assignments here.
$contents = get_database_contents();
$smarty->assign($contents);
}
$smarty->display('index.tpl');
?>
You can keep parts of a page dynamic (disable caching) with the
[`{nocache}{/nocache}`](#language.function.nocache) block function, or by using the
`nocache` parameter for most template functions.
Let\'s say the whole page can be cached except for a banner that is
displayed down the side of the page. By using a [`{nocache}{/nocache}`](#language.function.nocache)
block for the banner, you can
keep this element dynamic within the cached content.
You can clear all the cache files with the
[`clearAllCache()`](#api.clear.all.cache) function, or individual cache
files [and groups](#caching.groups) with the
[`clearCache()`](#api.clear.cache) function.
<?php
use Smarty\Smarty;
$smarty = new Smarty;
$smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
// clear only cache for index.tpl
$smarty->clearCache('index.tpl');
// clear out all cache files
$smarty->clearAllCache();
$smarty->display('index.tpl');
?>

2
mkdocs.yml
View File

@@ -130,7 +130,7 @@ nav:
- 'Template resources': 'api/resources.md'
- 'Caching':
- 'Basics': 'api/caching/basics.md'
- 'Multiple caches per page': 'api/caching/multiple-caches-per-pages.md'
- 'Multiple caches per template': 'api/caching/multiple-caches-per-template.md'
- 'Custom cache storage layers': 'api/caching/custom-storage-layers.md'
- 'Extending Smarty':
- 'Introduction': 'api/extending/introduction.md'