smarty-php/smarty
1
0
Fork 0
mirror of https://github.com/smarty-php/smarty.git synced 2025-07-29 15:37:14 +02:00
Code Issues Packages Projects Releases Wiki Activity

Improve the documentation, bringing it up to date with PHP7/8 and Smarty 4 and providing

Browse Source 
a more logical introduction and getting started experience.
This commit is contained in:
Simon Wisselink
2021-12-03 16:51:08 +01:00
parent 3a91df797e
commit cb5efd04c3
9 changed files with 413 additions and 635 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
README.md
View File

@ -17,12 +17,4 @@ To get the latest stable version of Smarty use:
composer require smarty/smarty
````
To get the latest, unreleased version, use:
```bash
composer require smarty/smarty:dev-master
````
To get the previous stable version of Smarty, Smarty 3, use:
```bash
composer require smarty/smarty:^3
````
More in the [Getting Started](./docs/getting-started.md) section of the docs.

13
docs/designers/language-basic-syntax.md
View File

@ -1,6 +1,18 @@
Basic Syntax
============
A simple Smarty template could look like this:
```html
<h1>{$title|escape}</h1>
<ul>
{foreach $cities as $city}
<li>{$city.name|escape} ({$city.population})</li>
{foreachelse}
<li>no cities found</li>
{/foreach}
</ul>
```
All Smarty template tags are enclosed within delimiters. By default
these are `{` and `}`, but they can be
[changed](../programmers/api-variables/variable-left-delimiter.md).
@ -11,6 +23,7 @@ displayed as static content, or unchanged. When Smarty encounters
template tags, it attempts to interpret them, and displays the
appropriate output in their place.
The basis components of the Smarty syntax are:
- [Comments](./language-basic-syntax/language-syntax-comments.md)
- [Variables](./language-basic-syntax/language-syntax-variables.md)
- [Functions](./language-basic-syntax/language-syntax-functions.md)

1
docs/designers/language-builtin-functions.md
View File

@ -21,7 +21,6 @@ Built-in Functions {#language.builtin.functions}
- [{ldelim},{rdelim}](./language-builtin-functions/language-function-ldelim.md)
- [{literal}](./language-builtin-functions/language-function-literal.md)
- [{nocache}](./language-builtin-functions/language-function-nocache.md)
- [{php}](./language-builtin-functions/language-function-php.md)
- [{section},{sectionelse}](./language-builtin-functions/language-function-section.md)
- [{setfilter}](./language-builtin-functions/language-function-setfilter.md)
- [{strip}](./language-builtin-functions/language-function-strip.md)

45
docs/designers/language-builtin-functions/language-function-php.md
View File

@ -1,45 +0,0 @@
{php} {#language.function.php}
=====
> **Note**
>
> `{php}` tags are deprecated from Smarty, and should not be used. Put
> your PHP logic in PHP scripts or plugin functions instead.
> **Note**
>
> As of Smarty 3.1 the `{php}` tags are only available from
> [SmartyBC](#bc).
The `{php}` tags allow PHP code to be embedded directly into the
template. They will not be escaped, regardless of the
[`$php_handling`](#variable.php.handling) setting.
{php}
// including a php script directly from the template.
include('/path/to/display_weather.php');
{/php}
{* this template includes a {php} block that assign's the variable $varX *}
{php}
global $foo, $bar;
if($foo == $bar){
echo 'This will be sent to browser';
}
// assign a variable to Smarty
$this->assign('varX','Toffee');
{/php}
{* output the variable *}
<strong>{$varX}</strong> is my fav ice cream :-)
See also [`$php_handling`](#variable.php.handling),
[`{include_php}`](#language.function.include.php),
[`{include}`](#language.function.include),
[`{insert}`](#language.function.insert) and [componentized
templates](#tips.componentized.templates).

152
docs/features.md Normal file
View File

@ -0,0 +1,152 @@
Features
=======
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](#variable.compile.check) only the
template files that have changed.
- You can easily create your own custom
[functions](#language.custom.functions) and [variable
modifiers](#language.modifiers), so the template language is
extremely extensible.
- Configurable template [{delimiter}](#variable.left.delimiter) tag
syntax, so you can use `{$foo}`, `{{$foo}}`, `<!--{$foo}-->`, etc.
- The [`{if}..{elseif}..{else}..{/if}`](#language.function.if)
constructs are passed to the PHP parser, so the `{if...}` expression
syntax can be as simple or as complex an evaluation as you like.
- Allows unlimited nesting of
[`sections`](#language.function.section), `if's` etc.
- Built-in [caching](#caching) support
- Arbitrary [template](#resources) sources
- [Template Inheritance](#advanced.features.template.inheritance) for
easy management of template content.
- [Plugin](#plugins) architecture
## Seperation of presentation from application code
- This means templates can certainly contain logic under the condition
that it is for presentation only. Things such as
[including](./designers/language-builtin-functions/language-function-include.md) other templates,
[alternating](./designers/language-custom-functions/language-function-cycle.md) table row colors,
[upper-casing](./designers/language-modifiers/language-modifier-upper.md) a variable,
[looping](./designers/language-builtin-functions/language-function-foreach.md) over an array of data and
rendering it are examples of presentation logic.
- This does not mean however that Smarty forces a separation of
business and presentation logic. Smarty has no knowledge of which is
which, so placing business logic in the template is your own doing.
- Also, if you desire *no* logic in your templates you certainly can
do so by boiling the content down to text and variables only.
## How does it work?
Under the hood, Smarty "compiles" (basically copies and converts) the
templates into PHP scripts. This happens once when each template is
first invoked, and then the compiled versions are used from that point
forward. Smarty takes care of this for you, so the template designer
just edits the Smarty templates and never has to manage the compiled
versions. This approach keeps the templates easy to maintain, and yet
keeps execution times extremely fast since the compiled code is just
PHP. And of course, all PHP scripts take advantage of PHP op-code caches
such as APC.
## Template Inheritance
Template inheritance was introduced in Smarty 3. Before template
inheritance, we managed our templates in
pieces such as header and footer templates. This organization lends
itself to many problems that require some hoop-jumping, such as managing
content within the header/footer on a per-page basis. With template
inheritance, instead of including other templates we maintain our
templates as single pages. We can then manipulate blocks of content
within by inheriting them. This makes templates intuitive, efficient and
easy to manage. See
[Template Inheritance](./programmers/advanced-features/advanced-features-template-inheritance.md)
for more info.
## Why not use XML/XSLT syntax?
There are a couple of good reasons. First, Smarty can be used for more
than just XML/HTML based templates, such as generating emails,
javascript, CSV, and PDF documents. Second, XML/XSLT syntax is even more
verbose and fragile than PHP code! It is perfect for computers, but
horrible for humans. Smarty is about being easy to read, understand and
maintain.
## Template Security
Although Smarty insulates you from PHP, you still have the option to use
it in certain ways if you wish. Template security forces the restriction
of PHP (and select Smarty functions.) This is useful if you have third
parties editing templates, and you don't want to unleash the full power
of PHP or Smarty to them.
## Integration
Sometimes Smarty gets compared to Model-View-Controller (MVC)
frameworks. Smarty is not an MVC, it is just the presentation layer,
much like the View (V) part of an MVC. As a matter of fact, Smarty can
easily be integrated as the view layer of an MVC. Many of the more
popular ones have integration instructions for Smarty, or you may find
some help here in the forums and documentation.
## Other Template Engines
Smarty is not the only engine following the *"Separate Programming Code
from Presentation"* philosophy. For instance, Python has template
engines built around the same principles such as Django Templates and
CheetahTemplate. *Note: Languages such as Python do not mix with HTML
natively, which give them the advantage of proper programming code
separation from the outset. There are libraries available to mix Python
with HTML, but they are typically avoided.*
## What Smarty is Not
Smarty is not an application development framework. Smarty is not an
MVC. Smarty is not an alternative to Laravel, Symfony, CodeIgniter,
or any of the other application development frameworks for PHP.
Smarty is a template engine, and works as the (V)iew component of your
application. Smarty can easily be coupled to any of the engines listed
above as the view component. No different than any other software,
Smarty has a learning curve. Smarty does not guarantee good application
design or proper separation of presentation, this still needs to be
addressed by a competent developer and web designer.
## Is Smarty Right for Me?
Smarty is not meant to be a tool for every job. The important thing is
to identify if Smarty fits your needs. There are some important
questions to ask yourself:
### Template Syntax
Are you content with PHP tags mixed with HTML? Are your
web designers comfortable with PHP? Would your web designers prefer a
tag-based syntax designed for presentation? Some experience working with
both Smarty and PHP helps answer these questions.
### The Business Case
Is there a requirement to insulate the templates from
PHP? Do you have untrusted parties editing templates that you do not
wish to unleash the power of PHP to? Do you need to programmatically
control what is and is not available within the templates? Smarty
supplies these capabilities by design.
## Feature set
Does Smarty's features such as caching, template
inheritance and plugin architecture save development cycles writing code
that would be needed otherwise? Does the codebase or framework you plan
on using have the features you need for the presentation component?
## Sites using Smarty
Many well-known PHP projects make use of Smarty such as XOOPS CMS, CMS Made Simple, Tiki
CMS/Groupware and X-Cart to name a few.
## Summary
Whether you are using Smarty for a small website or massive enterprise
solution, it can accommodate your needs. There are numerous features
that make Smarty a great choice:
- separation of PHP from HTML/CSS just makes sense
- readability for organization and management
- security for 3rd party template access
- feature completeness, and easily extendable to your own needs
- massive user base, Smarty is here to stay
- LGPL license for commercial use
- 100% free to use, open source project

480
docs/getting-started.md
View File

@ -1,267 +1,56 @@
What is Smarty?
===============
Smarty is a template engine for PHP. More specifically, it facilitates a
manageable 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](#api.assign) into Smarty by the
application.
- Then the template designer edits the templates and uses a
combination of HTML tags and [template tags](#language.basic.syntax)
to format the presentation of these
[variables](#language.syntax.variables) with elements such as
tables, div\'s, background colors, font sizes, style sheets, svg
etc.
- One day the programmer needs to change the way the article content
is retrieved, ie 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 would require no change 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.
One design goal of Smarty is the separation of business logic and
presentation logic.
- This means templates can certainly contain logic under the condition
that it is for presentation only. Things such as
[including](#language.function.include) other templates,
[alternating](#language.function.cycle) table row colors,
[upper-casing](#language.modifier.upper) a variable,
[looping](#language.function.foreach) over an array of data and
[displaying](#api.display) it are examples of presentation logic.
- This does not mean however that Smarty forces a separation of
business and presentation logic. Smarty has no knowledge of which is
which, so placing business logic in the template is your own doing.
- Also, if you desire *no* logic in your templates you certainly can
do so by boiling the content down to text and variables only.
**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](#variable.compile.check) only the
template files that have changed.
- You can easily create your own custom
[functions](#language.custom.functions) and [variable
modifiers](#language.modifiers), so the template language is
extremely extensible.
- Configurable template [{delimiter}](#variable.left.delimiter) tag
syntax, so you can use `{$foo}`, `{{$foo}}`, `<!--{$foo}-->`, etc.
- The [`{if}..{elseif}..{else}..{/if}`](#language.function.if)
constructs are passed to the PHP parser, so the `{if...}` expression
syntax can be as simple or as complex an evaluation as you like.
- Allows unlimited nesting of
[`sections`](#language.function.section), `if's` etc.
- Built-in [caching](#caching) support
- Arbitrary [template](#resources) sources
- [Template Inheritance](#advanced.features.template.inheritance) for
easy management of template content.
- [Plugin](#plugins) architecture
Installation
============
Requirements {#installation.requirements}
============
Smarty requires a web server running PHP 5.2 or greater.
Basic Installation {#installing.smarty.basic}
==================
Install the Smarty library files which are in the `/libs/` sub directory
of the distribution. These are `.php` files that you SHOULD NOT edit.
They are shared among all applications and only get changed when you
upgrade to a new version of Smarty.
In the examples below the Smarty tarball has been unpacked to:
- `/usr/local/lib/Smarty-v.e.r/` for \*nix machines
- and `c:\webroot\libs\Smarty-v.e.r\` for the windows environment.
<!-- -->
Smarty-v.e.r/
libs/
Smarty.class.php
debug.tpl
sysplugins/* (everything)
plugins/* (everything)
Smarty uses a PHP [constant](&url.php-manual;define) named
[`SMARTY_DIR`](#constant.smarty.dir) which is the **full system file
path** to the Smarty `libs/` directory. Basically, if your application
can find the `Smarty.class.php` file, you do not need to set the
[`SMARTY_DIR`](#constant.smarty.dir) as Smarty will figure it out on its
own. Therefore, if `Smarty.class.php` is not in your
[include\_path](&url.php-manual;ini.core.php#ini.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/**.
::: {.informalexample}
Here\'s how you create an instance of Smarty in your PHP scripts:
<?php
// NOTE: Smarty has a capital 'S'
require_once('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 need to do one of the
following:
<?php
// *nix style (note capital 'S')
define('SMARTY_DIR', '/usr/local/lib/Smarty-v.e.r/libs/');
// windows style
define('SMARTY_DIR', 'c:/webroot/libs/Smarty-v.e.r/libs/');
// hack version example that works on both *nix and windows
// Smarty is assumend to be in 'includes/' dir under current script
define('SMARTY_DIR',str_replace("\\","/",getcwd()).'/includes/Smarty-v.e.r/libs/');
require_once(SMARTY_DIR . 'Smarty.class.php');
$smarty = new Smarty();
?>
<?php
// *nix style (note capital 'S')
require_once('/usr/local/lib/Smarty-v.e.r/libs/Smarty.class.php');
// windows style
require_once('c:/webroot/libs/Smarty-v.e.r/libs/Smarty.class.php');
$smarty = new Smarty();
?>
;;;;;;;;;;;;;;;;;;;;;;;;;
; Paths and Directories ;
;;;;;;;;;;;;;;;;;;;;;;;;;
; *nix: "/path1:/path2"
include_path = ".:/usr/share/php:/usr/local/lib/Smarty-v.e.r/libs/"
; Windows: "\path1;\path2"
include_path = ".;c:\php\includes;c:\webroot\libs\Smarty-v.e.r\libs\"
<?php
// *nix
ini_set('include_path', ini_get('include_path').PATH_SEPARATOR.'/usr/local/lib/Smarty-v.e.r/libs/');
// windows
ini_set('include_path', ini_get('include_path').PATH_SEPARATOR.'c:/webroot/lib/Smarty-v.e.r/libs/');
?>
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`](#variable.template.dir),
[`$compile_dir`](#variable.compile.dir),
[`$config_dir`](#variable.config.dir), and
[`$cache_dir`](#variable.cache.dir) respectively
- It is highly recommended that you setup a separate set of these
directories for each application that will use Smarty
- You can verify if your system has the correct access rights for
these directories with [`testInstall()`](#api.test.install).
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 application.
/usr/local/lib/Smarty-v.e.r/libs/
Smarty.class.php
debug.tpl
sysplugins/*
plugins/*
/web/www.example.com/
guestbook/
templates/
index.tpl
templates_c/
configs/
cache/
htdocs/
index.php
Be sure that you know the location of your web server\'s document root
as a file path. In the following examples, the document root is
`/web/www.example.com/guestbook/htdocs/`. 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
(but not mandatory) to place these directories *outside* of the web
server\'s document root.
You will need as least one file under your document root, and that is
the script accessed by the web browser. We will name our script
`index.php`, and place it in a subdirectory under the document root
`/htdocs/`.
Smarty will need **write access** (windows users please ignore) to the
[`$compile_dir`](#variable.compile.dir) and
[`$cache_dir`](#variable.cache.dir) directories (`templates_c/` and
`cache/`), so be sure the web server user account can write to them.
==============
## Requirements
Smarty can be run with PHP 7.1 to PHP 8.0.
## Installation
Smarty versions 3.1.11 or later can be installed with [Composer](https://getcomposer.org/).
To get the latest stable version of Smarty use:
```bash
composer require smarty/smarty
````
To get the latest, unreleased version, use:
```bash
composer require smarty/smarty:dev-master
````
To get the previous stable version of Smarty, Smarty 3, use:
```bash
composer require smarty/smarty:^3
````
Here's how you create an instance of Smarty in your PHP scripts:
```php
<?php
require 'vendor/autoload.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`](./programmers/api-variables/variable-template-dir.md),
[`configs`](./programmers/api-variables/variable-config-dir.md),
[`templates_c`](./programmers/api-variables/variable-compile-dir.md)
and
[`cache`](./programmers/api-variables/variable-cache-dir.md)
relative to the current working directory.
The defaults can be changed as follows:
```php
$smarty = new Smarty();
$smarty->setTemplateDir('/some/template/dir');
$smarty->setConfigDir('/some/config/dir');
$smarty->setCompileDir('/some/compile/dir');
$smarty->setCacheDir('/some/cache/dir');
```
The compile dir and cache dir need to be writable for the user running the PHP script.
> **Note**
>
@ -270,66 +59,62 @@ Smarty will need **write access** (windows users please ignore) to the
> can look in your `httpd.conf` file to see what user and group are
> being used.
```bash
chown nobody:nobody /web/www.example.com/guestbook/templates_c/
chmod 770 /web/www.example.com/guestbook/templates_c/
chown nobody:nobody /web/www.example.com/guestbook/templates_c/
chmod 770 /web/www.example.com/guestbook/templates_c/
chown nobody:nobody /web/www.example.com/guestbook/cache/
chmod 770 /web/www.example.com/guestbook/cache/
```
chown nobody:nobody /web/www.example.com/guestbook/cache/
chmod 770 /web/www.example.com/guestbook/cache/
You can verify if your system has the correct access rights for
these directories with [`testInstall()`](./programmers/api-functions/api-test-install.md):
```php
$smarty = new Smarty();
$smarty->setTemplateDir('/some/template/dir');
$smarty->setConfigDir('/some/config/dir');
$smarty->setCompileDir('/some/compile/dir');
$smarty->setCacheDir('/some/cache/dir');
$smarty->testInstall();
```
Now, let's create the `index.tpl` file that Smarty will display. This
needs to be located in the [`$template_dir`](./programmers/api-variables/variable-template-dir.md).
```html
{* Smarty *}
Hello {$name}, welcome to Smarty!
```
> **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 display. This
needs to be located in the [`$template_dir`](#variable.template.dir).
{* Smarty *}
Hello {$name}, welcome to Smarty!
> **Note**
>
> `{* Smarty *}` is a template [comment](#language.syntax.comments). It
> `{* Smarty *}` is a template [comment](./designers/language-basic-syntax/language-syntax-comments.md). 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()`](#api.assign) a template variable and
[`display()`](#api.display) the `index.tpl` file.
Now lets edit our php file. We'll create an instance of Smarty,
[`assign()`](./programmers/api-functions/api-assign.md) a template variable and
[`display()`](./programmers/api-functions/api-display.md) the `index.tpl` file.
```php
<?php
<?php
require 'vendor/autoload.php';
require_once(SMARTY_DIR . 'Smarty.class.php');
$smarty = new Smarty();
$smarty = new Smarty();
$smarty->setTemplateDir('/web/www.example.com/guestbook/templates/');
$smarty->setCompileDir('/web/www.example.com/guestbook/templates_c/');
$smarty->setConfigDir('/web/www.example.com/guestbook/configs/');
$smarty->setCacheDir('/web/www.example.com/guestbook/cache/');
$smarty->setTemplateDir('/web/www.example.com/guestbook/templates/');
$smarty->setCompileDir('/web/www.example.com/guestbook/templates_c/');
$smarty->setConfigDir('/web/www.example.com/guestbook/configs/');
$smarty->setCacheDir('/web/www.example.com/guestbook/cache/');
$smarty->assign('name', 'Ned');
$smarty->display('index.tpl');
$smarty->assign('name','Ned');
//** un-comment the following line to show the debug console
//$smarty->debugging = true;
$smarty->display('index.tpl');
?>
```
> **Note**
>
@ -340,78 +125,45 @@ Now lets edit `index.php`. We\'ll create an instance of Smarty,
> absolute paths. This ensures that Smarty is getting files from the
> directories you intended.
Now navigate to the `index.php` file with the web browser. You should
see *\"Hello Ned, welcome to Smarty!\"*
Now, run your PHP file. You should see *\"Hello Ned, welcome to Smarty!\"*
You have completed the basic setup for Smarty!
Extended Setup {#installing.smarty.extended}
## Extended Setup {#installing.smarty.extended}
==============
This is a continuation of the [basic
installation](#installing.smarty.basic), please read that first!
A slightly more flexible way to setup Smarty is to [extend the
class](&url.php-manual;ref.classobj) and initialize your Smarty
A slightly more flexible way to setup Smarty is to extend the Smarty
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.
```php
<?php
class Smarty_GuestBook extends Smarty {
<?php
public function __construct()
{
parent::__construct();
// load Smarty library
require('Smarty.class.php');
$this->setTemplateDir('/web/www.example.com/guestbook/templates/');
$this->setCompileDir('/web/www.example.com/guestbook/templates_c/');
$this->setConfigDir('/web/www.example.com/guestbook/configs/');
$this->setCacheDir('/web/www.example.com/guestbook/cache/');
// 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');
$this->caching = Smarty::CACHING_LIFETIME_CURRENT;
$this->assign('app_name', 'Guest Book');
}
class Smarty_GuestBook extends Smarty {
}
```
function __construct()
{
// Class Constructor.
// These automatically get set with each new instance.
parent::__construct();
$this->setTemplateDir('/web/www.example.com/guestbook/templates/');
$this->setCompileDir('/web/www.example.com/guestbook/templates_c/');
$this->setConfigDir('/web/www.example.com/guestbook/configs/');
$this->setCacheDir('/web/www.example.com/guestbook/cache/');
$this->caching = Smarty::CACHING_LIFETIME_CURRENT;
$this->assign('app_name', 'Guest Book');
}
}
?>
Now lets alter the `index.php` file to use `setup.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.
Now, we can use `Smarty_GuestBook` instead of `Smarty` in our scripts:
```php
$smarty = new Smarty_GuestBook();
$smarty->assign('name','Ned');
$smarty->display('index.tpl');
```

27
docs/index.md
View File

@ -1,12 +1,31 @@
# Smarty 4 Documentation
Smarty is a template engine for PHP, facilitating the separation of presentation (HTML/CSS) from application logic.
It allows you to write **templates**, using **variables**, **modifiers**, **functions** and **comments**, like this:
```html
<h1>{$title|escape}</h1>
<p>
The number of pixels is: {math equation="x * y" x=$height y=$width}.
</p>
```
When this template is rendered, with the value "Hello world" for the variable $title, 640 for $width,
and 480 for $height, the result is:
```html
<h1>Hello world</h1>
<p>
The number of pixels is: 307200.
</p>
```
## Introduction
- [Preface](./preface.md)
- [Philosophy](./philosophy.md) - or "Why do I need a template engine?"
- [Features](./features.md) - or "Why do I want Smarty?"
- [Getting Started](./getting-started.md)
## Smarty for template developers
## Smarty for template designers
- [Basic Syntax](./designers/language-basic-syntax.md)
- [Variables](./designers/language-variables.md)
- [Variable Modifiers](./designers/language-modifiers.md)
@ -27,5 +46,5 @@ Smarty is a template engine for PHP, facilitating the separation of presentation
- [Extending Smarty With Plugins](./programmers/plugins.md)
## Other
- Some random [tips & tricks](./appendixes/tips.md)
- [Some random tips & tricks](./appendixes/tips.md)
- [Troubleshooting](./appendixes/troubleshooting.md)

108
docs/philosophy.md Normal file
View File

@ -0,0 +1,108 @@
Philosophy
=======
## What is Smarty?
Smarty is a template engine for PHP. More specifically, it facilitates a
manageable 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](#api.assign) into Smarty by the
application.
- Then the template designer edits the templates and uses a
combination of HTML tags and [template tags](#language.basic.syntax)
to format the presentation of these
[variables](#language.syntax.variables) with elements such as
tables, div\'s, background colors, font sizes, style sheets, svg
etc.
- One day the programmer needs to change the way the article content
is retrieved, ie 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 would require no change 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.
## Goals
The Smarty design was largely driven by these goals:
- clean separation of presentation from application code
- PHP backend, Smarty template frontend
- complement PHP, not replace it
- fast development/deployment for programmers and designers
- quick and easy to maintain
- syntax easy to understand, no PHP knowledge necessary
- flexibility for custom development
- security: insulation from PHP
- free, open source
## Two camps of thought
When it comes to templating in PHP, there are basically two camps of
thought. The first camp exclaims that \"PHP is a template engine\". This
approach simply mixes PHP code with HTML. Although this approach is
fastest from a pure script-execution point of view, many would argue
that the PHP syntax is messy and complicated when mixed with tagged
markup such as HTML.
The second camp exclaims that presentation should be void of all
programming code, and instead use simple tags to indicate where
application content is revealed. This approach is common with other
template engines (even in other programming languages), and is also the
approach that Smarty takes. The idea is to keep the templates focused
squarely on presentation, void of application code, and with as little
overhead as possible.
## Why is separating PHP from templates important?
Two major benefits:
- SYNTAX: Templates typically consist of semantic markup such as HTML.
PHP syntax works well for application code, but quickly degenerates
when mixed with HTML. Smarty\'s simple {tag} syntax is designed
specifically to express presentation. Smarty focuses your templates
on presentation and less on \"code\". This lends to quicker template
deployment and easier maintenance. Smarty syntax requires no working
knowledge of PHP, and is intuitive for programmers and
non-programmers alike.
- INSULATION: When PHP is mixed with templates, there are no
restrictions on what type of logic can be injected into a template.
Smarty insulates the templates from PHP, creating a controlled
separation of presentation from business logic. Smarty also has
security features that can further enforce restrictions on
templates.
## Web designers and PHP
A common question: "Web designers have to learn a syntax anyway, why
not PHP?" Of course web designers can learn PHP, and they may already
be familiar with it. The issue isn't their ability to learn PHP, it is
about the consequences of mixing PHP with HTML. If designers use PHP, it
is too easy to add code into templates that doesn't belong there (you
just handed them a swiss-army knife when they just needed a knife.) You
can teach them the rules of application design, but this is probably
something they don't really need to learn (now they are developers!)
The PHP manual is also an overwhelming pile of information to sift
through. It is like handing the owner of a car the factory assembly
manual when all they need is the owners manual. Smarty gives web
designers exactly the tools they need, and gives developers fine-grained
control over those tools. The simplicity of the tag-based syntax is also
a huge welcome for designers, it helps them streamline the organization
and management of templates.

212
docs/preface.md
View File

@ -1,212 +0,0 @@
Preface
=======
**The Philosophy**
The Smarty design was largely driven by these goals:
- clean separation of presentation from application code
- PHP backend, Smarty template frontend
- complement PHP, not replace it
- fast development/deployment for programmers and designers
- quick and easy to maintain
- syntax easy to understand, no PHP knowledge necessary
- flexibility for custom development
- security: insulation from PHP
- free, open source
**What is Smarty?**
Smarty is a template engine for PHP, facilitating the separation of
presentation (HTML/CSS) from application logic. This implies that *PHP
code is application logic*, and is separated from the presentation.
**Two camps of thought**
When it comes to templating in PHP, there are basically two camps of
thought. The first camp exclaims that \"PHP is a template engine\". This
approach simply mixes PHP code with HTML. Although this approach is
fastest from a pure script-execution point of view, many would argue
that the PHP syntax is messy and complicated when mixed with tagged
markup such as HTML.
The second camp exclaims that presentation should be void of all
programming code, and instead use simple tags to indicate where
application content is revealed. This approach is common with other
template engines (even in other programming languages), and is also the
approach that Smarty takes. The idea is to keep the templates focused
squarely on presentation, void of application code, and with as little
overhead as possible.
**Why is separating PHP from templates important?**
Two major benefits:
- SYNTAX: Templates typically consist of semantic markup such as HTML.
PHP syntax works well for application code, but quickly degenerates
when mixed with HTML. Smarty\'s simple {tag} syntax is designed
specifically to express presentation. Smarty focuses your templates
on presentation and less on \"code\". This lends to quicker template
deployment and easier maintenance. Smarty syntax requires no working
knowledge of PHP, and is intuitive for programmers and
non-programmers alike.
- INSULATION: When PHP is mixed with templates, there are no
restrictions on what type of logic can be injected into a template.
Smarty insulates the templates from PHP, creating a controlled
separation of presentation from business logic. Smarty also has
security features that can further enforce restrictions on
templates.
**Web designers and PHP**
A common question: \"Web designers have to learn a syntax anyways, why
not PHP?\" Of course web designers can learn PHP, and they may already
be familiar with it. The issue isn\'t their ability to learn PHP, it is
about the consequences of mixing PHP with HTML. If designers use PHP, it
is too easy to add code into templates that doesn\'t belong there (you
just handed them a swiss-army knife when they just needed a knife.) You
can teach them the rules of application design, but this is probably
something they don\'t really need to learn (now they are developers!)
The PHP manual is also an overwhelming pile of information to sift
through. It is like handing the owner of a car the factory assembly
manual when all they need is the owners manual. Smarty gives web
designers exactly the tools they need, and gives developers fine-grained
control over those tools. The simplicity of the tag-based syntax is also
a huge welcome for designers, it helps them streamline the organization
and management of templates.
**Implementation is Important**
Although Smarty gives you the tools to make a clean separation of
presentation from application code, it also gives you plenty of room to
bend those rules. A poor implementation (i.e. injecting PHP in
templates) will cause more problems than the presentation separation was
meant to resolve. The documentation does a good job of indicating what
things to watch out for. Also see the Best Practices section of the
Smarty website.
**How does it work?**
Under the hood, Smarty \"compiles\" (basically copies and converts) the
templates into PHP scripts. This happens once when each template is
first invoked, and then the compiled versions are used from that point
forward. Smarty takes care of this for you, so the template designer
just edits the Smarty templates and never has to manage the compiled
versions. This approach keeps the templates easy to maintain, and yet
keeps execution times extremely fast since the compiled code is just
PHP. And of course, all PHP scripts take advantage of PHP op-code caches
such as APC.
**Template Inheritance**
Template inheritance is new to Smarty 3, and it\'s one of many great new
features. Before template inheritance, we managed our templates in
pieces such as header and footer templates. This organization lends
itself to many problems that require some hoop-jumping, such as managing
content within the header/footer on a per-page basis. With template
inheritance, instead of including other templates we maintain our
templates as single pages. We can then manipulate blocks of content
within by inheriting them. This makes templates intuitive, efficient and
easy to manage. See the Template Inheritance section of th Smarty
website for more info.
**Why not use XML/XSLT syntax?**
There are a couple of good reasons. First, Smarty can be used for more
than just XML/HTML based templates, such as generating emails,
javascript, CSV, and PDF documents. Second, XML/XSLT syntax is even more
verbose and fragile than PHP code! It is perfect for computers, but
horrible for humans. Smarty is about being easy to read, understand and
maintain.
**Template Security**
Although Smarty insulates you from PHP, you still have the option to use
it in certain ways if you wish. Template security forces the restriction
of PHP (and select Smarty functions.) This is useful if you have third
parties editing templates, and you don\'t want to unleash the full power
of PHP or Smarty to them.
**Integration**
Sometimes Smarty gets compared to Model-View-Controller (MVC)
frameworks. Smarty is not an MVC, it is just the presentation layer,
much like the View (V) part of an MVC. As a matter of fact, Smarty can
easily be integrated as the view layer of an MVC. Many of the more
popular ones have integration instructions for Smarty, or you may find
some help here in the forums and documentation.
**Other Template Engines**
Smarty is not the only engine following the *\"Separate Programming Code
from Presentation\"* philosophy. For instance, Python has template
engines built around the same principles such as Django Templates and
CheetahTemplate. *Note: Languages such as Python do not mix with HTML
natively, which give them the advantage of proper programming code
separation from the outset. There are libraries available to mix Python
with HTML, but they are typically avoided.*
**What Smarty is Not**
Smarty is not an application development framework. Smarty is not an
MVC. Smarty is not an alternative to Zend Framework, CodeIgniter,
PHPCake, or any of the other application development frameworks for PHP.
Smarty is a template engine, and works as the (V)iew component of your
application. Smarty can easily be coupled to any of the engines listed
above as the view component. No different than any other software,
Smarty has a learning curve. Smarty does not guarantee good application
design or proper separation of presentation, this still needs to be
addressed by a competent developer and web designer.
**Is Smarty Right for Me?**
Smarty is not meant to be a tool for every job. The important thing is
to identify if Smarty fits your needs. There are some important
questions to ask yourself:
TEMPLATE SYNTAX. Are you content with PHP tags mixed with HTML? Are your
web designers comfortable with PHP? Would your web designers prefer a
tag-based syntax designed for presentation? Some experience working with
both Smarty and PHP helps answer these questions.
THE BUSINESS CASE: Is there a requirement to insulate the templates from
PHP? Do you have untrusted parties editing templates that you do not
wish to unleash the power of PHP to? Do you need to programmatically
control what is and is not available within the templates? Smarty
supplies these capabilities by design.
FEATURE SET: Does Smarty\'s features such as caching, template
inheritance and plugin architecture save development cycles writing code
that would be needed otherwise? Does the codebase or framework you plan
on using have the features you need for the presentation component?
Templating in PHP is a hot topic, and opinions widely vary. It is
important that you understand Smarty, understand your own requirements,
and make an informed decision for yourself. You are welcome to ask
specific questions in the forums or the IRC channel.
See also the section about \"Use Cases and Work Flow\" on the Smarty
website.
**Sites using Smarty**
There are tens of thousands of unique visitors on the Smarty website
daily, mostly developers reading documentation. Many well-known PHP
projects make use of Smarty such as XOOPS CMS, CMS Made Simple, Tiki
CMS/Groupware and X-Cart to name a few.
**Summary**
Whether you are using Smarty for a small website or massive enterprise
solution, it can accommodate your needs. There are numerous features
that make Smarty a great choice:
- separation of PHP from HTML/CSS just makes sense
- readability for organization and management
- security for 3rd party template access
- feature completeness, and easily extendable to your own needs
- massive user base, Smarty is here to stay
- LGPL license for commercial use
- 100% free to use, open source project