Provides HTML escapers and helpers, including form input helpers, that can be used in any template, view, or presentation system.
This library requires PHP 5.3 or later with mbstring and/or iconv installed, and has no userland dependencies.
It is installable and autoloadable via Composer as aura/html.
Alternatively, download a release or clone this repository, then require or include its autoload.php file.
To run the unit tests at the command line, issue phpunit -c tests/unit/. (This requires PHPUnit to be available as phpunit.)
To run the Aura.Di container configuration tests at the command line, go to the tests/container directory and issue ./phpunit.sh. (This requires PHPUnit to be available as phpunit and Composer to be available as composer.)
This library attempts to comply with PSR-1, PSR-2, and PSR-4. If you notice compliance oversights, please send a patch via pull request.
To ask questions, provide feedback, or otherwise communicate with the Aura community, please join our Google Group, follow @auraphp on Twitter, or chat with us on #auraphp on Freenode.
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();
?>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.
There are two steps to adding your own custom helpers:
-
Write a helper class
-
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.
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:
$this->escape()->html('foo')to escape HTML values$this->escape()->attr('foo')to escape unquoted HTML attributes$this->escape()->css('foo')to escape CSS values$this->escape()->js('foo')to escape JavaScript values
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>