\$use_include_path {#variable.use.include.path}

This tells smarty to respect the include_path within the File Template Resource handler and the plugin loader to resolve the directories known to $template_dir. The flag also makes the plugin loader check the include_path for $plugins_dir.

Note

You should not design your applications to rely on the include_path, as this may - depending on your implementation - slow down your system (and Smarty) considerably.

If use_include_path is enabled, file discovery for $template_dir and $plugins_dir work as follows.

For each element $directory in array (\$template_dir or \$plugins_dir) do
Test if requested file is in $directory relative to the current working directory. If file found, return it.
For each $path in include_path do
Test if requested file is in $directory relative to the $path (possibly relative to the current working directory). If file found, return it.
Try default_handler or fail.

This means that whenever a directory/file relative to the current working directory is encountered, it is preferred over anything potentially accessible through the include_path.

Note

Smarty does not filter elements of the include_path. That means a \".:\" within your include path will trigger the current working directory lookup twice.