Aura for PHP

1.1.1.1. Getting Started

The easiest way to instantiate a HelperLocator with all the available helpers is to use the HelperLocatorFactory:

<?php
$factory = new \Aura\Html\HelperLocatorFactory;
$helper = $factory->newInstance();
?>

1.1.1.1.1. Built-In Helpers

Once you have a HelperLocator, you can then use the helpers by calling them as methods on the HelperLocator instance. See the tag helpers and form helpers pages for more information.

N.b.: All built-in helpers escape values appropriately; see the various helper class internals for more information.

1.1.1.1.2. Custom Helpers

There are two steps to adding your own custom helpers:

  1. Write a helper class

  2. Set a factory for that class into the HelperLocator under a service name

A helper class needs only to implement the __invoke() method. We suggest extending from AbstractHelper to get access to indenting, escaping, etc., but it's not required.

The following example helper class applies ROT-13 to a string.

<?php
namespace Vendor\Package;

use Aura\Html\Helper\AbstractHelper;

class Obfuscate extends AbstractHelper
{
    public function __invoke($string)
    {
        return $this->escaper->html(str_rot13($input));
    }
}
?>

Now that we have a helper class, we set a factory for it into the HelperLocator under a service name. Therein, we create and return the helper class.

<?php
$helper->set('obfuscate', function () {
    return new \Vendor\Package\Obfuscate;
});
?>

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

<?= $helper->obfuscate('plain text') ?>

Note that we can use any service name for the helper, although it is generally useful to name the service for the helper class, and for a word that can be called as a method.

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

1.1.1.1.3. Escaping

One of the important but menial tasks with PHP-based template systems is that of escaping output properly. Escaping output is absolutely necessary from a security perspective. This package comes with an escape() helper that has four escaping methods:

Here is a contrived example of the various escape() helper methods:

<head>

    <style>
        body {
            color: <?= $this->escape()->css($theme->color) ?>;
            font-size: <?= $this->escape()->css($theme->font_size) ?>;
        }
    </style>

    <script language="javascript">
        var foo = "<?= $this->escape()->js($js->foo); ?>";
    </script>

</head>

<body>

    <h1><?= $this->escape()->html($blog->title) ?></h1>

    <p class="byline">
        by <?= $this->escape()->html($blog->author) ?>
        on <?= $this->escape()->html($blog->date) ?>
    </p>

    <div id="<?php $this->escape()->attr($blog->div_id) ?>">
        <?= $blog->raw_html ?>
    </div>

</body>

Unfortunately, escaper functionality is verbose, and can make the template code look cluttered. There are two ways to mitigate this.

The first is to assign the escape() helper to a variable, and then invoke it as a callable. Here is a contrived example of the various escaping methods as callables:

<?php
// assign the escaper helper properties to callable variables
$h = $this->escape()->html;
$a = $this->escape()->attr;
$c = $this->escape()->css;
$j = $this->escape()->js;
?>

<head>

    <style>
        body {
            color: <?= $c($theme->color) ?>;
            font-size: <?= $c($theme->font_size) ?>;
        }
    </style>

    <script language="javascript">
        var foo = "<?= $j($js->foo); ?>";
    </script>

</head>

<body>

    <h1><?= $h($blog->title) ?></h1>

    <p class="byline">
        by <?= $h($blog->author) ?>
        on <?= $h($blog->date) ?>
    </p>

    <div id="<?php $a($blog->div_id) ?>">
        <?= $blog->raw_html ?>
    </div>

</body>

Alternatively, the Escaper class used by the escape() helper comes with four static methods to reduce verbosity and clutter: h(), a(), c(), j(), and. These escape values for HTML content values, unquoted HTML attribute values, CSS values, and JavaScript values, respectively.

N.b.: In Aura, we generally avoid static methods. However, we feel the tradeoff of less-cluttered templates can be worth using static methods in this one case.

To call the static Escaper methods in a PHP-based template, use the Escaper as a short alias name, then call the static methods on the alias. (If you did not instantiate a HelperLocatorFactory, you will need to prepare the static escaper methods by calling Escaper::setStatic(new Escaper).)

Here is a contrived example of the various static methods:

<?php use Aura\Html\Escaper as e; ?>

<head>

    <style>
        body {
            color: <?= e::c($theme->color) ?>;
            font-size: <?= e::c($theme->font_size) ?>;
        }
    </style>

    <script language="javascript">
        var foo = "<?= e::j($js->foo); ?>";
    </script>

</head>

<body>

    <h1><?= e::h($blog->title) ?></h1>

    <p class="byline">
        by <?= e::h($blog->author) ?>
        on <?= e::h($blog->date) ?>
    </p>

    <div id="<?php e::a($blog->div_id) ?>">
        <?= $blog->raw_html ?>
    </div>

</body>