Aura.Html
Provides HTML escapers and helpers, including form input helpers, that can be used in any template, view, or presentation system., (*1)
Foreword
Installation
This library requires PHP 5.3 or later with mbstring and/or iconv installed; we recommend using the latest available version of PHP as a matter of principle. It has no userland dependencies., (*2)
It is installable and autoloadable via Composer as aura/html., (*3)
Alternatively, download a release or clone this repository, then require or include its autoload.php file., (*4)
Quality
, (*5)
To run the unit tests at the command line, issue composer install and then vendor/bin/phpunit at the package root. This requires Composer to be available as composer., (*6)
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., (*7)
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., (*8)
Getting Started
The easiest way to instantiate a HelperLocator with all the available helpers is to use the HelperLocatorFactory:, (*9)
<?php
$factory = new \Aura\Html\HelperLocatorFactory;
$helper = $factory->newInstance();
?>
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., (*10)
N.b.: All built-in helpers escape values appropriately; see the various helper class internals for more information., (*11)
Custom Helpers
There are two steps to adding your own custom helpers:, (*12)
-
Write a helper class, (*13)
-
Set a factory for that class into the HelperLocator under a service name, (*14)
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., (*15)
The following example helper class applies ROT-13 to a string., (*16)
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., (*17)
<?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():, (*18)
<?= $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., (*19)
Please examine the classes in Aura\Html\Helper for more complex and powerful
examples., (*20)
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:, (*21)
-
$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:, (*22)
```html+php
, (*23)
<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>
, (*24)
, (*25)
<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>
, (*26)
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:
```html+php
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., (*27)
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., (*28)
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).), (*29)
Here is a contrived example of the various static methods:, (*30)
```html+php
, (*31)
, (*32)
<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>
, (*33)
, (*34)
<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>
```, (*35)
Wallogit.com
