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

make use_sub_dirs go back to crc32 for subdir separation

Browse Source
This commit is contained in:
mohrt
2002-07-03 20:08:33 +00:00
parent 50652cd18f
commit 32ec082214
5 changed files with 434 additions and 159 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
Smarty.class.php
View File

@@ -1442,8 +1442,14 @@ function _run_insert_handler($args)
if(isset($auto_source)) { if(isset($auto_source)) {
// make source name safe for filename // make source name safe for filename
$auto_source = str_replace($_dir_sep_enc,'^',urlencode($auto_source)); if($this->use_sub_dirs) {
$res .= $auto_source . '.php'; $_filename = basename($auto_source);
$_crc32 = crc32($auto_source) . $_dir_sep;
$_crc32 = substr($_crc32,0,3) . $_dir_sep . $_crc32;
$res .= $_crc32 . $_filename . '.php';
} else {
$res .= str_replace($_dir_sep_enc,'^',urlencode($auto_source));
}
} }
return $res; return $res;

60
docs/designers.sgml
View File

@@ -842,9 +842,6 @@ two convicts evade noose, jury hung.</programlisting>
A regular expression search and replace on a variable. Use the A regular expression search and replace on a variable. Use the
syntax for preg_replace() from the PHP manual. syntax for preg_replace() from the PHP manual.
</para> </para>
<para>
NOTE: This function was added to Smarty 1.4.3.
</para>
<example> <example>
<title>regex_replace</title> <title>regex_replace</title>
<programlisting> <programlisting>
@@ -1254,15 +1251,16 @@ s m o k e r s a r e p. . .</programlisting>
template from the special variable $smarty.capture.foo where foo is template from the special variable $smarty.capture.foo where foo is
the value passed in the name attribute. If you do not supply a name the value passed in the name attribute. If you do not supply a name
attribute, then "default" will be used. All {capture} commands must attribute, then "default" will be used. All {capture} commands must
be paired with {/capture}. You can nest capture commands. capture be paired with {/capture}. You can nest capture commands.
was added to Smarty 1.4.0. The "name" attribute was added to Smarty
1.4.5.
</para> </para>
<note>
<title>Technical Note</title>
<para> <para>
NOTE: Smarty 1.4.0 - 1.4.4 placed the captured content into the Smarty 1.4.0 - 1.4.4 placed the captured content into the
variable named $return. As of 1.4.5, this behavior was changed to use variable named $return. As of 1.4.5, this behavior was changed to use
the name attribute, so update your templates accordingly. the name attribute, so update your templates accordingly.
</para> </para>
</note>
<caution> <caution>
<para> <para>
Be careful when capturing <command>insert</command> output. If Be careful when capturing <command>insert</command> output. If
@@ -1334,7 +1332,7 @@ s m o k e r s a r e p. . .</programlisting>
context. parent means variables are loaded into both context. parent means variables are loaded into both
the local context and the parent template that called the local context and the parent template that called
it. global means variables are available to all it. global means variables are available to all
templates. NOTE: This was added to Smarty 1.4.3. templates.
</entry> </entry>
</row> </row>
<row> <row>
@@ -1575,7 +1573,7 @@ cell: 760-1234&lt;br&gt;</programlisting>
You can optionally pass the <emphasis>assign</emphasis> attribute, You can optionally pass the <emphasis>assign</emphasis> attribute,
which will specify a template variable name that the output of which will specify a template variable name that the output of
<emphasis>include</emphasis> will be assigned to instead of <emphasis>include</emphasis> will be assigned to instead of
displayed. This was added to Smarty 1.5.0. displayed.
</para> </para>
<example> <example>
<title>function include</title> <title>function include</title>
@@ -1698,9 +1696,6 @@ cell: 760-1234&lt;br&gt;</programlisting>
<emphasis>include_php</emphasis> will be assigned to instead of <emphasis>include_php</emphasis> will be assigned to instead of
displayed. displayed.
</para> </para>
<para>
include_php was added to Smarty 1.5.0.
</para>
<example> <example>
<title>function include_php</title> <title>function include_php</title>
<programlisting> <programlisting>
@@ -1784,7 +1779,7 @@ index.tpl
<para> <para>
Insert tags work much like include tags, except that insert tags Insert tags work much like include tags, except that insert tags
are not cached when you have template <link are not cached when you have template <link
linkend="features.caching">caching</link> enabled. They will be linkend="caching">caching</link> enabled. They will be
executed on every invocation of the template. executed on every invocation of the template.
</para> </para>
<para> <para>
@@ -1820,7 +1815,7 @@ index.tpl
If you supply the "assign" attribute, the output of the insert tag If you supply the "assign" attribute, the output of the insert tag
will be assigned to this template variable instead of being output will be assigned to this template variable instead of being output
to the template. NOTE: assigning the output to a template variable to the template. NOTE: assigning the output to a template variable
isn't too useful with caching enabled. (added to Smarty 1.5.0) isn't too useful with caching enabled.
</para> </para>
<para> <para>
If you supply the "script" attribute, this php script will be If you supply the "script" attribute, this php script will be
@@ -1828,19 +1823,18 @@ index.tpl
is the case where the insert function may not exist yet, and a php is the case where the insert function may not exist yet, and a php
script must be included first to make it work. The path can be script must be included first to make it work. The path can be
either absolute, or relative to $trusted_dir. When security is either absolute, or relative to $trusted_dir. When security is
enabled, the script must reside in $trusted_dir. (added to Smarty enabled, the script must reside in $trusted_dir.
1.5.2)
</para> </para>
<para> <para>
The Smarty object is passed as the second argument. This way you The Smarty object is passed as the second argument. This way you
can reference and modify information in the Smarty object from can reference and modify information in the Smarty object from
within the insert function. (added in 1.4.5) within the insert function.
</para> </para>
<note> <note>
<title>Technical Note</title> <title>Technical Note</title>
<para> <para>
It is possible to have portions of the template not It is possible to have portions of the template not
cached. If you have <link linkend="features.caching">caching</link> cached. If you have <link linkend="caching">caching</link>
turned on, insert tags will not be cached. They will run turned on, insert tags will not be cached. They will run
dynamically every time the page is created, even within cached dynamically every time the page is created, even within cached
pages. This works good for things like banners, polls, live pages. This works good for things like banners, polls, live
@@ -1986,8 +1980,7 @@ OUTPUT:
php tags allow php to be embedded directly into the template. They php tags allow php to be embedded directly into the template. They
will not be escaped, regardless of the <link will not be escaped, regardless of the <link
linkend="variable.php.handling">$php_handling</link> setting. This linkend="variable.php.handling">$php_handling</link> setting. This
is for advanced users only, not normally needed. This was added to is for advanced users only, not normally needed.
1.4.0.
</para> </para>
<example> <example>
<title>php tags</title> <title>php tags</title>
@@ -2044,7 +2037,7 @@ OUTPUT:
seven values in the loop array and start is -2, the seven values in the loop array and start is -2, the
start index is 5. Invalid values (values outside of the start index is 5. Invalid values (values outside of the
length of the loop array) are automatically truncated length of the loop array) are automatically truncated
to the closest valid value. (Added to Smarty 1.4.4.)</entry> to the closest valid value.</entry>
</row> </row>
<row> <row>
<entry>step</entry> <entry>step</entry>
@@ -2054,7 +2047,7 @@ OUTPUT:
<entry>The step value that will be used to traverse the <entry>The step value that will be used to traverse the
loop array. For example, step=2 will loop on index loop array. For example, step=2 will loop on index
0,2,4, etc. If step is negative, it will step through 0,2,4, etc. If step is negative, it will step through
the array backwards. (Added to Smarty 1.4.4.)</entry> the array backwards.</entry>
</row> </row>
<row> <row>
<entry>max</entry> <entry>max</entry>
@@ -2062,7 +2055,7 @@ OUTPUT:
<entry>No</entry> <entry>No</entry>
<entry><emphasis>1</emphasis></entry> <entry><emphasis>1</emphasis></entry>
<entry>Sets the maximum number of times the section <entry>Sets the maximum number of times the section
will loop. (Added to Smarty 1.4.4.)</entry> will loop.</entry>
</row> </row>
<row> <row>
<entry>show</entry> <entry>show</entry>
@@ -2342,9 +2335,6 @@ e-mail: jane@mydomain.com&lt;p&gt;</programlisting>
NOTE: This is not affected by the section properties start, step and NOTE: This is not affected by the section properties start, step and
max, unlike the index property. max, unlike the index property.
</para> </para>
<para>
This was added to Smarty 1.4.4.
</para>
<example> <example>
<title>section property iteration</title> <title>section property iteration</title>
<programlisting> <programlisting>
@@ -2525,9 +2515,6 @@ e-mail: jane@mydomain.com&lt;p&gt;</programlisting>
total is used to display the number of iterations that this section total is used to display the number of iterations that this section
will loop. This can be used inside or after the section. will loop. This can be used inside or after the section.
</para> </para>
<para>
This was added to Smarty 1.4.4.
</para>
<example> <example>
<title>section property total</title> <title>section property total</title>
<programlisting> <programlisting>
@@ -2641,9 +2628,6 @@ OUTPUT:
assign is used for assigning template variables during the execution assign is used for assigning template variables during the execution
of the template. of the template.
</para> </para>
<para>
NOTE: This was added to Smarty 1.4.3.
</para>
<example> <example>
<title>assign</title> <title>assign</title>
<programlisting> <programlisting>
@@ -2727,12 +2711,12 @@ The value of $name is Bob.</programlisting>
and the direction of the count, as well as determine whether or not and the direction of the count, as well as determine whether or not
to print the value. You can run multiple counters concurrently by to print the value. You can run multiple counters concurrently by
supplying a unique id for each one. If you do not supply a name, the supplying a unique id for each one. If you do not supply a name, the
name 'default' will be used. counter was added to Smarty 1.4.0. name 'default' will be used.
</para> </para>
<para> <para>
If you supply the special "assign" attribute, the output of the If you supply the special "assign" attribute, the output of the
counter function will be assigned to this template variable instead of counter function will be assigned to this template variable instead of
being output to the template. (new in Smarty 1.5.0) being output to the template.
</para> </para>
<example> <example>
<title>counter</title> <title>counter</title>
@@ -3106,8 +3090,7 @@ You must supply a &lt;b&gt;state&lt;/b&gt;.
{* an alternative method is to pass the values & output as an associative array into {* an alternative method is to pass the values & output as an associative array into
options. $customer_options is an associative array in this example. This options. $customer_options is an associative array in this example. *}
functionality was added to Smarty 1.3.0 *}
&lt;select name=customer_id&gt; &lt;select name=customer_id&gt;
{html_options options=$customer_options selected=$customer_id} {html_options options=$customer_options selected=$customer_id}
@@ -3316,11 +3299,6 @@ OUTPUT:
html_select_date is a custom function that creates date dropdowns html_select_date is a custom function that creates date dropdowns
for you. It can display any or all of year, month, and day. for you. It can display any or all of year, month, and day.
</para> </para>
<para>
NOTE: reverse_years, field_array, day_size, month_size, year_size,
all_extra, day_extra, month_extra, year_extra, field_order,
field_separator added in Smarty 1.4.5.
</para>
<example> <example>
<title>html_select_date</title> <title>html_select_date</title>
<programlisting> <programlisting>

170
docs/getting-started.sgml
View File

@@ -1,18 +1,45 @@
<part id="getting.started"> <part id="getting.started">
<title>Getting Started</title> <title>Getting Started</title>
<chapter id="overview"> <chapter id="what.is.smarty">
<title>Overview</title>
<sect1 id="what.is.smarty">
<title>What is Smarty?</title> <title>What is Smarty?</title>
<para> <para>
Smarty is a template engine for PHP. One of the unique aspects about Smarty is a template engine for PHP. More specifically, it facilitates a
Smarty is that it compiles the template files into native PHP scripts managable way to separate application logic and content from its
upon the first invocation. After that, it just executes the compiled presentation. This is best described in a situation where the application
PHP scripts. Therefore, there is no costly template file parsing for programmer and the template designer play different roles, or in most cases
each request, and each template can take full advantage of PHP compiler are not the same person. For example, let's say you are creating a web page
cache solutions such as Zend Cache (http://www.zend.com) or PHP that is displaying a newspaper article. The article headline, tagline,
Accelerator (http://www.php-accelerator.co.uk). author and body are content elements, they contain no information about how
they will be presented. They are passed into Smarty by the application,
then the template designer edits the templates and uses a combination of
HTML tags and template tags to format the presentation of these elements
(HTML tables, background colors, font sizes, style sheets, etc.) One day
the programmer needs to change the way the article content is retrieved (a
change in application logic.) This change does not affect the template
designer, the content will still arrive in the template exactly the same.
Likewise, if the template designer wants to completely redesign the
templates, this requires no changes to the application logic. Therefore,
the programmer can make changes to the application logic without the need
to restructure templates, and the template designer can make changes to
templates without breaking application logic.
</para>
<para>
Now for a short word on what Smarty does NOT do. Smarty does not attempt to
completely separate logic from the templates. There is no problem with
logic in your templates under the condition that this logic is strictly for
presentation. A word of advice: keep application logic out of the
templates, and presentation logic out of the application. This will most
definately keep things managable and scalable for the foreseeable future.
</para>
<para>
One of the unique aspects about Smarty is the template compling. This means
Smarty reads the template files and creates PHP scripts from them. Once
they are created, they are executed from then on. Therefore there is no
costly template file parsing for each request, and each template can take
full advantage of PHP compiler cache solutions such as Zend Accelerator
(http://www.zend.com) or PHP Accelerator
(http://www.php-accelerator.co.uk).
</para> </para>
<para> <para>
Some of Smarty's features: Some of Smarty's features:
@@ -41,66 +68,7 @@
<listitem><para>Custom cache handling functions</para></listitem> <listitem><para>Custom cache handling functions</para></listitem>
<listitem><para>Plugin architecture</para></listitem> <listitem><para>Plugin architecture</para></listitem>
</itemizedlist> </itemizedlist>
</sect1>
<sect1 id="how.smarty.works">
<title>How Smarty works</title>
<sect2 id="features.compiling"><title>Compiling</title>
<para>
Smarty compiles the templates into native PHP code on-the-fly. The actual
PHP scripts that are generated are created implicitly, so theoretically you
should never have to worry about touching these files, or even know of their
existence. The exception to this is debugging Smarty template syntax errors,
discussed later in this document.
</para>
</sect2>
<sect2 id="features.caching">
<title>Caching</title>
<para>
Smarty can cache the output of your generated templates. By default
this is disabled. If you <link linkend="variable.caching">enable
caching</link>, Smarty will store a copy of the generated template
output, and use this until the copy <link
linkend="variable.cache.lifetime">expires</link>, regenerating a new
one. The default cache expire time can be configured from the
class. The exception to the rule is the <link
linkend="language.function.insert">insert</link> tag. Anything
generated by the insert tag is not cached, but run dynamically on
every invocation, even within cached content.
</para>
<note>
<title>Technical Note</title>
<para>
Any time you change a template, change values in
config files or change the content that gets displayed in a
template, you can turn on compile_check to regenerate the caches
that are affected, or wait for the cache to expire to see the
results of the changes. You clear caches manually by deleting files
from the cache directory, programatically with <link
linkend="api.clear.cache">clear_cache</link> or <link
linkend="api.clear.all.cache">clear_all_cache</link>, or turn on
$compile_check (or $force_compile).
</para>
</note>
<note>
<title>Technical Note</title>
<para>
If you have caching enabled AND you have compile_check enabled, the cached
file will regenerate if an involved template or config file has been
modified, regardless of the cache expire time. This results in a slight
performance hit since Smarty has to check the templates and config files
for modification times. Therefore if you are not actively changing
templates or config files, it is advisable to leave compile_check off.
Enabling $force_compile will effectively disable caching, as the cache will
get regerated on every invocation.
</para>
</note>
</sect2>
</sect1>
</chapter> </chapter>
<chapter id="installation"> <chapter id="installation">
<title>Installation</title> <title>Installation</title>
@@ -113,17 +81,20 @@
<sect1 id="installing.smarty.basic"> <sect1 id="installing.smarty.basic">
<title>Basic Installation</title> <title>Basic Installation</title>
<note>
<title>Technical Note</title>
<para> <para>
This installation guide makes the assumption that you are familiar with This installation guide makes the assumption that you are familiar with
your web server setup, your PHP setup, and your operating system directory your web server setup, your PHP setup, and your operating system directory
naming conventions. In these examples we use a Unix filesystem, so be sure naming conventions. In these examples we use a Unix filesystem, so be sure
you make the appropriate adjustments for your environment. To be sure the you make the appropriate adjustments for your environment.
examples in this installation work, add "/php/includes" to your PHP
include_path if it is not already there. Your include_path is usually set
in your php.ini file. You can see your current include_path from phpinfo(),
or you can use ini_get('include_path') from within your PHP script.
</para> </para>
<para> <para>
The following examples assume that "/php/includes" is in your PHP
include_path. See the PHP manual for information on setting this up.
</para>
</note>
<para>
First install the Smarty library files. These are the PHP files that you DO First install the Smarty library files. These are the PHP files that you DO
NOT edit. They are shared among all applications and they only get updated NOT edit. They are shared among all applications and they only get updated
when you upgrade to a new version of Smarty. when you upgrade to a new version of Smarty.
@@ -131,10 +102,10 @@
<note> <note>
<title>Technical Note</title> <title>Technical Note</title>
<para> <para>
We highly recommend you do not edit the Smarty files. This makes upgrades We recommend that you do not edit the Smarty library files. This makes
much easier for you. You DO NOT need to edit these files to configure your upgrades much easier for you. You DO NOT need to edit these files to
applications! Use an instance of the Smarty class, which we'll get to in configure your applications! Use an instance of the Smarty class, which
the sample setup below. we'll get to in the sample setup below.
</para> </para>
</note> </note>
@@ -209,16 +180,16 @@ $smarty = new Smarty;</screen>
<note> <note>
<title>Technical Note</title> <title>Technical Note</title>
<para> <para>
As a rule of thumb, none of these directories should be within the document As a rule of thumb, none of these directories should be under the document
root of your web server, and this is recommended to avoid any possible root of your web server. This is recommended to avoid any possible direct
direct access. You may, for example, have config files with sensitive data. access. You may, for example, have config files with sensitive data.
</para> </para>
</note> </note>
<para> <para>
You will need as least one file under your document root, and that is the You will need as least one file under your document root, and that is the
script accessed by the web browser. We will call our script "index.php", script accessed by the web browser. We will call our script "index.php",
and place it in a subdirectory called "guestbook". and place it in a subdirectory under the document root called "/guestbook/".
</para> </para>
<note> <note>
@@ -254,6 +225,15 @@ $smarty = new Smarty;</screen>
/web/www.mydomain.com/docs/guestbook/index.php</screen> /web/www.mydomain.com/docs/guestbook/index.php</screen>
</example> </example>
<note>
<title>Technical Note</title>
<para>
The $config_dir and $cache_dir are not absolutely necessary if you do not
plan on using config files or template caching. It is probably a good idea
to set them up anyways, in the case you decide to use them later.
</para>
</note>
<para> <para>
Smarty will need write access to the $compile_dir and $cache_dir, so be sure Smarty will need write access to the $compile_dir and $cache_dir, so be sure
the web server user can write to them. This is usually user "nobody" and the web server user can write to them. This is usually user "nobody" and
@@ -298,6 +278,17 @@ Hello, {$name}!</screen>
</example> </example>
<note>
<title>Technical Note</title>
<para>
{* Smarty *} is a template comment. It is not required, but it is good
practice to start all your template files with this comment. It makes
the file easy to recognize regardless of the file extension. For
example, text editors could recognize the file and turn on special
syntax highlighting.
</para>
</note>
<para> <para>
Now lets edit index.php. We'll create an instance of Smarty, assign a Now lets edit index.php. We'll create an instance of Smarty, assign a
template variable and display the index.tpl file. template variable and display the index.tpl file.
@@ -326,10 +317,11 @@ $smarty->display('index.tpl');</screen>
<title>Technical Note</title> <title>Technical Note</title>
<para> <para>
In our example, we are setting absolute paths to all of the Smarty In our example, we are setting absolute paths to all of the Smarty
directories. If these directories are within your PHP include_path, then directories. If '/web/www.mydomain.com/smarty/guestbook/' is within your
these settings are not necessary. However, it is more efficient and (in PHP include_path, then these settings are not necessary. However, it is
personal experience) less error-prone to set them to absolute paths. This more efficient and (from experience) less error-prone to set them to
ensures that Smarty is getting files from the directories you intended. absolute paths. This ensures that Smarty is getting files from the
directories you intended.
</para> </para>
</note> </note>
@@ -342,7 +334,7 @@ $smarty->display('index.tpl');</screen>
</para> </para>
</sect1> </sect1>
<sect1 id="installing.smarty.extended"> <sect1 id="installing.smarty.extended">
<title>Extended Installation</title> <title>Extended Setup</title>
<para> <para>
This is a continuation of the <link This is a continuation of the <link
@@ -365,8 +357,8 @@ $smarty->display('index.tpl');</screen>
define(SMARTY_DIR,'/usr/local/lib/php/Smarty/'); define(SMARTY_DIR,'/usr/local/lib/php/Smarty/');
require(SMARTY_DIR.'Smarty.class.php'); require(SMARTY_DIR.'Smarty.class.php');
// load application library files // a good place to load application library files, example:
require('guestbook/guestbook.lib.php'); // require('guestbook/guestbook.lib.php');
Smarty_GuestBook extends Smarty { Smarty_GuestBook extends Smarty {

343
docs/programmers.sgml
View File

@@ -51,8 +51,7 @@ require_once(SMARTY_DIR."Smarty.class.php");</programlisting>
This is the name of the directory where compiled templates are This is the name of the directory where compiled templates are
located. By default this is "./templates_c", meaning that it located. By default this is "./templates_c", meaning that it
will look for the compile directory in the same directory as will look for the compile directory in the same directory as
the executing php script. This was added to Smarty version the executing php script.
1.2.1.
</para> </para>
<note> <note>
<title>Technical Note</title> <title>Technical Note</title>
@@ -239,7 +238,7 @@ $smarty-&gt;autoload_filters = array('pre' =&gt; array('trim', 'stamp'),
for the cache directory in the same directory as the executing for the cache directory in the same directory as the executing
php script. You can also use your own custom cache handler php script. You can also use your own custom cache handler
function to control cache files, which will ignore this function to control cache files, which will ignore this
setting. (added to Smarty 1.3.0) setting.
</para> </para>
<note> <note>
<title>Technical Note</title> <title>Technical Note</title>
@@ -261,14 +260,29 @@ $smarty-&gt;autoload_filters = array('pre' =&gt; array('trim', 'stamp'),
<para> <para>
This is the length of time in seconds that a template cache is valid. This is the length of time in seconds that a template cache is valid.
Once this time has expired, the cache will be regenerated. $caching must Once this time has expired, the cache will be regenerated. $caching must
be set to "true" for this setting to work. You can also force the cache be set to "true" for $cache_lifetime to have any purpose. A value of -1
to expire with <link will force the cache to never expire. A value of 0 will cause the cache
linkend="api.clear.all.cache">clear_all_cache</link>. A setting of -1 to always regenerate (good for testing only, to disable caching a more
will force the cache to never expire. A setting of 0 will cause the efficient method is to set <link
cache to always regenerate (which doesn't make much sense, you'd be linkend="variable.caching">$caching</link> = false.)
better off setting caching=false.) If $caching = 2, then the cache
expiration time is saved along with the template.
</para> </para>
<para>
If <link linkend="variable.force.compile">$force_compile</link> is
enabled, the cache files will be regenerated every time, effectively
disabling caching. You can clear all the cache files with the <link
linkend="api.clear.all.cache">clear_all_cache()</link> function, or
individual cache files (or groups) with the <link
linkend="api.clear.cache">clear_cache()</link> function.
</para>
<note>
<title>Technical Note</title>
<para>
If you want to give certain templates their own cache lifetime, you could
do this by setting <link linkend="variable.caching">$caching</link> = 2,
then set $cache_lifetime to a unique value just before calling display()
or fetch().
</para>
</note>
</sect1> </sect1>
<sect1 id="variable.cache.handler.func"> <sect1 id="variable.cache.handler.func">
<title>$cache_handler_func</title> <title>$cache_handler_func</title>
@@ -292,7 +306,7 @@ $smarty-&gt;autoload_filters = array('pre' =&gt; array('trim', 'stamp'),
<title>$default_template_handler_func</title> <title>$default_template_handler_func</title>
<para> <para>
This function is called when a template cannot be obtained from This function is called when a template cannot be obtained from
its resource. (added to Smarty 1.5.2) its resource.
</para> </para>
</sect1> </sect1>
<sect1 id="variable.php.handling"> <sect1 id="variable.php.handling">
@@ -342,9 +356,6 @@ $smarty-&gt;autoload_filters = array('pre' =&gt; array('trim', 'stamp'),
<listitem><para>PHP functions are not allowed as modifiers, except <listitem><para>PHP functions are not allowed as modifiers, except
those specified in the $security_settings</para></listitem> those specified in the $security_settings</para></listitem>
</itemizedlist> </itemizedlist>
<para>
NOTE: Security features were added to Smarty 1.4.3.
</para>
</sect1> </sect1>
<sect1 id="variable.secure.dir"> <sect1 id="variable.secure.dir">
<title>$secure_dir</title> <title>$secure_dir</title>
@@ -530,8 +541,7 @@ $smarty->clear_all_assign();</programlisting>
</funcprototype> </funcprototype>
</funcsynopsis> </funcsynopsis>
<para> <para>
This clears the entire template cache. This was added to Smarty This clears the entire template cache.
1.3.0.
</para> </para>
<example> <example>
<title>clear_all_cache</title> <title>clear_all_cache</title>
@@ -550,8 +560,7 @@ $smarty->clear_all_cache();</programlisting>
</funcsynopsis> </funcsynopsis>
<para> <para>
This clears the value of an assigned variable. This This clears the value of an assigned variable. This
can be a single value, or an array of values. Array can be a single value, or an array of values.
functionality was added to Smarty 1.3.0.
</para> </para>
<example> <example>
<title>clear_assign</title> <title>clear_assign</title>
@@ -579,7 +588,7 @@ $smarty->clear_assign(array("Name","Address","Zip"));</programlisting>
cache by supplying the cache id as the second parameter. You cache by supplying the cache id as the second parameter. You
can also pass a compile id as a third paramter. You can "group" can also pass a compile id as a third paramter. You can "group"
templates together so they can be removed as a group. See the templates together so they can be removed as a group. See the
<link linkend="features.caching">caching section</link> for <link linkend="caching">caching section</link> for
more information. more information.
</para> </para>
<example> <example>
@@ -629,7 +638,7 @@ $smarty->clear_compiled_tpl();</programlisting>
This displays the template. Supply a valid <link This displays the template. Supply a valid <link
linkend="template.resources">template resource</link> linkend="template.resources">template resource</link>
type and path. As an optional second parameter, you can pass a type and path. As an optional second parameter, you can pass a
cache id. See the <link linkend="features.caching">caching cache id. See the <link linkend="caching">caching
section</link> for more information. section</link> for more information.
</para> </para>
<para> <para>
@@ -709,7 +718,7 @@ $smarty->display("db:header.tpl");</programlisting>
Supply a valid <link Supply a valid <link
linkend="template.resources">template resource</link> linkend="template.resources">template resource</link>
type and path. As an optional second parameter, you can pass a type and path. As an optional second parameter, you can pass a
cache id. See the <link linkend="features.caching">caching cache id. See the <link linkend="caching">caching
section</link> for more information. section</link> for more information.
</para> </para>
<para> <para>
@@ -791,8 +800,7 @@ var_dump($tpl_vars);</programlisting>
<para> <para>
This returns true if there is a valid cache for this template. This returns true if there is a valid cache for this template.
This only works if <link This only works if <link
linkend="variable.caching">caching</link> is set to true. This linkend="variable.caching">caching</link> is set to true.
was added to Smarty 1.3.0.
</para> </para>
<example> <example>
<title>is_cached</title> <title>is_cached</title>
@@ -1032,8 +1040,7 @@ $smarty->register_resource("db", array("db_get_template",
This function can be used to output an error message using Smarty. This function can be used to output an error message using Smarty.
<parameter>level</parameter> parameter can be one of the values <parameter>level</parameter> parameter can be one of the values
used for trigger_error() PHP function, i.e. E_USER_NOTICE, used for trigger_error() PHP function, i.e. E_USER_NOTICE,
E_USER_WARNING, etc. By default it's E_USER_WARNING. This function E_USER_WARNING, etc. By default it's E_USER_WARNING.
was added to Smarty 2.0.
</para> </para>
</sect1> </sect1>
@@ -1173,6 +1180,292 @@ $smarty->unregister_resource("db");</programlisting>
</sect1> </sect1>
</chapter> </chapter>
<chapter id="caching">
<title>Caching</title>
<para>
Caching is used to speed up a call to <link
linkend="api.display">display()</link> or <link
linkend="api.fetch">fetch()</link> 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() or fetch() is cached, one cache file could conceivably be made up
of several template files, config files, etc.
</para>
<para>
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 weather map containing new information by the
minute, it would not make sense to cache this page.
</para>
<sect1 id="caching.setting.up">
<title>Setting Up Caching</title>
<para>
The first thing to do is enable caching. This is done by setting <link
linkend="variable.caching">$caching</link> = true (or 1.)
</para>
<example>
<title>enabling caching</title>
<programlisting>
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
$smarty->display('index.tpl');</programlisting>
</example>
<para>
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 <link linkend="variable.cache.dir">$cache_dir</link>.
Upon the next call to display('index.tpl'), the cached copy will be used
instead of rendering the template again.
</para>
<note>
<title>Technical Note</title>
<para>
The files in the $cache_dir are named similar to the template name.
Although they end in the ".php" extention, they are not really executable
php scripts. Do not edit these files!
</para>
</note>
<para>
Each cached page has a limited lifetime determined by <link
linkend="variable.cache.lifetime">$cache_lifetime</link>. The default value
is 3600 seconds, or 1 hour. After that time expires, the cache is
regenerated. It is possible to give individual caches their own expiration
time by setting $caching = 2. See the documentation on <link
linkend="variable.cache.lifetime">$cache_lifetime</link> for details.
</para>
<example>
<title>setting cache_lifetime per cache</title>
<programlisting>
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = 2; // lifetime is per cache
// set the cache_lifetime for index.tpl to 15 minutes
$smarty->cache_lifetime = 300;
$smarty->display('index.tpl');
// set the cache_lifetime for home.tpl to 1 hour
$smarty->cache_lifetime = 3600;
$smarty->display('home.tpl');
// NOTE: the following $cache_lifetime setting will not work when $caching = 2.
// 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->cache_lifetime = 30; // 30 seconds
$smarty->display('home.tpl');</programlisting>
</example>
<para>
If <link linkend="variable.compile.check">$compile_check</link> is enabled,
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 slight
overhead so for optimum performance, leave $compile_check set to false.
</para>
<example>
<title>enabling $compile_check</title>
<programlisting>
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
$smarty->compile_check = true;
$smarty->display('index.tpl');</programlisting>
</example>
<para>
If <link linkend="variable.force.compile">$force_compile</link> is enabled,
the cache files will always be regenerated. This effectively turns off
caching. $force_compile is usually for debugging purposes only, a more
efficient way of disabling caching is to set <link
linkend="variable.caching">$caching</link> = false (or 0.)
</para>
<para>
The <link linkend="api.is.cached">is_cached()</link> 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.
</para>
<example>
<title>using is_cached()</title>
<programlisting>
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
if(!$smarty->is_cached('index.tpl')) {
// No cache available, do variable assignments here.
$contents = get_database_contents();
$smarty->assign($contents);
}
$smarty->display('index.tpl');</programlisting>
</example>
<para>
You can keep parts of a page dynamic with the <link
linkend="language.function.insert">insert</link> template function. Let's
say the whole page can be cached except for a banner that is displayed down
the right side of the page. By using an insert function for the banner, you
can keep this element dynamic within the cached content. See the
documentation on <link linkend="language.function.insert">insert</link> for
details and examples.
</para>
<para>
You can clear all the cache files with the <link
linkend="api.clear.all.cache">clear_all_cache()</link> function, or
individual cache files (or groups) with the <link
linkend="api.clear.cache">clear_cache()</link> function.
</para>
<example>
<title>clearing the cache</title>
<programlisting>
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
// clear out all cache files
$smarty->clear_all_cache();
// clear only cache for index.tpl
$smarty->clear_cache('index.tpl');
$smarty->display('index.tpl');</programlisting>
</example>
</sect1>
<sect1 id="caching.multiple.caches">
<title>Multiple Caches Per Page</title>
<para>
You can have multiple cache files for a single call to display() or
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.
</para>
<example>
<title>passing a cache_id to display()</title>
<programlisting>
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
$my_cache_id = $_GET['article_id'];
$smarty->display('index.tpl',$my_cache_id);</programlisting>
</example>
<para>
Above, we are passing the variable $my_cache_id to 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.
</para>
<note>
<title>Technical Note</title>
<para>
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_ids 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
10 characters and is made up of alpha-numerics only, and must be a valid
article_id in the database. Check for this!
</para>
</note>
<para>
Be sure to pass the same cache_id as the
second parameter to <link linkend="api.is.cached">is_cached()</link> and
<link linkend="api.clear.cache">clear_cache()</link>.
</para>
<example>
<title>passing a cache_id to is_cached()</title>
<programlisting>
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
$my_cache_id = $_GET['article_id'];
if(!$smarty->is_cached('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);</programlisting>
</example>
<para>
You can clear all caches for a particular cache_id by passing null as the
first parameter to clear_cache().
</para>
<example>
<title>clearing all caches for a particular cache_id</title>
<programlisting>
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
// clear all caches with "sports" as the cache_id
$smarty->clear_cache(null,"sports");
$smarty->display('index.tpl',"sports");</programlisting>
</example>
<para>
In this manner, you can "group" your caches together by giving them the
same cache_id.
</para>
</sect1>
<sect1 id="caching.groups">
<title>Cache Groups</title>
<para>
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.
</para>
<example>
<title>cache_id groups</title>
<programlisting>
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
// clear all caches with "sports|basketball" as the first two cache_id groups
$smarty->clear_cache(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->clear_cache(null,"sports");
$smarty->display('index.tpl',"sports|basketball");</programlisting>
</example>
<note>
<title>Technical Note</title>
<para>
The cache grouping does NOT use the path to the template as any part of the
cache_id. For example, if you have display('themes/blue/index.tpl'), you
cannot clear the cache for everything under the "themes/blue" directory. If
you want to do that, you must group them in the cache_id, such as
display('themes/blue/index.tpl','themes|blue'); Then you can clear the
caches for the blue theme with clear_cache(null,'themes|blue');
</para>
</note>
</sect1>
</chapter>
<chapter id="advanced.features"> <chapter id="advanced.features">
<title>Advanced Features</title> <title>Advanced Features</title>
<sect1 id="advanced.features.prefilters"> <sect1 id="advanced.features.prefilters">

10
libs/Smarty.class.php
View File

@@ -1442,8 +1442,14 @@ function _run_insert_handler($args)
if(isset($auto_source)) { if(isset($auto_source)) {
// make source name safe for filename // make source name safe for filename
$auto_source = str_replace($_dir_sep_enc,'^',urlencode($auto_source)); if($this->use_sub_dirs) {
$res .= $auto_source . '.php'; $_filename = basename($auto_source);
$_crc32 = crc32($auto_source) . $_dir_sep;
$_crc32 = substr($_crc32,0,3) . $_dir_sep . $_crc32;
$res .= $_crc32 . $_filename . '.php';
} else {
$res .= str_replace($_dir_sep_enc,'^',urlencode($auto_source));
}
} }
return $res; return $res;