Plates Template System

Plates is a native PHP template system designed for developers who prefer using native PHP instead of learning a new compiled template language (like Twig or Smarty). It is framework-agnostic, Composer-ready, and PSR-2 compliant.

Key characteristics include:

• Native PHP: Uses standard PHP syntax within templates, meaning no new language syntax to learn.
• Template System, not Language: It provides a system to manage templates rather than introducing a proprietary language.
• Extensibility: Easily extended via functions and extensions.
• Decoupled Design: Makes templates easy to test and works with any PHP project.

Plates is a native PHP template system designed for developers who prefer using native PHP instead of learning a new compiled template language like Twig or Smarty. It is framework-agnostic, Composer-ready, and PSR-2 compliant.

Key features include:

• Native PHP templates: No new syntax to learn; use standard PHP code.
• Template Inheritance: Increase code reuse with layouts and inheritance.
• Namespacing: Use template folders to group templates into namespaces.
• Data Management: Support for sharing data across templates and preassigning data to specific templates.
• Extensibility: Easily extend the system using functions and extensions.
• Security: Includes built-in escaping helpers.

Plates is designed for Dependency Injection. You can pass an instance of League\Plates\Engine into your controllers or other application services via their constructors. This allows your application components to access the template engine without needing to know about file system paths or configuration details.

class Controller
{
    private $templates;

    public function __construct(League\Plates\Engine $templates)
    {
        $this->templates = $templates;
    }

    // Create a template object
    public function getIndex()
    {
        $template = $this->templates->make('home');

        return $template->render();
    }

    // Render a template directly
    public function getIndex()
    {
        return $this->templates->render('home');
    }
}

When designing a layout, you can provide default content for a section using $this->fetch('name'). This is useful for ensuring a part of your UI (like a sidebar or navigation) is never empty, even if the specific page being rendered doesn't define that section.

In your layout, you can check if a section has content using a conditional, and if not, fetch the default content:

<div id="sidebar">
    <?php if ($this->section('sidebar')): ?>
        <?=$this->section('sidebar')?>
    <?php else: ?>
        <?=$this->fetch('default-sidebar')?>
    <?php endif ?>
</div>

In Plates templates, all built-in and custom template functions are accessed via the $this pseudo-variable. This allows you to call methods directly within your template files.

<p>Hello, <?=$this->escape($name)?></p>

Sections (or blocks) allow you to capture content within a template and save it for use elsewhere (e.g., in a layout template) instead of rendering it immediately.

1. Define a section: Use $this->start('name') to begin capturing content and $this->stop() to end it.
2. Retrieve content: Use $this->section('name') to output the captured content. This can be used in both the current template and the layout template.

<?php $this->start('welcome') ?>

    <h1>Welcome!</h1>
    <p>Hello <?=$this->e($name)?></p>

<?php $this->stop() ?>

<!-- In another template or layout -->
<?=$this->section('welcome')?>

Themes and Folders are distinct features and should not be used interchangeably:

• Themes: Fallback logic is implicit. All template names are automatically resolved and checked against the entire hierarchy (from last child to first parent).
• Folders: Fallback logic is opt-in. You must explicitly prefix the template name with the folder name to access it.

Creating an engine with a single theme is functionally equivalent to using a single directory with no folders.

Extensions can interact with the core Plates objects:

1. Engine: The Engine instance is automatically passed as an argument to the register(Engine $engine) method.
2. Template: The Template object is automatically assigned as a parameter to every function call made by the extension. To access it, you must define a public property named $template on your extension class.

use League\Plates\Engine;
use League\Plates\Extension\ExtensionInterface;

class MyExtension implements ExtensionInterface
{
    protected $engine;
    public $template; // must be public

    public function register(Engine $engine)
    {
        $this->engine = $engine;

        // Access template data:
        $data = $this->template->data();

        // Register functions
        // ...
    }
}

Plates provides several features to manage template logic and organization:

• Layouts and Inheritance: Increase code reuse through template layouts and inheritance models.
• Template Folders: Group templates into namespaces using folders.
• Data Management: Share data across templates or preassign specific data to individual templates.
• Escaping: Includes built-in escaping helpers for security.
• Extensibility: Supports adding custom functions and extensions to the engine.

To use Plates, instantiate the League\Plates\Engine class by providing the absolute path to your templates directory. You can then render templates using the render() method, passing the template filename (without the .php extension) and an associative array of data to be used within the template.

// Create new Plates instance
$templates = new League\Plates\Engine('/path/to/templates');

// Render a template
echo $templates->render('profile', ['name' => 'Jonathan']);