eclipxe / engineworks-templates
PHP Templates with plugins
Requires
- php: >=7.3
Requires (Dev)
- phpunit/phpunit: ^9.5
- psr/http-message: ^1.0
- rector/rector: ^0.13.10
- slim/psr7: ^1.5
- slim/slim: ^4.9
Suggests
- psr/http-message: ^1.0
- slim/psr7: ^1.5
- slim/slim: ^4.9
README
This library is just for running PHP Templates. Similar projects: Slim/Php-View
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.
Installation
Use composer to install this library composer require eclipxe/engineworks-templates
Basic use
<?php use EngineWorks\Templates\Callables; use EngineWorks\Templates\Plugins; use EngineWorks\Templates\Resolver; use EngineWorks\Templates\Templates; // create callables $callables = new Callables(); $callables->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 htmljs($string)
: escape as javascriptejs($string)
: escape as html and then as javascripturi($string)
: escape as uri (seerawurlencode
)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 numbertr($message, $arguments, $encoder = $this->getDefaultEncoder())
: return a transliterated message, very useful for inline templates, likehello {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 /** * @var $pagename string * @var $users array */ ?> <h1><?=$this->e($pagename)?></h1> <ul> <?php foreach ($users as $user): ?> <li>User: <b><?=$this->tr('{fullname} ({nickname})', $user)?></b></li> <?php endforeach; ?> </ul>
This is the templates call:
<?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:
<h1>List of users & 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.
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.
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
methodbaseUrl
: returnbaseUrl
property (setup from\Slim\App::getBasePath
)
This is a common code to attach the plugin into the Callables
collection:
<?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.
Contributing
Contributions are welcome! Please read CONTRIBUTING for details and don't forget to take a look on the TODO and CHANGELOG files.
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.