README

Simple Template Engine is a small, simple text-based template parsing engine that works on text replacement.

Important

The master branch currently holds the work-in-progress version 3.x, which is a break from the backward compatibility promise. This will be resolved once 3.0.0 is released. Since 3.x is under development, it is not recommended to use in a production environment. The public API, implementations, etc., can (and will likely) change.

Installation

Compatible with PHP >= 8.2 and can be installed with Composer.

$ composer require esi/simple_tpl:^3.0

Usage

Storage

There are two storage implementations available: Storage\FilesystemStorage and Storage\DatabaseStorage. Both storage implementations implement the Storage\StorageInterface interface, with only one defined method: loadTemplate().

NOTE: If you wish to have a system for editing/saving, deleting or updating the templates themselves, you would need to implement this on your own. This library only searches for templates that have already been created, by name, then parses them with a key => value associative array of variables.

Filesystem Storage

The FilesystemStorage implementation allows you to use regular files for your templates. Your template files are expected to end with the .tpl extension. I plan to allow the ability to use different extensions later.

Create a FilesystemStorage instance with the path/directory to where your templates are located.
Pass this instance to the Template class when creating it.

Let's say you had a template called example_template.tpl within the ./templates/ directory.

Template file:

<!DOCTYPE HTML>
<html lang="en">
<head>
    <meta http-equiv="content-type" content="text/html" />
    <title>{title}</title>
</head>
<body>
<p>{content}</p>
</body>
</html>

PHP to parse the template:

use Esi\SimpleTpl\Template;
use Esi\SimpleTpl\Storage\FilesystemStorage;

$templateStorage = new FilesystemStorage('./templates/');
$template = new Template($templateStorage);

$template->setTplVars([
    'title' => 'Hello, World!',
    'content' => 'This is a simple template engine.'
]);

echo $template->parse('example_template');

When calling display() or parse(), you only need to provide the file name without extension. For example, if your template file is mytemplate.tpl, you would call either of these methods with mytemplate.

Database Storage

The DatabaseStorage implementation allows you to use a database for your templates.

Create a PDO instance with your database details to create a connection.
Create a DatabaseStorage instance and pass the PDO instance to it.
Pass the DatabaseStorage instance to the Template class when creating it.

Let's say the content of the example_template is the same as in the filesystem example:

use Esi\SimpleTpl\Template;
use Esi\SimpleTpl\Storage\DatabaseTemplateStorage;
use PDO;

$pdo = new PDO('mysql:host=localhost;dbname=templates', 'user', 'password');
$templateStorage = new DatabaseTemplateStorage($pdo);
$template = new Template($templateStorage);

$template->setTplVars([
    'title' => 'Hello, World!',
    'content' => 'This is a simple template engine.'
]);

echo $template->parse('example_template');

DatabaseStorage does not allow specifying custom table or field/column names. It expects a table named templates with, at minimum, two columns named name (for the template name) and content (for the template content). I plan to allow the ability to use custom table and field/column names later.

An example on how this table may be structured:

CREATE TABLE IF NOT EXISTS `templates` (
    `id` INT UNSIGNED NOT NULL AUTO_INCREMENT,
    `name` VARCHAR(255) NOT NULL,
    `content` MEDIUMTEXT NOT NULL,
    PRIMARY KEY (`id`),
    UNIQUE KEY `name` (`name`)
)

Caching

If you would like to utilize caching for templates, you will need to provide the library a PSR-6 cache implementation. You can view a list of packages that provide this implementation on Packagist.

Whether you use FilesystemStorage or DatabaseStorage, you can use caching for either by passing an object that implements \Psr\Cache\CacheItemPoolInterface.

For example:

$ composer require symfony/cache:^7.2

use Esi\SimpleTpl\Template;
use Esi\SimpleTpl\Storage\FilesystemStorage;
use Symfony\Component\Cache\Adapter\AbstractAdapter;

$templateStorage = new FilesystemStorage('/path/to/templates');
$template = new Template(
    $templateStorage,
    /**
     * Symfony's AbstractAdapter::createSystemCache() returns the best possible adapter that your runtime supports.
     * Generally, it will create a cache via PHP files (Opcache must be enabled via opcache.enable in php.ini), and chain that with APCu if your system supports it.
     *
     * For more information on symfony/cache's available cache pool (PSR-6) adapters:
     * @see https://symfony.com/doc/current/components/cache/cache_pools.html 
     */
    AbstractAdapter::createSystemCache(namespace: 'simple_tpl', defaultLifetime: 300, version: '', directory: sys_get_temp_dir())
);

// ... assign vars, parse /display template, etc ...

About

Requirements

SimpleTpl works with PHP 8.2.0 or above.

Credits

Author: Eric Sizemore
Thanks to all Contributors.
Special thanks to JetBrains for their Licenses for Open Source Development.

Contributing

See CONTRIBUTING for more information.

Bugs and feature requests are tracked on GitHub.

Contributor Covenant Code of Conduct

See CODE_OF_CONDUCT.md

Backward Compatibility Promise

See backward-compatibility.md for more information on Backwards Compatibility.

Changelog

See the CHANGELOG for more information on what has changed recently.

License

Simple Template Engine's license depends on the version you are using:

v3.0.0 and later is licensed under The MIT License.
v2.0.1 and earlier is licensed under the GNU GPL v3 License.

See the LICENSE for more information on the license that applies to this project.

Security

See SECURITY for more information on the security disclosure process.

esi / simple_tpl

Maintainers

Details