Aura View

The Aura View package is an implementation of the TemplateView pattern, with support for automatic escaping, path stacks, and helpers. It adheres to the "use PHP for presentation logic" ideology, and is preceded by systems such as Savant, Zend_View, and Solar_View.

This package is compliant with PSR-0, PSR-1, and PSR-2. If you notice compliance oversights, please send a patch via pull request.

Basic Usage

Instantiation

The easiest way to instantiate a new Template with all the associated helpers is to include the instance.php script.

<?php
$template = require '/path/to/Aura.View/scripts/instance.php';

Then use the Template object to fetch() the output of a template script.

<?php
echo $template->fetch('/path/to/tpl.php');

Alternatively, we can add the Aura.View package to an autoloader, and instantiate manually:

<?php
use Aura\View\Template;
use Aura\View\EscaperFactory;
use Aura\View\TemplateFinder;
use Aura\View\HelperLocator;

$template = new Template(
    new EscaperFactory,
    new TemplateFinder,
    new HelperLocator
);

(Note that if we instantiate manually, we will need to configure the HelperLocator manually to add helper services. See the "Helpers" section near the end of this page for more information.)

Assigning Data

We can add data to the template script as properties ...

<?php
// business logic
$template->var = 'World';

... or by using the addData() method:

<?php
// business logic
$template->addData([
    'foo' => 'value of foo',
    'bar' => 'value of bar',
]);

We can then refer to the data as properties from within the template script using $this:

<?php
// template script
echo $this->var;

Finally, we can replace all the Template data values at once using setData().

<?php
// business logic
// this will remove $var, $foo, and $bar from the template
$template->setData([
    'baz' => 'Value of baz',
    'dib' => 'Value of dib',
]);

Writing Template Scripts

Aura View template scripts are written in plain PHP and do not require a new markup language. The template scripts are executed inside the Template object scope, so use of $this refers to the Template object. The following is an example script:

<html>
<head>
    <title><?= $this->title; ?></title>
</head>
<body>
    <p><?= "Hello " . $this->var . '!'; ?></p>
</body>
</html>

We can use any PHP code we would normally use. (This will require discipline on the part of the template script author to restrict himself to presentation-related logic only.)

We may wish to use the alternative PHP syntax for conditionals and loops:

<?php if ($this->model->hasMessage()): ?>
    <p>The message is <?= $this->model->getMessage(); ?></p>
<?php endif; ?>

<ul>
<?php foreach ($this->list as $item): ?>
    <li><?= $item; ?></li>
<?php endforeach; ?>
</ul>

Escaping Output

Aura View automatically escapes data assigned to the template when you access that data. So, in general, you do not need to manually apply escaping in your template scripts.

Strings assigned to the template are automatically escaped as you access them; integers, floats, booleans, and nulls are not.
If you assign an array to the template, its keys and values will be escaped as you access them.
If you assign an object to the template, its properties and method returns will also be escaped as you access them.

Here is an example of the business logic to assign data to the template ...

<?php
/**
 * @var object $obj An object with properties and methods.
 * @var array $arr An associative array.
 * @var string $str A string.
 * @var int|float $num An actual number (not a string representation).
 * @var bool $bool A boolean.
 * @var null $null A null value.
 */
$template->setData([
    'obj'  => $obj,
    'arr'  => $arr,
    'str'  => $str,
    'num'  => $num,
    'bool' => $bool,
    'null' => null,
]);

... and here is an example of the automatic escaping in the template:

<?php
// strings are auto-escaped whenever you access them
echo $this->str;

// integers, floats, booleans, nulls, and resources are not escaped
if ($this->null === null || $this->bool === false) {
    echo $this->num;
}

// array keys and values are auto-escaped per the string/number/etc
// rules listed above
foreach ($this->arr as $key => $val) {
    // the key and value are already escaped for us
    echo $key . ': ' . $val;
}

// object properties and method returns are auto-escaped per the 
// string/number/etc rules listed above
echo $this->obj->property;
echo $this->obj->method();

// if the object implements Iterator or IteratorAggregate,
// the iterator keys and values are auto-escaped as well
foreach ($this->obj as $key => $val) {
    echo $key . ': ' . $val;
}

Note that automatic escaping occurs at access time, not at assignment time, and only occurs when accessing values assigned to the template.

Manual Escaping

If you create a variable of your own inside a template, you will need to escape it yourself using the escape() helper:

<?php
$var = "this & that";
echo $this->escape($var);

Raw Data

If you want to access the assigned data without escaping applied, use the __raw() method:

<?php
// get the raw assigned string
echo $this->__raw()->str;

// get the count of an assigned array or object
echo count($this->__raw()->arr);

// see if the assigned array is empty
if (! $this->__raw()->arr) {
    echo "Array is empty.";
}

// get a raw property from an assigned object;
// either of the following will work:
echo $this->__raw()->obj->property;
echo $this->obj->__raw()->property;

// get a raw method result from an assigned object;
// either of the following will work:
echo $this->__raw()->obj->method();
echo $this->obj->__raw()->method();

// check if an object is an instanceof SomeClass
if ($this->__raw()->obj instanceof SomeClass) {
    // ...
}

Using the raw data is the only way to get a count() on an array or a Countable object, or to find the class type of the underlying variable. This is because the automatic escaping works by wrapping ("decorating") the underlying variable with an escaper object. The decoration makes it possible to auto-escape array keys and values, and object properties and methods, but unfortunately hides things like implements and instanceof from PHP.

Double Escaping

There is an escaping "gotcha" to look out for when manipulating values after they are assigned to a template. If you use an assigned value and re-assign it to the template, the new value will be double-escaped when you access it.

For example, given this business logic ...

<?php
// business logic
$template->foo = "this & that";

... and this template script ...

<?php
// template script
$this->bar = $this->foo . " & the other";
echo $this->bar;

... the output will be "this &amp; that & the other". The output was double-escaped; this is because the template escaped $this->foo for us when we accessed it and assigned it to $this->bar, and then escaped $this->bar for output as well.

When performing manipulations of this kind, use the __raw() values instead:

<?php
// template script
$this->bar = $this->__raw()->foo . " & the other";
echo $this->bar;

Now the output will be "this & that & the other", correctly escaped only once.

Using Helpers

Aura View comes with various Helper classes to encapsulate common presentation logic. These helpers are mapped to the Template object through a HelperLocator. We can call a helper in one of two ways:

As a method on the Template object
Via getHelper() to get the helper as an object of its own

We have already discussed the escape() helper above. Other helpers that are part of Aura View include:

$this->anchor($href, $text) returns an <a href="$href">$text</a> tag
$this->attribs($list) returns a space-separated attribute list from a $list key-value pair
$this->base($href) returns a <base href="$href" /> tag
$this->datetime($datestr, $format) returns a formatted datetime string.
$this->image($src) returns an <img src="$src" /> tag.
$this->metas() provides an object with methods that add to, and then retrieve, a series of <meta ... /> tags.
- $this->metas()->addHttp($http_equiv, $content) adds an HTTP-equivalent meta tag to the helper.
- $this->metas()->addName($name, $content) adds a meta-name tags to the helper.
- $this-metas()->get() returns all the added tags from the helper.
$this->scripts() provides an object with methods that add to, and then retrieve, a series of <script ... ></script> tags.
- $this->scripts()->add($src) adds a script tag to the helper.
- $this->scripts()->addCond($exp, $src) adds a script tag inside a conditional expression to the helper.
- $this->scripts()->get() returns all the added tags from the helper.
$this->styles() provides an object with methods that add to, and then retrieve, a series of <link rel="stylesheet" ... /> tags.
- $this->styles()->add($href) adds a style tag to the helper.
- $this->styles()->get() returns all the added tags from the helper.
$this->title() provides an object with methods that manipulate the <title>...</title> tag.
- $this->title()->set($title) sets the title value.
- $this->title()->append($suffix) adds on to the end of title value.
- $this->title()->prepend($prefix) adds on to the beginning of the title value.
- $this->title()->get() returns the title tag and value.

Advanced Usage

The Template Finder

Although we can use an absolute template script path with fetch(), it is more powerful to specify one or more paths where template scripts are located. Then we can fetch() based on a template name, and the TemplateFinder will search through the assigned paths for that template. This allows us to specify baseline templates, and override them as needed.

To tell the TemplateFinder where to find template scripts, get it from the Template and use setPaths().

<?php
// business logic
$finder = $template->getTemplateFinder();

// set the paths where templates can be found
$finder->setPaths([
    '/path/to/templates/foo',
    '/path/to/templates/bar',
    '/path/to/templates/baz',
]);

Now when we call fetch(), the Template object will use the TemplateFinder to look through those directories for the template script we specified.

For example, if we echo $template->fetch('tpl') the TemplateFinder will look through each of the directories in turn to use the first 'tpl.php' template script it finds. This allows us to set up several locations for templates, and put replacement templates in locations the TemplateFinder will get to before the baseline ones.

Template Composition

It often makes sense to split one template up into multiple pieces. This allows us to keep logical separations between different pieces of content. We might have a header section, a navigation section, a sidebar, and so on.

We can use the $this->find() method in a template script to find a template, and then include it wherever we like. For example:

<html>
<head>
    <?php include $this->find('head'); ?>
</head>
<body>
    <?php include $this->find('branding'); ?>
    <?php include $this->find('navigation'); ?>
    <p>Hello, <?= $this->var; ?>!</p>
    <?php include $this->find('foot'); ?>
</body>
</html>

Templates that we include in this way will share the scope of the template they are included from.

Template Partials

Template partials are a scope-separated way of splitting up templates. We can fetch() other templates from within a template; template scripts that are fetched in this way will not share the scope of the template they are called from (although $this will still be available). In addition, we can pass an array of variables to be extracted into the partial template.

For example, given the following partial template ...

<?php
// partial template named '_item.php'.
// note that we use $item, not $this->item.
echo "    <li>{$item}</li>" . PHP_EOL;

... we can fetch() it from within another template:

<?php
// main template. assume $this->list is an array of items.
foreach ($this->list as $item) {
    $template_name = '_item';
    $template_vars = ['item' => $item];
    echo $this->fetch($template_name, $template_vars);
}

That will run the $template_name template script in a separate scope, and extract the $template_vars array within that separate scope.

Writing Helpers

There are two steps to adding new helpers:

Write a helper class
Add that class as a service in the HelperLocator

Writing a helper class is straightforward: extend AbstractHelper with an __invoke() method. The following helper, for example, applies ROT-13 to a string.

<?php
namespace Vendor\Package\View\Helper;

use Aura\View\Helper\AbstractHelper;

class Obfuscate extends AbstractHelper
{
    public function __invoke($string)
    {
        return str_rot13($input);
    }
}

Now that we have a helper class, you can add it as a service in the HelperLocator like so:

<?php
// business logic
$locator = $template->getHelperLocator();
$locator->set('obfuscate', function() {
    return new \Vendor\Package\View\Helper\Obfuscate;
});

The service name in the HelperLocator doubles as a method name on the Template object. This means we can call the helper via $this->obfuscate():

<?php
// template script
echo $this->obfuscate('plain text');

Note that we can use any method name for the helper, although it is generally useful to name the service for the helper class.

Please examine the classes in Aura\View\Helper for more complex and powerful examples.

pborreli / aura.view Goto Github PK

aura.view's Introduction