smarty/FAQ

GENERAL
-------

Q: What is Smarty?
A: Smarty is a template engine for PHP... but be aware this isn't just another
   PHP template engine. It's much more than that.

Q: What's the difference between Smarty and other template engines?
A: Most other template engines for PHP provide basic variable substitution and
   dynamic block functionality. Smarty takes a step further to be a "smart"
   template engine, adding features such as configuration files, template
   functions, variable modifiers (see the docs!) and making all of this
   functionality as easy as possible to use for both programmers and template
   designers. Smarty also compiles the templates into PHP scripts, eliminating
   the need to parse the templates on every invocation, making Smarty extremely
   scalable and managable for large application needs.

Q: What do you mean "Compiled PHP Scripts" ?
A: Smarty reads the template files and creates PHP scripts from them. Once
   these PHP scripts are created, Smarty executes these, never having to parse
   the template files again. If you change a template file, Smarty will
   recreate the PHP script for it. All this is done automatically by Smarty.
   Template designers never need to mess with the generated PHP scripts or even
   know of their existance. (NOTE: you can turn off this compile checking step
   in Smarty for increased performance.)

Q: Why can't I just use APC <http://apc.communityconnect.com/> (or Zend Cache)?
A: You certainly can. Smarty's cache and these cache solutions have nothing in
   common. What APC does is caches compiled bytecode of your PHP scripts in
   shared memory or in a file. This speeds up server response and saves the
   compilation step. Smarty creates PHP scripts (which APC will cache nicely)
   and also has it's own internal caching mechanism for the output of the
   template contents. For example, if you have a template that requires several
   database queries, Smarty can cache this output, saving the need to call the
   database every time. APC cannot help you here. Smarty and APC (or Zend
   Cache) actually complement each other nicely. If performance is of the
   utmost importance, we would recommend using one of these with any PHP
   application, using Smarty or not.

Q: Why does smarty have a built in cache? Wouldn't it be better to handle this
   in a separate class?
A: Smarty's caching functionality is tightly integrated with the template
   engine, making it quite a bit more flexible than a simple caching wrapper.
   For instance, you can cache select portions of a template page. Let's say
   you have a polling box on your site. With Smarty, you can leave the poll
   dynamic and cache the rest of the page. You can also pass templates
   multiple cache ids, meaning that a template can have several caches
   depending on URL, cookies, etc.

Q: Is Smarty faster than <insert other PHP template engine>?
A: It could be. One of the strengths of Smarty is that it does not need to
   parse the template files on every hit to the server. Version 1.3.1 has
   many noticable performance tune-ups, so your best bet is to try some
   benchmarks and compare for yourself.

   The above comparison assumes that you are not using Smarty's built-in
   ability to cache templates. If you are, that makes this comparison pretty
   unfair since Smarty will basically be displaying static content instead of
   generating templates, which will really speed things up especially for
   complicated tests.

Q: How can I be sure to get the best performance from Smarty?
A: Be sure you set $compile_check=false once your templates are initially
   compiled. This will skip the unneeded step of testing if the template has
   changed since it was last compiled. If you have complex pages that don't
   change too often, turn on the caching engine and adjust your application so
   it doesn't do unnecessary work (like db calls) if a cached page is
   available. See the documentation for examples.
   
Q: Can I use Macromedia's Dreamweaver to edit my templates?
A: Certainly. You might want to change your tag delimiters from {} to something
   that resembles valid HTML, like <!--{ }--> or <{ }> or something similar.
   This way the editor won't view the template tags as errors.
   
Q: Do you have a mailing list?
A: Yes. Subscribe by sending an e-mail to subscribe-smarty@lists.ispi.net. This
   is also archived at http://marc.theaimsgroup.com/?l=smarty&r=1&w=2


TROUBLESHOOTING
---------------

Q: Smarty doesn't work.
A: You must be using PHP 4.0.4pl1 or later to fix all known problems
   Smarty has with PHP. Read the BUGS file for more info.

Q: I get the following error when running Smarty:
   Warning: Wrong parameter count for preg_replace() in
   Smarty.class.php on line 371
A: preg_replace had a parameter added in PHP 4.0.2 that Smarty
   requires. Upgrade to at least 4.0.4pl to fix all known PHP issues with
   Smarty.

Q: I get the following error when running Smarty:
   Fatal error: Failed opening required 'PEAR.php'
   (include_path='') in Config_File.class.php on line 3
A: Smarty uses the PEAR libraries for some of its error handling routines.
   PEAR libraries come with the distribution of PHP. Be sure that the path to
   these libraries is included in your php include_path. Unix users check
   /usr/local/lib/php. Windows users check C:\php\pear. You may also need to
   change the filename from PEAR.php.in to PEAR.php (windows distribution)
   Example entry in php.ini:
   (unix) include_path=".:/usr/local/lib/php"
   (windows) include_path=".;\php\pear"

Q: I get this error when passing variables to {include}:
   Fatal error: Call to undefined function: get_defined_vars() in
   /path/to/Smarty/templates_c/index.tpl.php on line 8
A: get_defined_vars() was added to PHP 4.0.4. If you plan on passing
   variables to included templates, you will need PHP 4.0.4 or later.

Q: I get PHP errors in my {if} tag logic.
A: All conditional qualifiers must be separated by spaces. This syntax will not
   work: {if $name=="Wilma"} You must instead do this: {if $name == "Wilma"}.
   The reason for this is syntax ambiguity. Both "==" and "eq" are equivalent
   in the template parser, so something like {if $nameeq"Wilma"} wouldn't be
   parsable by the tokenizer.

Q: I'm changing my php code and/or templates, and my results are not getting
   updated.
A: This may be the result of your compile or cache settings. If you are
   changing your php code, your templates will not necessarily get recompiled
   to reflect the changes. Use $force_compile during develpment to avoid these
   situations. Also turn off caching during development when you aren't
   specifically testing it. You can also remove everything from your
   compile_dir and cache_dir and reload the page to be sure everything gets
   regenerated.

Q: I'm running Windows 2000 and I get blank content. My compiled PHP files are
   also zero length.
A: There seems to be a problem with some W2k machines and exclusive file
   locking. Comment out the flock() call in _write_file to get around this,
   although be aware this could possibly cause a problem with simultaneous
   writes to a file, especially with caching turned on. NOTE: As of Smarty
   1.4.0, a workaround was put in place that should solve this.

Q: The template goes into an infinite loop when I include included templates
   that pass local variables
A: This was fixed in 1.3.2 (new global attribute)

Q: My ISP did not setup the PEAR repository, nor will they set it up. How do I
   make Smarty run without it?
A: The easiest thing to do is grab all of PEAR and install it locally for your
   own use. There's nothing that says PEAR must be installed in its default
   directory. There won't be a version of Smarty that runs without PEAR, as it
   dependant on it, and may become moreso in the future.