mindplay / kisstpl
View service / template engine for plain PHP templates
Installs: 32 655
Dependents: 1
Suggesters: 1
Security: 0
Stars: 4
Watchers: 3
Forks: 0
Open Issues: 1
Requires
- php: >=5.3
Requires (Dev)
- mindplay/benchpress: @dev
- mindplay/testies: dev-master
- phpunit/php-code-coverage: 2.*
README
A very simple view-service / template-engine for plain PHP templates.
I wanted a template engine that uses view-models (objects) rather than view-dictionaries (arrays) as are typical in most PHP template engines.
Oh, and if you don't like typing htmlspecialchars()
all day, maybe try this.
The view-service is tied to a root folder and a root namespace:
$service = new ViewService(new SimpleViewFinder('my/app/views', 'app\view')); $hello = new \app\view\HelloWorld(); $service->render($hello); // -> "my/app/views/HelloWorld.view.php"
The render()
statement in this example will render the template
my/app/views/HelloWorld.view.php
, passing the view-model object to
the rendered template as $view
- the SimpleViewFinder
is responsible
for locating the actual template based on the type of view-model.
The render()
method also accepts a second argument, allowing you to
render different templates for the same view-model:
$service->render($hello, 'boom'); // -> "my/app/views/HelloWorld.boom.php" $service->render($hello, 'bang'); // -> "my/app/views/HelloWorld.bang.php"
You can type-hint in the beginning of a template file for IDE support:
<?php use app\view\HelloWorld; /** * @var HelloWorld $view */ ?> ...
Alternatively, for type-safe template rendering, you can also type-hint statically, by returning a closure:
use app\view\HelloWorld; use mindplay\kisstpl\Renderer; <?php return function(HelloWorld $view, Renderer $renderer) { ?> ... <?php }
Things like layouts can be accomplished by using plain OOP composition.
For example, let's say we have a Layout
view-model with a $body
property, and we have an instance of the layout view-model in a $layout
property of the HelloWorld
model - to implement a typical two-step
layout, in the HelloWorld template, use begin()
and end()
to buffer
and capture a section of content:
<?php use app\view\HelloWorld; use mindplay\kisstpl\ViewService; /** * @var HelloWorld $view * @var ViewService $this */ $view->layout->title = 'My Page!'; $this->begin($view->layout->body); ?> <h1>Hello!</h1> <p>Body content goes here...</p> <?php $this->end($view->layout->body); $this->render($view->layout);
Note that begin()
and end()
take variable references as arguments -
the call to end()
will apply the captured content to $view->layout->body
.
There is deliberately no view rendering "pipeline", or any concept of layout, and this is "a good thing" - your templates have complete control of the rendering process, you have IDE support all the way,
You can also capture rendered content and return it, instead of sending the rendered content to output:
$content = $service->capture($hello);
You can use this feature to implement "partials", since it can be called
from within a template. Like render()
, the capture()
method also accepts
a second argument allowing you to render different views of the same view-model.
You can of course also extend ViewService
with custom functionality - an
interface Renderer
defines the four basic methods, render()
, capture()
,
begin()
and end()
so you can type-hint and swap out implementations as needed.
You can also replace the ViewFinder
implementation if you need custom logic
(specific to your project) for locating templates. A few implementations are
included:
-
SimpleViewFinder
for direct 1:1 class-to-file mapping (and zero overhead from calls tofile_exists()
) with a specified base namespace and root path. -
LocalViewFinder
for direct 1:1 class-to-file mapping (and zero overhead) not limited to any particular namespace, and assuming local view-files located in the same path as the view-model class file. -
DefaultViewFinder
which searches a list of root-paths and defaults to the first template found. -
MultiViewFinder
which allows you to aggregate as many otherViewFinder
instances as you need, and try them in order.
The latter is useful in modular scenarios, e.g. using a "theme" folder for template overrides, allowing you to plug in as many conventions for locating views as necessary.