Smarty: Installation
Chapter 2 - Installation
Requirements
Smarty requires a web server running PHP 4.0.6 or later.
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
/internals/*.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.example.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.example.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.example.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/internals/*.php
/usr/local/lib/php/Smarty/plugins/*.php
/web/www.example.com/smarty/guestbook/templates/
/web/www.example.com/smarty/guestbook/templates_c/
/web/www.example.com/smarty/guestbook/configs/
/web/www.example.com/smarty/guestbook/cache/
/web/www.example.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.example.com/smarty/guestbook/templates_c/
chmod 770 /web/www.example.com/smarty/guestbook/templates_c/
chown nobody:nobody /web/www.example.com/smarty/guestbook/cache/
chmod 770 /web/www.example.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.example.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.example.com/docs/guestbook/index.php
<?php
// load Smarty
library
require('Smarty.class.php');
$smarty
= new
Smarty;
$smarty->template_dir
=
'/web/www.example.com/smarty/guestbook/templates/';
$smarty->compile_dir
=
'/web/www.example.com/smarty/guestbook/templates_c/';
$smarty->config_dir
=
'/web/www.example.com/smarty/guestbook/configs/';
$smarty->cache_dir
=
'/web/www.example.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.example.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!
Extended Setup
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. In our example environment, "/php/includes"
is in our include_path. Be sure you set this up too, or use absolute file paths.
Example 2-10. Editing /php/includes/guestbook/setup.php
<?php
// load Smarty library
require('Smarty.class.php');
// The setup.php file is a good place to load
// required application library files, and you
// can do that right here. An example:
// require('guestbook/guestbook.lib.php');
class Smarty_GuestBook extends Smarty
{
function Smarty_GuestBook()
{
// Class Constructor.
// These automatically get set with each new
instance.
$this->Smarty();
$this->template_dir
= '/web/www.example.com/smarty/guestbook/templates/';
$this->compile_dir =
'/web/www.example.com/smarty/guestbook/templates_c/';
$this->config_dir =
'/web/www.example.com/smarty/guestbook/configs/';
$this->cache_dir =
'/web/www.example.com/smarty/guestbook/cache/';
$this->caching
= true;
$this->assign('app_name',
'Guest Book');
}
}
?> |
|
Now lets alter the index.php file to use setup.php:
Example 2-11. Editing
/web/www.example.com/docs/guestbook/index.php
<?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.
|
