smarty/docs/getting-started.sgml

<part id="getting.started">
 <title>Getting Started</title>

 <chapter id="overview">
  <title>Overview</title>
  <sect1 id="what.is.smarty">
   <title>What is Smarty?</title>
   <para>
    Smarty is a template engine for PHP. One of the unique aspects about
    Smarty is that it compiles the template files into native PHP scripts
    upon the first invocation. After that, it just executes the compiled
    PHP scripts. 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 Cache (http://www.zend.com) or PHP
    Accelerator (http://www.php-accelerator.co.uk).
   </para>
   <para>
    Some of Smarty's features:
   </para>
   <itemizedlist>
    <listitem><para>It is extremely fast.</para></listitem>
    <listitem><para>It is efficient since the PHP parser does the
      dirty work.</para></listitem>
    <listitem><para>No template parsing overhead, only compiles once.</para></listitem>
    <listitem><para>It is smart about recompiling only the template
      files that have changed.</para></listitem>
    <listitem><para>You can make <link linkend="language.custom.functions">custom
       functions</link> and custom <link linkend="language.modifiers">variable
       modifiers</link>, so the template language is extremely extensible.</para></listitem>
    <listitem><para>Configurable template delimiter tag syntax, so you can use
      {}, {{}}, &lt;!--{}--&gt;, etc.</para></listitem>
    <listitem><para>The if/elseif/else/endif constructs are passed to the
      PHP parser, so the {if ...} expression syntax can be as simple or as complex
      as you like.</para></listitem>
    <listitem><para>Unlimited nesting of sections, ifs, etc. allowed.</para></listitem>
    <listitem><para>It is possible to embed PHP code right in your template files,
      although this may not be needed (nor recommended)
      since the engine is so customizable.</para></listitem>
    <listitem><para>Built-in caching support</para></listitem>
    <listitem><para>Arbitrary template sources</para></listitem>
    <listitem><para>Custom cache handling functions</para></listitem>
    <listitem><para>Plugin architecture</para></listitem>
   </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>
     As of Smarty 1.4.6, 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 it 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. As of Smarty 1.4.7, enabling $force_compile will cause cache
     files to always be regenerated.
    </para>
	</note>
   </sect2>
  </sect1>
 </chapter>

 <chapter id="installation">
  <title>Installation</title>

  <sect1 id="installation.requirements">
   <title>Requirements</title>
   <para>
    Smarty requires PHP 4.0.6 or later. See the
    <link linkend="bugs">BUGS</link> section for caveats.
   </para>
  </sect1>

  <sect1 id="installing.smarty">
   <title>Installing Smarty</title>
   <para>
	Installing Smarty is fairly straightforward, there are a few things to be
	aware of. Smarty creates PHP scripts from the templates. This usually means
	allowing user "nobody" (or whomever the web server runs as) to have
	permission to write the files. Each installation of a Smarty application
	minimally needs a templates directory and a compiled templates directory.
	If you use configuration files you will also need a directory for those. By
	default these are named "templates", "templates_c" and "configs"
	respectively. "templates_c" needs to be writable by the web server user. If
	you plan on using caching, you will need to create a "cache" directory,
	also with permission to write files.
   </para>
   <note>
	<title>Technical Note</title>
	<para>
    You can get around the need to allow the web server
    user write access to compile templates. Smarty needs to compile the
    templates only once. This can be done from the command line, using the
    CGI version of PHP. example: "php -q index.php". Once the templates are
    compiled, they should run fine from the web environment. If you change
    a template, you must recompile from the command line again. If you do
    not have the CGI version of PHP available and you are concerned about
    world-writable directory access, you can chmod 777 the compile_dir, let
    the templates compile once as the web server user, then change the
    directory mode to 755. If you are using the caching feature of Smarty,
    the cache directory must always have write access for the web server
    user.
   </para>
   </note>
   <note>
   <title>Technical Note</title>
   <para>
    If you do not have access to the php.ini file, you can
    change non-server settings (such as your include_path) with the
    ini_set() command (available in PHP 4.0.4 or later.) example:
    ini_set("include_path",".:/usr/local/lib/php");
   </para>
   </note>
   <para>
    Copy the Smarty.class.php, Smarty.addons.php and Config_File.class.php
    scripts to a directory that is in your PHP include_path. NOTE: PHP will
    try to create a directory alongside the executing script called
    "templates_c". Be sure that directory permissions allow this to happen.
    You will see PHP error messages if this fails. You can also create the
    directory yourself before hand, and change the file ownership
    accordingly. See below.
   </para>
   <note>
   <title>Technical Note</title>
   <para>
    If you don't want to use include_path to find the
    Smarty files, you can set the SMARTY_DIR constant to the full path to
    your Smarty library files. Be sure the path ends with a slash!
   </para>
   </note>
   <example>
    <title>Example of installing Smarty</title>
    <screen>
# be sure you are in the web server document tree
# this assumes your web server runs as user "nobody"
# and you are in a un*x environment
gtar -zxvf Smarty-[version].tar.gz
mkdir templates_c
chown nobody:nobody templates_c
chmod 700 templates_c
# if you are using caching, do the following
mkdir cache
chown nobody:nobody cache
chmod 700 cache</screen>
   </example>
   <para>
    Next, try running the index.php script from your web browser.
   </para>
  </sect1>

  <sect1 id="smarty.constants">
   <title>Constants</title>
   <para></para>

   <sect2 id="constant.smarty.dir">
    <title>SMARTY_DIR</title>
    <para>
     This should be the full system path to the location of the Smarty
     class files. If this is not defined, then Smarty will attempt to
     determine the appropriate value automatically. If defined, the path
     must end with a slash.
    </para>
    <example>
     <title>SMARTY_DIR</title>
     <programlisting>
// set path to Smarty directory
define("SMARTY_DIR","/usr/local/lib/php/Smarty/");

require_once(SMARTY_DIR."Smarty.class.php");</programlisting>
    </example>
   </sect2>
  </sect1>
 </chapter>
</part>