README

Fast and minimalist view template engine with macro, helpers and directives.

! Deprecated

This package is mark as deprecated! It may receive bug fixes if needed but that's it. I strongly encourage users to switch to a modern JS front framework instead of using PHP as templating engine.

Installation

This is a standalone package and not provided automatically with peak/framework

$ composer require peak/view

Basic usage

A view need at least 2 things:

A Presentation
Data (or variables if you prefer)

$presentation = new SingleLayoutPresentation(
    '/path/to/layout1.php', 
    '/path/to/view1.php'
);
$data = [
    'title' => 'FooTheBar',
    'name' => 'JohnDoe'
];
$view = new View($data, $presentation);

Example of view templates

layout example:

<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title><?= $this->title ?></title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
    <main>
        <?= $this->layoutContent ?>
    </main>
</body>
</html>

script example (represented by $this->layoutContent in your layout):

<div class="container">
    hello <?= $this->name ?>
</div>

Render a view

$output = $view->render();

Create a complex Presentation

$presentation = new Presentation([
    '/layout1.php' => [
        '/view1.php',
        '/layout2,php' => [
            '/view2.php',
            '/view3.php',
        ]
    ]
]);

Macros

Macro are closure that will be bind to your view class instance. They have access to all class properties/methods so they must be used carefully. Macro are ideal for small task.

$view->addMacro('formatedName', function() {
    return ucfirst($this->name);
});

and in your template view:

...
<h1>Hello <?= $this->formatedName() ?></h1>

Helpers

An helper is a standalone object instance that is callable. In contrary of macro, helper do not have access to view properties/methods directly but tend to be more maintainable and secure than macro. Helper are ideal for advanced task and can benefit from dependencies injection.

Example of an helper class:

class EscapeTextHelper
{
    public function __invoke($text)
    {
        return filter_var($text, FILTER_SANITIZE_SPECIAL_CHARS);
    }
}

Before you can use it, you'll need to give a function name to your view helper:

$view->setHelpers([
    'escape' => new EscapeTextHelper(),
    // ...
]);

and finally, you'll be able to use your helper the same way you use macros

...
<h1>Hello <?= $this->escape($this->name) ?></h1>

Directives

Directives provide you a simpler and more elegant syntax for writing templates. By default, there is no directive activated in your View. You need to add them to your View instance with setDirectives() method. The downside of directives is that View must run them after rendering a template, adding an extra compilation step. The more directives you have, the more it take times to render the view . Of course, this side effect can be mitigated with a proper caching solution, but to keep things simple, Peak View doesn't provide one by default.

$view->setDirectives([
    // give you ability to print variable with syntax {{ $myVar }}
    new EchoDirective(), 
    // give you ability to call native php functions, 
    // macros or helpers with syntax @function(...args)
    new FnDirective(),  
]);

$view->addVars([
    'name' => 'bob'
    'messages' => [
        // ...
    ],
    'items' => [
        'property' => 'value'
    ]
]);

template.php

<h1>Hello {{ $name }}</h1>

<p>You can call native php function with @</p>
<h4>@date(l \t\h\e jS) - You have @count($messages) message(s)</h4>

<p>You can also call helpers and macros too</p>
<p>@escape($name)</p>

<p>You can still use directly PHP like this: <?= $this->name; ?></p>

<p>And finally, array variable can be accessed with DotNotation syntax: {{ $items.property }}</p>

It is important to keep in mind that PHP is executed first in your template and directives are compiled/rendered after that.

You can also write you own directive by using DirectiveInterface.

peak / view

Maintainers

Details