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>
	 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 id="installation">
  <title>Installation</title>

  <sect1 id="installation.requirements">
   <title>Requirements</title>
   <para>
   Smarty requires a web server running PHP 4.0.6 or later.
   </para>
  </sect1>

  <sect1 id="installing.smarty.basic">
    <title>Basic Installation</title>
	<para>
	This installation guide makes the assumption that you are familiar with
	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
	you make the appropriate adjustments for your environment. To be sure the
	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>
	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
	when you upgrade to a new version of Smarty.
	</para>
	<note>
	 <title>Technical Note</title>
	 <para>
	 We highly recommend you do not edit the Smarty files. This makes upgrades
	 much easier for you. You DO NOT need to edit these files to configure your
	 applications! Use an instance of the Smarty class, which we'll get to in
	 the sample setup below.
	</para>
	</note>

	<para>
	This is a list of the required library files that come with Smarty:
	</para>
	<example>
     <title>Smarty library files list</title>
     <screen>
Smarty.class.php
Smarty_Compiler.class.php
Config_File.class.php
debug.tpl
/plugins/*.php (all of them!)</screen>
	</example>

	<para>
	You can either place these library files within your PHP include_path, or
	in any directory as long as you define that with the <link
	linkend="constant.smarty.dir">SMARTY_DIR</link> constant. We'll show an
	example of both.
	</para>
	<para>
	Here is how you create an instance of Smarty in your PHP scripts:
	</para>

	<example>
     <title>Create Smarty instance from include_path</title>
     <screen>
require('Smarty.class.php');
$smarty = new Smarty;</screen>
	</example>

	<para>
	If the library files are outside of your PHP include_path, you must define
	the absolute path with the <link
	linkend="constant.smarty.dir">SMARTY_DIR</link> constant. SMARTY_DIR must
	end with a slash. Lets say we place our Smarty library files in
	"/usr/local/lib/php/Smarty/".
	</para>

	<example>
     <title>Create Smarty instance from SMARTY_DIR</title>
     <screen>
define(SMARTY_DIR,'/usr/local/lib/php/Smarty/');
require(SMARTY_DIR.'Smarty.class.php');
$smarty = new Smarty;</screen>
	</example>

	<para>
	Now the library files are in place, it's time to setup the Smarty
	directories.
	</para>
	<para>
	For our installation example, we will be setting up the Smarty environment
	for a guest book application. We picked an application only for the purpose
	of a directory naming convention. You can use the same environment for any
	application, just replace "guestbook" with the name of your app.
	</para>
	<para>
	Be sure you know the location of your web server document root. In our
	example, the document root is "/web/www.domain.com/docs/".
	</para>
	<para>
	The Smarty directories are defined in the class variables $template_dir,
	$compile_dir, $config_dir and $cache_dir, which default to the values
	"templates", "templates_c", "configs" and "cache" respectively. In our
	example, we'll place all of these directories under
	"/web/www.domain.com/smarty/guestbook/".
	</para>

	<note>
	<title>Technical Note</title>
	<para>
	As a rule of thumb, none of these directories should be within the document
	root of your web server, and this is recommended to avoid any possible
	direct access. You may, for example, have config files with sensitive data.
    </para>
	</note>

	<para>
	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",
	and place it in a subdirectory called "guestbook".
	</para>
	
	<note>
	<title>Technical Note</title>
	<para>
	It is convenient to setup the web server so that "index.php" can be
	identified as the default directory index, so if you access
	"http://www.domain.com/guestbook/", the index.php script will be executed
	without "index.php" in the URL. In Apache you can set this up by adding
	"index.php" onto the end of your DirectoryIndex setting (separate each
	entry with a space.)
    </para>
	</note>
	
	<para>
	Lets take a look at the file structure so far:
	</para>

	<example>
     <title>Example file structure</title>
     <screen>
/usr/local/lib/php/Smarty/Smarty.class.php
/usr/local/lib/php/Smarty/Smarty_Compiler.class.php
/usr/local/lib/php/Smarty/Config_File.class.php
/usr/local/lib/php/Smarty/debug.tpl
/usr/local/lib/php/Smarty/plugins/*.php

/web/www.mydomain.com/smarty/guestbook/templates/
/web/www.mydomain.com/smarty/guestbook/templates_c/
/web/www.mydomain.com/smarty/guestbook/configs/
/web/www.mydomain.com/smarty/guestbook/cache/

/web/www.mydomain.com/docs/guestbook/index.php</screen>
	</example>

	<para>
	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
	group "nobody". For OS X users, the default is user "web" and group "web".
	If you are using Apache, you can look in your httpd.conf file (usually in
	"/usr/local/apache/conf/") to see what user and group are being used.
	</para>

	<example>
     <title>Setting file permissions</title>
     <screen>

chown nobody:nobody /web/www.mydomain.com/smarty/templates_c/
chmod 770 /web/www.mydomain.com/smarty/templates_c/

chown nobody:nobody /web/www.mydomain.com/smarty/cache/
chmod 770 /web/www.mydomain.com/smarty/cache/</screen>
	</example>

	<note>
	 <title>Technical Note</title>
	 <para>
	 chmod 770 will be fairly tight security, it only allows user "nobody" and
	 group "nobody" read/write access to the directories. If you would like to
	 open up read access to anyone (mostly for your own convenience of viewing
	 these files), you can use 775 instead.
     </para>
	</note>

	<para>
	We need to create the index.tpl file that Smarty will load. This will be
	located in your $template_dir.
	</para>

	<example>
     <title>Editing /web/www.mydomain.com/smarty/templates/index.tpl</title>
     <screen>

{* Smarty *}

Hello, {$name}!</screen>
	</example>


	<para>
	Now lets edit index.php. We'll create an instance of Smarty, assign a
	template variable and display the index.tpl file.
	</para>

	<example>
     <title>Editing /web/www.mydomain.com/docs/guestbook/index.php</title>
     <screen>

define(SMARTY_DIR,'/usr/local/lib/php/Smarty/');
require(SMARTY_DIR.'Smarty.class.php');

$smarty = new Smarty;

$smarty->template_dir = '/web/www.mydomain.com/smarty/guestbook/templates/';
$smarty->compile_dir = '/web/www.mydomain.com/smarty/guestbook/templates_c/';
$smarty->config_dir = '/web/www.mydomain.com/smarty/guestbook/configs/';
$smarty->cache_dir = '/web/www.mydomain.com/smarty/guestbook/cache/';

$smarty->assign('name','Ned');

$smarty->display('index.tpl');</screen>
	</example>

	<note>
	 <title>Technical Note</title>
	 <para>
	 In our example, we are setting absolute paths to all of the Smarty
	 directories. If these directories are within your PHP include_path, then
	 these settings are not necessary. However, it is more efficient and (in
	 personal experience) less error-prone to set them to absolute paths. This
	 ensures that Smarty is getting files from the directories you intended.
	 </para>
	</note>

	<para>
	Now load the index.php file from your web browser. You should see "Hello,
	Ned!"
	</para>
	<para>
	You have completed the basic setup for Smarty!
	</para>
   </sect1>
   <sect1 id="installing.smarty.extended">
   <title>Extended Installation</title>

   <para>
   This is a continuation of the <link
   linkend="installing.smarty.basic">basic installation</link>, please read
   that first!
   </para>
   <para>
   A slightly more flexible way to setup Smarty is to extend the class and
   initialize your Smarty environment. So instead of repeatedly setting
   directory paths, assigning the same vars, etc., we can do that in one place.
   Lets create a new directory "/php/includes/guestbook/" and make a new file called
   "setup.php".
   </para>

   <example>
    <title>Editing /php/includes/guestbook/setup.php</title>
    <screen>

// load Smarty library files
define(SMARTY_DIR,'/usr/local/lib/php/Smarty/');
require(SMARTY_DIR.'Smarty.class.php');

// load application library files
require('guestbook/guestbook.lib.php');

Smarty_GuestBook extends Smarty {

   function Smarty_GuestBook() {
   
   		// Class Constructor. These automatically get set with each new instance.

		$this->template_dir = '/web/www.mydomain.com/smarty/guestbook/templates/';
		$this->compile_dir = '/web/www.mydomain.com/smarty/guestbook/templates_c/';
		$this->config_dir = '/web/www.mydomain.com/smarty/guestbook/configs/';
		$this->cache_dir = '/web/www.mydomain.com/smarty/guestbook/cache/'; 
		
		$this->caching = true;
		$this->assign('app_name','Guest Book');
   }

}</screen>
   </example>

   <note>
	<title>Technical Note</title>
	<para>
	In our example, we keep application libraries (not intended for direct
	browser access) in a separate directory outside of the document root. These
	files may contain sensitive data that we don't want any direct access to.
	We keep all library files for the guest book application under
	"/php/includes/guestbook/" and load them in the setup script, as you see in
	the above example.
	</para>
   </note>

  <para>
  Now lets alter the index.php file to use setup.php:
  </para>
   
   <example>
    <title>Editing /web/www.mydomain.com/docs/guestbook/index.php</title>
    <screen>

require('guestbook/setup.php');

$smarty = new Smarty_GuestBook;

$smarty->assign('name','Ned');

$smarty->display('index.tpl');</screen>
   </example>

  <para>
  Now you see it is quite simple to bring up an instance of Smarty, just use
  Smarty_GuestBook which automatically initializes everything for our application.
  </para>
   
  </sect1>

 </chapter>
</part>