Basic Installation

Install the Smarty library files which are in the /libs/ directory of the distribution. These are the PHP files that you SHOULD NOT edit. They are shared among all applications and they only get updated when you upgrade to a new version of Smarty.

Example 2-1. Smarty library files

Smarty.class.php
Smarty_Compiler.class.php
Config_File.class.php
debug.tpl
/core/*.php (all of them)
/plugins/*.php (all of them)

Smarty uses a PHP constant named SMARTY_DIR which is the system filepath Smarty library directory. Basically, if your application can find the Smarty.class.php file, you do not need to set SMARTY_DIR, Smarty will figure it out on its own. Therefore, if Smarty.class.php is not in your include_path, or you do not supply an absolute path to it in your application, then you must define SMARTY_DIR manually. SMARTY_DIR must include a trailing slash.

Here is how you create an instance of Smarty in your PHP scripts:

Example 2-2. Create Smarty instance of Smarty


<?php
require('Smarty.class.php');
$smarty = new Smarty;
?>

Try running the above script. If you get an error saying the Smarty.class.php file could not be found, you have to do one of the following:

Example 2-3. Supply absolute path to library file


<?php
require('/usr/local/lib/php/Smarty/Smarty.class.php');
$smarty = new Smarty;
?>

Example 2-4. Add library directory to php_include path


<?php
// Edit your php.ini file, add the Smarty library
// directory to the include_path and restart web server.
// Then the following should work:
require('Smarty.class.php');
$smarty = new Smarty;
?>

Example 2-5. Set SMARTY_DIR constant manually


<?php
define('SMARTY_DIR', '/usr/local/lib/php/Smarty/');
require(SMARTY_DIR . 'Smarty.class.php');
$smarty = new Smarty;
?>

Now that the library files are in place, it's time to setup the Smarty directories for your application. Smarty requires four directories which are (by default) named templates, templates_c, configs and cache. Each of these are definable by the Smarty class properties $template_dir, $compile_dir, $config_dir, and $cache_dir respectively. It is highly recommended that you setup a separate set of these directories for each application that will use Smarty.

Be sure you know the location of your web server document root. In our example, the document root is "/web/www.mydomain.com/docs/". The Smarty directories are only accessed by the Smarty library and never accessed directly by the web browser. Therefore to avoid any security concerns, it is recommended to place these directories outside of the document root.

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. We'll place our Smarty directories under "/web/www.mydomain.com/smarty/guestbook/".

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 under the document root called "/guestbook/".

Technical Note: 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.mydomain.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.)

Lets take a look at the file structure so far:

Example 2-6. Example file structure

/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/core/*.php
/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

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 "www" and group "www". 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.

Example 2-7. Setting file permissions

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

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

Technical Note: 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.

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

Example 2-8. Editing /web/www.mydomain.com/smarty/guestbook/templates/index.tpl

{* Smarty *}

Hello, {$name}!

Technical Note: {* 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.

Now lets edit index.php. We'll create an instance of Smarty, assign a template variable and display the index.tpl file. In our example environment, "/usr/local/lib/php/Smarty" is in our include_path. Be sure you do the same, or use absolute paths.

Example 2-9. Editing /web/www.mydomain.com/docs/guestbook/index.php


<?php

// load Smarty library
require('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');
?>

Technical Note: In our example, we are setting absolute paths to all of the Smarty directories. If '/web/www.mydomain.com/smarty/guestbook/' is within your PHP include_path, then these settings are not necessary. However, it is more efficient and (from experience) less error-prone to set them to absolute paths. This ensures that Smarty is getting files from the directories you intended.

Now load the index.php file from your web browser. You should see "Hello, Ned!"

You have completed the basic setup for Smarty!