smarty-php/smarty
1
0
Fork 0
mirror of https://github.com/smarty-php/smarty.git synced 2025-08-04 10:24:26 +02:00
Code Issues Packages Projects Releases Wiki Activity

update installation docs

Browse Source
This commit is contained in:
mohrt
2002-06-25 23:02:58 +00:00
parent d2d1abd3ff
commit e4b3570d82
2 changed files with 280 additions and 138 deletions
Download Patch File Download Diff File Expand all files Collapse all files

314
docs/getting-started.sgml
View File

@@ -87,15 +87,14 @@
<note> <note>
<title>Technical Note</title> <title>Technical Note</title>
<para> <para>
As of Smarty 1.4.6, if you have caching enabled AND If you have caching enabled AND you have compile_check enabled, the cached
you have compile_check enabled, the cached file will regenerate if file will regenerate if an involved template or config file has been
an involved template or config file has been modified, regardless modified, regardless of the cache expire time. This results in a slight
of the cache expire time. This results in a slight performance hit performance hit since Smarty has to check the templates and config files
since it has to check the templates and config files for for modification times. Therefore if you are not actively changing
modification times. Therefore if you are not actively changing templates or config files, it is advisable to leave compile_check off.
templates or config files, it is advisable to leave compile_check Enabling $force_compile will effectively disable caching, as the cache will
off. As of Smarty 1.4.7, enabling $force_compile will cause cache get regerated on every invocation.
files to always be regenerated.
</para> </para>
</note> </note>
</sect2> </sect2>
@@ -108,31 +107,39 @@
<sect1 id="installation.requirements"> <sect1 id="installation.requirements">
<title>Requirements</title> <title>Requirements</title>
<para> <para>
Smarty requires PHP 4.0.6 or later. See the Smarty requires a web server running PHP 4.0.6 or later.
<link linkend="bugs">BUGS</link> section for caveats.
</para> </para>
</sect1> </sect1>
<sect1 id="installing.smarty"> <sect1 id="installing.smarty.basic">
<title>Installing Smarty</title> <title>Basic Installation</title>
<para>
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.
</para>
<para> <para>
First install the Smarty library files. These are the PHP files that you DO 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. NOT edit. They are shared among all applications and they only get updated
These files are shared among all applications installed on your server that when you upgrade to a new version of Smarty.
utilize Smarty.
</para> </para>
<note> <note>
<title>Technical Note</title> <title>Technical Note</title>
<para> <para>
We highly recommend you do not edit the Smarty files unless you know what We highly recommend you do not edit the Smarty files. This makes upgrades
you're doing. This makes upgrades much easier for you. You DO NOT need to much easier for you. You DO NOT need to edit these files to configure your
edit these files to configure your applications! Use an instance of the applications! Use an instance of the Smarty class, which we'll get to in
Smarty class, which we'll get to in the sample setup below. the sample setup below.
</para> </para>
</note> </note>
<para> <para>
Here is a list of the library files that come with Smarty: This is a list of the required library files that come with Smarty:
</para> </para>
<example> <example>
<title>Smarty library files list</title> <title>Smarty library files list</title>
@@ -140,33 +147,35 @@
Smarty.class.php Smarty.class.php
Smarty_Compiler.class.php Smarty_Compiler.class.php
Config_File.class.php Config_File.class.php
/plugins/(all files)</screen> debug.tpl
/plugins/*.php (all of them!)</screen>
</example> </example>
<para> <para>
Place these library files in a directory located within your PHP You can either place these library files within your PHP include_path, or
include_path. Your include_path is usually set in your php.ini file, and you in any directory as long as you define that with the SMARTY_DIR constant.
can get your current include_path setting from the phpinfo() function. Call We'll show an example of both.
Smarty in your applications like this: </para>
<para>
Here is how you create an instance of Smarty in your PHP scripts:
</para> </para>
<example> <example>
<title>Loading Smarty library files from include_path</title> <title>Create Smarty instance from include_path</title>
<screen> <screen>
// Smarty.class.php will be found in your include_path
require('Smarty.class.php'); require('Smarty.class.php');
$smarty = new Smarty;</screen> $smarty = new Smarty;</screen>
</example> </example>
<para> <para>
If you would like to place your library files outside of your include path, If the library files are outside of your PHP include_path, you must define
you must supply the absolute path in your application via the SMARTY_DIR the absolute path with the SMARTY_DIR constant. SMARTY_DIR must end with a
constant. SMARTY_DIR must end with a slash. Lets say we place our Smarty slash. Lets say we place our Smarty library files in
library files in /usr/local/lib/php/Smarty/. "/usr/local/lib/php/Smarty/".
</para> </para>
<example> <example>
<title>Loading Smarty library files directly</title> <title>Create Smarty instance from SMARTY_DIR</title>
<screen> <screen>
define(SMARTY_DIR,'/usr/local/lib/php/Smarty/'); define(SMARTY_DIR,'/usr/local/lib/php/Smarty/');
require(SMARTY_DIR.'Smarty.class.php'); require(SMARTY_DIR.'Smarty.class.php');
@@ -174,98 +183,239 @@ $smarty = new Smarty;</screen>
</example> </example>
<para> <para>
Now we need to setup the directories for our application. These are Now the library files are in place, it's time to setup the Smarty
$template_dir, $compile_dir, $config_dir and $cache_dir. It is your directories.
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.
</para> </para>
<para> <para>
Lets take a look at an example of a complete file structure for all of our For our installation example, we will be setting up the Smarty environment
files: 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.
</para>
<para>
Be sure you know the location of your web server document root. In our
example, the document root is "/web/www.domain.com/docs/".
</para>
<para>
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/".
</para>
<note>
<title>Technical Note</title>
<para>
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.
</para>
</note>
<para>
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".
</para>
<note>
<title>Technical Note</title>
<para>
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.)
</para>
</note>
<para>
Lets take a look at the file structure so far:
</para> </para>
<example> <example>
<title>Example file structure</title> <title>Example file structure</title>
<screen> <screen>
/usr/local/lib/php/Smarty/Smarty.class.php /php/includes/Smarty/Smarty.class.php
/usr/local/lib/php/Smarty/Smarty_Compiler.class.php /php/includes/Smarty/Smarty_Compiler.class.php
/usr/local/lib/php/Smarty/Config_File.class.php /php/includes/Smarty/Config_File.class.php
/usr/local/lib/php/Smarty/plugins/*.php /php/includes/Smarty/debug.tpl
/php/includes/Smarty/plugins/*.php
/web/www.mydomain.com/smarty/templates/ /web/www.mydomain.com/smarty/guestbook/templates/
/web/www.mydomain.com/smarty/templates_c/ /web/www.mydomain.com/smarty/guestbook/templates_c/
/web/www.mydomain.com/smarty/configs/ /web/www.mydomain.com/smarty/guestbook/configs/
/web/www.mydomain.com/smarty/cache/ /web/www.mydomain.com/smarty/guestbook/cache/
/web/www.mydomain.com/docs/myapp/index.php</screen> /web/www.mydomain.com/docs/guestbook/index.php</screen>
</example> </example>
<para> <para>
Smarty will need write access to the $compile_dir and $cache_dir, so be sure 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 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". 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.
</para> </para>
<example> <example>
<title>Setting file permissions</title> <title>Setting file permissions</title>
<screen> <screen>
chown nobody:nobody /web/www.mydomain.com/smarty/templates_c/ 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/ 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/</screen>
/web/www.mydomain.com/docs/index.php</screen>
</example> </example>
<note>
<title>Technical Note</title>
<para> <para>
In this example, index.php is in our document root under the subdirectory chmod 770 will be fairly tight security, it only allows user "nobody" and
"myapp". Lets edit this file and call a Smarty template. 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.
</para>
</note>
<para>
We need to create the index.tpl file that Smarty will load. This will be
located in your $template_dir.
</para> </para>
<example> <example>
<title>Editing index.php</title> <title>Editing /web/www.mydomain.com/smarty/templates/index.tpl</title>
<screen> <screen>
// contents of /web/www.mydomain.com/docs/myapp/index.php {* Smarty *}
Hello, {$name}!</screen>
</example>
<para>
Now lets edit index.php. We'll create an instance of Smarty, assign a
template variable and display the index.tpl file.
</para>
<example>
<title>Editing /web/www.mydomain.com/docs/guestbook/index.php</title>
<screen>
define(SMARTY_DIR,'/usr/local/lib/php/Smarty/'); define(SMARTY_DIR,'/usr/local/lib/php/Smarty/');
require(SMARTY_DIR.'Smarty.class.php'); require(SMARTY_DIR.'Smarty.class.php');
$smarty = new Smarty; $smarty = new Smarty;
/* $smarty->template_dir = '/web/www.mydomain.com/smarty/guestbook/templates/';
NOTE: the following four lines do not need to be set if $smarty->compile_dir = '/web/www.mydomain.com/smarty/guestbook/templates_c/';
/web/www.mydomain.com/smarty/ is in your include_path. $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->assign('name','Ned');
$smarty->compile_dir = '/web/www.mydomain.com/smarty/templates_c/';
$smarty->config_dir = '/web/www.mydomain.com/smarty/configs/'; $smarty->display('index.tpl');</screen>
$smarty->cache_dir = '/web/www.mydomain.com/smarty/cache/'; </example>
<note>
<title>Technical Note</title>
<para>
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.
</para>
</note>
<para>
Now load the index.php file from your web browser. You should see "Hello,
Ned!"
</para>
<para>
You have completed the basic setup for Smarty!
</para>
</sect1>
<sect1 id="installing.smarty.extended">
<title>Extended Installation</title>
<para>
This is a continuation of the <link
linkend="installing.smarty.basic">basic installation</link>, please read
that first!
</para>
<para>
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".
</para>
<example>
<title>Editing /php/includes/guestbook/setup.php</title>
<screen>
// load Smarty library files
define(SMARTY_DIR,'/usr/local/lib/php/Smarty/');
require(SMARTY_DIR.'Smarty.class.php');
// load application library files
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');
}
}</screen>
</example>
<note>
<title>Technical Note</title>
<para>
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.
</para>
</note>
<para>
Now lets alter the index.php file to use setup.php:
</para>
<example>
<title>Editing /web/www.mydomain.com/docs/guestbook/index.php</title>
<screen>
require('guestbook/setup.php');
$smarty = new Smarty_GuestBook;
$smarty->assign('name','Ned');
$smarty->display('index.tpl');</screen> $smarty->display('index.tpl');</screen>
</example> </example>
<para> <para>
Before we execute this, we need to create the index.tpl file that Smarty will Now you see it is quite simple to bring up an instance of Smarty, just use
load. This will be located in your $template_dir. Smarty_GuestBook which automatically initializes everything for our application.
</para>
<example>
<title>Editing index.tpl</title>
<screen>
{* contents of /web/www.mydomain.com/smarty/templates/index.tpl *}
Hello World!</screen>
</example>
<para>
Now load the index.php file from your web browser. You should see "Hello
World!" That's it for the basic setup for Smarty!
</para> </para>
</sect1> </sect1>

14
docs/programmers.sgml
View File

@@ -78,18 +78,13 @@
included templates and assigned variables for the current included templates and assigned variables for the current
template page. template page.
</para> </para>
<para>
NOTE: This was added to Smarty 1.4.3.
</para>
</sect1> </sect1>
<sect1 id="variable.debug.tpl"> <sect1 id="variable.debug.tpl">
<title>$debug_tpl</title> <title>$debug_tpl</title>
<para> <para>
This is the name of the template file used for the debugging This is the name of the template file used for the debugging console. By
console. default, it is named debug.tpl and is located in the <link
</para> linkend="constant.smarty.dir">SMARTY_DIR</link>.
<para>
NOTE: This was added to Smarty 1.4.3.
</para> </para>
</sect1> </sect1>
<sect1 id="variable.debugging.ctrl"> <sect1 id="variable.debugging.ctrl">
@@ -101,9 +96,6 @@
for that invocation of the script. If $debugging is true, this for that invocation of the script. If $debugging is true, this
value is ignored. value is ignored.
</para> </para>
<para>
NOTE: This was added to Smarty 1.4.4.
</para>
</sect1> </sect1>
<sect1 id="variable.global.assign"> <sect1 id="variable.global.assign">
<title>$global_assign</title> <title>$global_assign</title>