diff --git a/docs/getting-started.sgml b/docs/getting-started.sgml
index f63dafc2..457b8c07 100644
--- a/docs/getting-started.sgml
+++ b/docs/getting-started.sgml
@@ -87,15 +87,14 @@
Technical Note
- As of Smarty 1.4.6, if you have caching enabled AND
- you have compile_check enabled, the cached file will regenerate if
- an involved template or config file has been modified, regardless
- of the cache expire time. This results in a slight performance hit
- since it has to check the templates and config files for
- modification times. Therefore if you are not actively changing
- templates or config files, it is advisable to leave compile_check
- off. As of Smarty 1.4.7, enabling $force_compile will cause cache
- files to always be regenerated.
+ If you have caching enabled AND you have compile_check enabled, the cached
+ file will regenerate if an involved template or config file has been
+ modified, regardless of the cache expire time. This results in a slight
+ performance hit since Smarty has to check the templates and config files
+ for modification times. Therefore if you are not actively changing
+ templates or config files, it is advisable to leave compile_check off.
+ Enabling $force_compile will effectively disable caching, as the cache will
+ get regerated on every invocation.
@@ -108,165 +107,316 @@
Requirements
- Smarty requires PHP 4.0.6 or later. See the
- BUGS section for caveats.
+ Smarty requires a web server running PHP 4.0.6 or later.
-
- Installing Smarty
-
- First install the Smarty library files. These are the PHP files that you DO
- NOT edit. They only get updated when you upgrade to a new version of Smarty.
- These files are shared among all applications installed on your server that
- utilize Smarty.
-
-
- Technical Note
+
+ Basic Installation
- We highly recommend you do not edit the Smarty files unless you know what
- you're doing. 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.
-
-
-
-
- Here is a list of the library files that come with Smarty:
-
-
- Smarty library files list
-
+ 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. To be sure the
+ examples in this installation work, add "/php/includes" to your PHP
+ include_path if it is not already there. Your include_path is usually set
+ in your php.ini file. You can see your current include_path from phpinfo(),
+ or you can use ini_get('include_path') from within your PHP script.
+
+
+ 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.
+
+
+ Technical Note
+
+ We highly recommend you do not edit the Smarty 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 library files list
+
Smarty.class.php
Smarty_Compiler.class.php
Config_File.class.php
-/plugins/(all files)
-
+debug.tpl
+/plugins/*.php (all of them!)
+
-
- Place these library files in a directory located within your PHP
- include_path. Your include_path is usually set in your php.ini file, and you
- can get your current include_path setting from the phpinfo() function. Call
- Smarty in your applications like this:
-
+
+ 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:
+
-
- Loading Smarty library files from include_path
-
-// Smarty.class.php will be found in your include_path
+
+ Create Smarty instance from include_path
+
require('Smarty.class.php');
$smarty = new Smarty;
-
-
-
- If you would like to place your library files outside of your include path,
- you must supply the absolute path in your application via 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/.
-
-
-
- Loading Smarty library files directly
-
+
+
+
+ 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/".
+
+
+
+ Create Smarty instance from SMARTY_DIR
+
define(SMARTY_DIR,'/usr/local/lib/php/Smarty/');
require(SMARTY_DIR.'Smarty.class.php');
$smarty = new Smarty;
-
+
-
- Now we need to setup the directories for our application. These are
- $template_dir, $compile_dir, $config_dir and $cache_dir. It is your
- discretion to have your applications share any of these directories, or
- make them separate. None of these directories need be in the document root
- of your web server, so keep them out of there to avoid the issue of prying
- eyes getting to these files directly with a browser.
-
-
- Lets take a look at an example of a complete file structure for all of our
- files:
-
-
-
- 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/plugins/*.php
+
+ 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/".
+
-/web/www.mydomain.com/smarty/templates/
-/web/www.mydomain.com/smarty/templates_c/
-/web/www.mydomain.com/smarty/configs/
-/web/www.mydomain.com/smarty/cache/
+
+ Technical Note
+
+ As a rule of thumb, none of these directories should be within the document
+ root of your web server, and this is recommended to avoid any possible
+ direct access. You may, for example, have config files with sensitive data.
+
+
-/web/www.mydomain.com/docs/myapp/index.php
-
+
+ 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 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.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:
+
-
- 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".
-
-
- Setting file permissions
-
+
+ Example file structure
+
+/php/includes/Smarty/Smarty.class.php
+/php/includes/Smarty/Smarty_Compiler.class.php
+/php/includes/Smarty/Config_File.class.php
+/php/includes/Smarty/debug.tpl
+/php/includes/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 "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.
+
+
+
+ Setting file permissions
+
chown nobody:nobody /web/www.mydomain.com/smarty/templates_c/
-chmod 550 /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 550 /web/www.mydomain.com/smarty/cache/
+chmod 770 /web/www.mydomain.com/smarty/cache/
+
-/web/www.mydomain.com/docs/index.php
-
-
-
- In this example, index.php is in our document root under the subdirectory
- "myapp". Lets edit this file and call a Smarty template.
-
-
-
- Editing index.php
-
+
+ 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.
+
+
-// contents of /web/www.mydomain.com/docs/myapp/index.php
+
+ We need to create the index.tpl file that Smarty will load. This will be
+ located in your $template_dir.
+
+
+
+ Editing /web/www.mydomain.com/smarty/templates/index.tpl
+
+
+{* Smarty *}
+
+Hello, {$name}!
+
+
+
+
+ Now lets edit index.php. We'll create an instance of Smarty, assign a
+ template variable and display the index.tpl file.
+
+
+
+ Editing /web/www.mydomain.com/docs/guestbook/index.php
+
define(SMARTY_DIR,'/usr/local/lib/php/Smarty/');
require(SMARTY_DIR.'Smarty.class.php');
$smarty = new Smarty;
-/*
- NOTE: the following four lines do not need to be set if
- /web/www.mydomain.com/smarty/ is in your include_path.
-*/
+$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->template_dir = '/web/www.mydomain.com/smarty/templates/';
-$smarty->compile_dir = '/web/www.mydomain.com/smarty/templates_c/';
-$smarty->config_dir = '/web/www.mydomain.com/smarty/configs/';
-$smarty->cache_dir = '/web/www.mydomain.com/smarty/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 these directories are within your PHP include_path, then
+ these settings are not necessary. However, it is more efficient and (in
+ personal 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 Installation
+
- Before we execute this, we need to create the index.tpl file that Smarty will
- load. This will be located in your $template_dir.
+ 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".
- Editing index.tpl
+ Editing /php/includes/guestbook/setup.php
-{* contents of /web/www.mydomain.com/smarty/templates/index.tpl *}
+// load Smarty library files
+define(SMARTY_DIR,'/usr/local/lib/php/Smarty/');
+require(SMARTY_DIR.'Smarty.class.php');
-Hello World!
-
+// load application library files
+require('guestbook/guestbook.lib.php');
+
+Smarty_GuestBook extends Smarty {
+
+ function Smarty_GuestBook() {
-
- Now load the index.php file from your web browser. You should see "Hello
- World!" That's it for the basic setup for Smarty!
-
+ // 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');
+ }
+
+}
+
+
+
+ Technical Note
+
+ 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:
+
+
+
+ Editing /web/www.mydomain.com/docs/guestbook/index.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.
+
diff --git a/docs/programmers.sgml b/docs/programmers.sgml
index 57c4e0db..d1d5e3ed 100644
--- a/docs/programmers.sgml
+++ b/docs/programmers.sgml
@@ -78,18 +78,13 @@
included templates and assigned variables for the current
template page.
-
- NOTE: This was added to Smarty 1.4.3.
- $debug_tpl
- This is the name of the template file used for the debugging
- console.
-
-
- NOTE: This was added to Smarty 1.4.3.
+ This is the name of the template file used for the debugging console. By
+ default, it is named debug.tpl and is located in the SMARTY_DIR.
@@ -101,9 +96,6 @@
for that invocation of the script. If $debugging is true, this
value is ignored.
-
- NOTE: This was added to Smarty 1.4.4.
- $global_assign