eclipxe/engineworks-templates

PHP Templates with plugins

eclipxe/engineworks-templates - PHP Templates with plugins

![Source Code][badge-source] ![Software License][badge-license] [][build] ![Scrutinizer][badge-quality] [][coverage] ![Total Downloads][badge-downloads], _(*1)

This library is just for running PHP Templates. Similar projects: Slim/Php-View, _(*2)

PHP is a powerfull template engine by itself, you might not need a template library as Twig, Plates or Smarty. It depends on the problem you are facing, maybe you are working with a legacy system, maybe you just don't want it., _(*3)

Installation

Use composer to install this library composer require eclipxe/engineworks-templates, _(*4)

Basic use

attach(
    new Plugins\HtmlEscape(),
    new Plugins\FormatNumber(),
    new Plugins\Transliterate(),
);

// create resolver
$resolver = new Resolver(__DIR__ . '/templates');

// create templates
$templates = new Templates($callables, $resolver);

// fetch the content of a template (templates/user-details.php)
/* @var $user array */
$content = $templates->fetch('user-details', ['user' => $user]);

// do whatever with the response, I will just echo it
echo $content;
```

## About the objects

### `EngineWorks\Templates\Templates`

This class works as a factory of `Template` objects, it helps to locate this objects with a common `Callables` object,
in a common directory with a common file extension.

The most common used method would be `fetch`. It simply creates a `Template` using the file specified by
*directory* plus *name* + *extension*, with the default callables.
Then will call `fetch` on that template.

### `EngineWorks\Templates\Template`

This is the main class of the library, it can be created stand alone
or by `Templates::create` (non-static call).

#### `EngineWorks\Templates\Template::fetch`

`fetch` method receives two arguments, a template name and a variables array.
 It will resolve the file name using the Resolver object.
 It will convert the array to variables (using `extract`) in order to make accesible these variables to the file.
 
## Inside the template

The template file is a PHP file, it will have all the variables that were set to fetch method.
Also, you can use `$this`, wich is refered to the `EngineWorks\Templates\Template` object.

The `$this` object offer some functions registered in the `Callables` object, in the example above the `$callables`
was attatched with the following functions:

- `e($string, $this->getDefaultHtmlFlags())`: escape as html
- `js($string)`: escape as javascript
- `ejs($string)`: escape as html and then as javascript
- `uri($string)`: escape as uri (see `rawurlencode`)
- `url($url, $vars)`: create an url with the defined `$vars`
- `qry($vars)`: create a query string with the defined `$vars`
- `fn($number, $decimals = $this->getDefaultDecimals())`: return a formatted number
- `tr($message, $arguments, $encoder = $this->getDefaultEncoder())`: return a transliterated message, 
  very useful for inline templates, like `hello {name}, I sent you an email to {email}`

So, you can use those functions using `$this` inside your template.

Also, you can use the `fetch` method to retrieve the content of another template.

This is a template example `templates/users-list.php`:

```php



=$this->e($pagename)?>

• User: =$this->tr('{fullname} ({nickname})', $user)?>

This is the templates call:, _(*5)

<?php
/* @var $templates \EngineWorks\Templates\Templates */
$templates->fetch('users-list', [
    'pagename' => 'List of users & members',
    'users' => [
        ['fullname' => 'John Doe', 'nickname' => 'jdoe'], 
        ['fullname' => 'Carlos C Soto', 'nickname' => 'eclipxe'], 
    ],
]);

This would be the result:, _(*6)

<h1>List of users &amp; members</h1>
<ul>
    <li>User: <b>John Doe (jdoe)</b></li>
    <li>User: <b>Carlos C Soto (eclipxe)</b></li>
</ul>

Integrations

Integrate with PSR-7

In order to integrate with a PSR-7 compatible library you can use the method render. This method is act as a decorator to fetch the template and write the contents into the ResponseInterface object., _(*7)

You only need to use this method in case you are using a PSR-7 compatible library. Otherwise, I recommend you to use fetch method. As this is optional, the psr/http-message package is not a composer dependence., _(*8)

Integrate with Slim 4

To use this library in Slim 4 we provide a plugin named Slim4Plugin that offers two methods: - pathFor: shortcut for \Slim\Interfaces\RouteParserInterface::urlFor method - baseUrl: return baseUrl property (setup from \Slim\App::getBasePath), _(*9)

This is a common code to attach the plugin into the Callables collection:, _(*10)

<?php
/* @var $callables \EngineWorks\Templates\Callables */
/* @var $app Slim\App */
$callables->attach(new \EngineWorks\Templates\Slim\Slim4Plugin(
    $app->getRouteCollector()->getRouteParser(),
    $app->getBasePath()
));

Compatibility

Version 2.x was compatible with PHP 5.4 or higher. It's no longer maintained. Version 3.x is compatible with PHP 7.3 or higher., _(*11)

Contributing

Contributions are welcome! Please read CONTRIBUTING for details and don't forget to take a look on the TODO and CHANGELOG files., _(*12)

Copyright and License

The EngineWorks\Templates library is copyright © Carlos C Soto and licensed for use under the MIT License (MIT). Please see LICENSE for more information., _(*13)