What is Smarty?
Why use it?
Use Cases and Work Flow
Syntax Comparison
Template Inheritance
Best Practices
Crash Course
You may use the Smarty logo according to the trademark notice.
For sponsorship, advertising, news or other inquiries, contact us at:
Install the Smarty library files which are in the
/libs/
sub directory of
the distribution. These are .php
files that you
SHOULD NOT edit. They are shared among all applications and only get
changed when you upgrade to a new version of Smarty.
In the examples below the Smarty tarball has been unpacked to:
/usr/local/lib/Smarty-v.e.r/
for *nix
machines
and
c:\webroot\libs\Smarty-v.e.r\
for the
windows environment.
Example 2.1. Required Smarty library files
Smarty-v.e.r/ libs/ Smarty.class.php debug.tpl sysplugins/* (everything) plugins/* (everything)
Smarty uses a PHP constant
named SMARTY_DIR
which is the full system file path
to the Smarty libs/
directory.
Basically, if your application can find the
Smarty.class.php
file, you do not need to set the
SMARTY_DIR
as 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's how you create an instance of Smarty in your PHP scripts:
<?php // NOTE: Smarty has a capital 'S' require_once('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 need to
do one of the following:
Example 2.2. Set SMARTY_DIR constant manually
<?php // *nix style (note capital 'S') define('SMARTY_DIR', '/usr/local/lib/Smarty-v.e.r/libs/'); // windows style define('SMARTY_DIR', 'c:/webroot/libs/Smarty-v.e.r/libs/'); // hack version example that works on both *nix and windows // Smarty is assumend to be in 'includes/' dir under current script define('SMARTY_DIR',str_replace("\\","/",getcwd()).'/includes/Smarty-v.e.r/libs/'); require_once(SMARTY_DIR . 'Smarty.class.php'); $smarty = new Smarty(); ?>
Example 2.3. Supply absolute path to library file
<?php // *nix style (note capital 'S') require_once('/usr/local/lib/Smarty-v.e.r/libs/Smarty.class.php'); // windows style require_once('c:/webroot/libs/Smarty-v.e.r/libs/Smarty.class.php'); $smarty = new Smarty(); ?>
Example 2.4. Add the library path to the php.ini
file
;;;;;;;;;;;;;;;;;;;;;;;;; ; Paths and Directories ; ;;;;;;;;;;;;;;;;;;;;;;;;; ; *nix: "/path1:/path2" include_path = ".:/usr/share/php:/usr/local/lib/Smarty-v.e.r/libs/" ; Windows: "\path1;\path2" include_path = ".;c:\php\includes;c:\webroot\libs\Smarty-v.e.r\libs\"
Example 2.5. Appending the include path in a php script with
ini_set()
<?php // *nix ini_set('include_path', ini_get('include_path').PATH_SEPARATOR.'/usr/local/lib/Smarty-v.e.r/libs/'); // windows ini_set('include_path', ini_get('include_path').PATH_SEPARATOR.'c:/webroot/lib/Smarty-v.e.r/libs/'); ?>
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
You can verify if your system has the correct access rights for these directories with
testInstall()
.
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 application.
Example 2.6. What the file structure looks like
/usr/local/lib/Smarty-v.e.r/libs/ Smarty.class.php debug.tpl sysplugins/* plugins/* /web/www.example.com/ guestbook/ templates/ index.tpl templates_c/ configs/ cache/ htdocs/ index.php
Be sure that you know the location of your web server's document root as a
file path. In the following examples, the document root is /web/www.example.com/guestbook/htdocs/
.
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 (but not mandatory) to place these directories
outside of the web server's document root.
You will need as least one file under your document root, and that is the
script accessed by the web browser. We will name our script
index.php
, and place it in a subdirectory under the
document root /htdocs/
.
Smarty will need write access
(windows users please ignore) to the
$compile_dir
and
$cache_dir
directories
(templates_c/
and
cache/
), so be sure the web server
user account 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 to see
what user and group are being used.
Example 2.7. Permissions and making directories writable
chown nobody:nobody /web/www.example.com/guestbook/templates_c/ chmod 770 /web/www.example.com/guestbook/templates_c/ chown nobody:nobody /web/www.example.com/guestbook/cache/ chmod 770 /web/www.example.com/guestbook/cache/
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
display. This needs to be located in the
$template_dir
.
Example 2.8. /web/www.example.com/guestbook/templates/index.tpl
{* Smarty *} Hello {$name}, welcome to Smarty!
{* 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.
Example 2.9. Editing /web/www.example.com/docs/guestbook/index.php
<?php require_once(SMARTY_DIR . 'Smarty.class.php'); $smarty = new Smarty(); $smarty->setTemplateDir('/web/www.example.com/guestbook/templates/'); $smarty->setCompileDir('/web/www.example.com/guestbook/templates_c/'); $smarty->setConfigDir('/web/www.example.com/guestbook/configs/'); $smarty->setCacheDir('/web/www.example.com/guestbook/cache/'); $smarty->assign('name','Ned'); //** un-comment the following line to show the debug console //$smarty->debugging = true; $smarty->display('index.tpl'); ?>
In our example, we are setting absolute paths to all of the Smarty
directories. If /web/www.example.com/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 navigate to the index.php
file with the web browser.
You should see "Hello Ned, welcome to Smarty!"
You have completed the basic setup for Smarty!