Smarty Manual
Prev | Chapter 2. Installation | Next

# Basic Installation

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 enviroment.

Example 2-1. Required Smarty library files
    Smarty-v.e.r/
       libs/
          Smarty.class.php
          Smarty_Compiler.class.php
          Config_File.class.php
          debug.tpl
          internals/*.php  (all of them)
          plugins/*.php    (all of them)

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

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
            Smarty_Compiler.class.php
            Config_File.class.php
            debug.tpl
            internals/*.php
            plugins/*.php

    /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.

> Note: 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/

> 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 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!

> 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.

Example 2-9. Editing /web/www.example.com/docs/guestbook/index.php
`<?php require_once(SMARTY_DIR . 'Smarty.class.php'); $smarty = new Smarty(); $smarty->template_dir = '/web/www.example.com/guestbook/templates/'; $smarty->compile_dir = '/web/www.example.com/guestbook/templates_c/'; $smarty->config_dir = '/web/www.example.com/guestbook/configs/'; $smarty->cache_dir = '/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'); ?>`

> Note: 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 naviagate 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!

Prev | Home | Next
Installation | Up | Extended Setup