From e4b3570d828b1a7f2a7461a94951ceb331f0a3e3 Mon Sep 17 00:00:00 2001 From: mohrt Date: Tue, 25 Jun 2002 23:02:58 +0000 Subject: [PATCH] update installation docs --- docs/getting-started.sgml | 404 ++++++++++++++++++++++++++------------ docs/programmers.sgml | 14 +- 2 files changed, 280 insertions(+), 138 deletions(-) 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