Smarty is a template engine for PHP. More specifically, it facilitates a managable way to separate application logic and content from its presentation. This is best described in a situation where the application programmer and the template designer play different roles, or in most cases are not the same person. For example, let's say you are creating a web page that is displaying a newspaper article. The article headline, tagline, author and body are content elements, they contain no information about how they will be presented. They are passed into Smarty by the application, then the template designer edits the templates and uses a combination of HTML tags and template tags to format the presentation of these elements (HTML tables, background colors, font sizes, style sheets, etc.) One day the programmer needs to change the way the article content is retrieved (a change in application logic.) This change does not affect the template designer, the content will still arrive in the template exactly the same. Likewise, if the template designer wants to completely redesign the templates, this requires no changes to the application logic. Therefore, the programmer can make changes to the application logic without the need to restructure templates, and the template designer can make changes to templates without breaking application logic. Now for a short word on what Smarty does NOT do. Smarty does not attempt to completely separate logic from the templates. There is no problem with logic in your templates under the condition that this logic is strictly for presentation. A word of advice: keep application logic out of the templates, and presentation logic out of the application. This will most definately keep things managable and scalable for the foreseeable future. One of the unique aspects about Smarty is the template compling. This means Smarty reads the template files and creates PHP scripts from them. Once they are created, they are executed from then on. 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 Accelerator (http://www.zend.com) or PHP Accelerator (http://www.php-accelerator.co.uk). Some of Smarty's features: It is extremely fast. It is efficient since the PHP parser does the dirty work. No template parsing overhead, only compiles once. It is smart about recompiling only the template files that have changed. You can make custom functions and custom variable modifiers, so the template language is extremely extensible. Configurable template delimiter tag syntax, so you can use {}, {{}}, <!--{}-->, etc. 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. Unlimited nesting of sections, ifs, etc. allowed. 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. Built-in caching support Arbitrary template sources Custom cache handling functions Plugin architecture Smarty requires a web server running PHP 4.0.6 or later. 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. The following examples assume that "/php/includes" is in your PHP include_path. See the PHP manual for information on setting this up. 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. We recommend that you do not edit the Smarty library 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. This is a list of the required library files that come with Smarty: Smarty.class.php Smarty_Compiler.class.php Config_File.class.php debug.tpl /plugins/*.php (all of them!) You can either place these library files within your PHP include_path, or in any directory as long as you define that with the SMARTY_DIR constant. We'll show an example of both. Here is how you create an instance of Smarty in your PHP scripts: require('Smarty.class.php'); $smarty = new Smarty; If the library files are outside of your PHP include_path, you must define the absolute path with the SMARTY_DIR constant. SMARTY_DIR must end with a slash. Lets say we place our Smarty library files in "/usr/local/lib/php/Smarty/". define(SMARTY_DIR,'/usr/local/lib/php/Smarty/'); require(SMARTY_DIR.'Smarty.class.php'); $smarty = new Smarty; Now the library files are in place, it's time to setup the Smarty directories. 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. Be sure you know the location of your web server document root. In our example, the document root is "/web/www.domain.com/docs/". 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/". As a rule of thumb, none of these directories should be under the document root of your web server. This is recommended to avoid any possible direct access. You may, for example, have config files with sensitive data. 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/". 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.) Lets take a look at the file structure so far: /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 The $config_dir and $cache_dir are not absolutely necessary if you do not plan on using config files or template caching. It is probably a good idea to set them up anyways, in the case you decide to use them later. 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. 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/ 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. {* Smarty *} Hello, {$name}! {* 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. 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'); 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! This is a continuation of the basic installation, please read that first! 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". // load Smarty library files define(SMARTY_DIR,'/usr/local/lib/php/Smarty/'); require(SMARTY_DIR.'Smarty.class.php'); // a good place to load application library files, example: // 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'); } } 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. Now lets alter the index.php file to use setup.php: require('guestbook/setup.php'); $smarty = new Smarty_GuestBook; $smarty->assign('name','Ned'); $smarty->display('index.tpl'); 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.