Provides TemplateView and TwoStepView using PHP as the templating language, with support for partials, sections, and helpers.

Overview

Aura View

This package provides an implementation of the TemplateView and TwoStepView patterns using PHP itself as the templating language. It supports both file-based and closure-based templates along with helpers and sections.

It is preceded by systems such as Savant, Zend_View, and Solar_View.

Foreword

Installation

This library requires PHP 5.4 or later; we recommend using the latest available version of PHP as a matter of principle. It has no userland dependencies.

It is installable and autoloadable via Composer as aura/view.

Alternatively, download a release or clone this repository, then require or include its autoload.php file.

Quality

Scrutinizer Code Quality Code Coverage Build Status

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.

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.

Community

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.

Getting Started

Instantiation

To instantiate a View object, use the ViewFactory:

<?php
$view_factory = new \Aura\View\ViewFactory;
$view = $view_factory->newInstance();
?>

Escaping Output

Security-minded observers will note that all the examples in this document use manually-escaped output. Because this package is not specific to any particular media type, it does not come with escaping functionality.

When you generate output via templates, you must escape it appropriately for security purposes. This means that HTML templates should use HTML escaping, CSS templates should use CSS escaping, XML templates should use XML escaping, PDF templates should use PDF escaping, RTF templates should use RTF escaping, and so on.

For a good set of HTML escapers, please consider Aura.Html.

Registering View Templates

Now that we have a View, we need to add named templates to its view template registry. These are typically PHP file paths, but templates can also be closures. For example:

<?php
$view_registry = $view->getViewRegistry();
$view_registry->set('browse', '/path/to/views/browse.php');
?>

The browse.php file may look something like this:

<?php
foreach ($this->items as $item) {
    $id = htmlspecialchars($item['id'], ENT_QUOTES, 'UTF-8');
    $name = htmlspecialchars($item['name'], ENT_QUOTES, 'UTF-8');
    echo "Item ID #{$id} is '{$name}'." . PHP_EOL;
}
?>

Note that we use echo, and not return, in templates.

N.b.: The template logic will be executed inside the View object scope, which means that $this in the template code will refer to the View object. The same is true for closure-based templates.

Setting Data

We will almost always want to use dynamic data in our templates. To assign a data collection to the View, use the setData() method and either an array or an object. We can then use data elements as if they are properties on the View object.

<?php
$view->setData(array(
    'items' => array(
        array(
            'id' => '1',
            'name' => 'Foo',
        ),
        array(
            'id' => '2',
            'name' => 'Bar',
        ),
        array(
            'id' => '3',
            'name' => 'Baz',
        ),
    )
));
?>

N.b.: Recall that $this in the template logic refers to the View object, so that data assigned to the View can be accessed as properties on $this.

The setData() method will overwrite all existing data in the View object. The addData() method, on the other hand, will merge with existing data in the View object.

Invoking A One-Step View

Now that we have registered a template and assigned some data to the View, we tell the View which template to use, and then invoke the View:

<?php
$view->setView('browse');
$output = $view->__invoke(); // or just $view()
?>

The $output in this case will be something like this:

Item #1 is 'Foo'.
Item #2 is 'Bar'.
Item #3 is 'Baz'.

Using Sub-Templates (aka "Partials")

Sometimes we will want to split a template up into multiple pieces. We can render these "partial" template pieces using the render() method in our main template code.

First, we place the sub-template in the view registry (or in the layout registry if it for use in layouts). Then we render() it from inside the main template code. Sub-templates can use any naming scheme we like. Some systems use the convention of prefixing partial templates with an underscore, and the following example will use that convention.

Second, we can pass an array of variables to be extracted into the local scope of the partial template. (The $this variable will always be available regardless.)

For example, let's split up our browse.php template file so that it uses a sub-template for displaying items.

<?php
// add templates to the view registry
$view_registry = $view->getViewRegistry();

// the "main" template
$view_registry->set('browse', '/path/to/views/browse.php');

// the "sub" template
$view_registry->set('_item', '/path/to/views/_item.php');
?>

We extract the item-display code from browse.php into _item.php:

<?php
$id = htmlspecialchars($item['id'], ENT_QUOTES, 'UTF-8');
$name = htmlspecialchars($item['name'], ENT_QUOTES, 'UTF-8')
echo "Item ID #{$id} is '{$name}'." . PHP_EOL;
?>

Then we modify browse.php to use the sub-template:

<?php
foreach ($this->items as $item) {
    echo $this->render('_item', array(
        'item' => $item,
    ));
?>

The output will be the same as earlier when we invoke the view.

N.b.: Alternatively, we can use include or require to execute a PHP file directly in the current template scope.

Using Sections

Sections are similar to sub-templates (aka "partials") except that they are captured inline for later use. In general, they are used by view templates to capture output for layout templates.

For example, we can capture output in the view template to a named section ...

<?php
// begin buffering output for a named section
$this->beginSection('local-nav');

echo "<div>";
// ... echo the local navigation output ...
echo "</div>";

// end buffering and capture the output
$this->endSection();
?>

... and then use that output in a layout template:

<?php
if ($this->hasSection('local-nav')) {
    echo $this->getSection('local-nav');
} else {
    echo "<div>No local navigation.</div>";
}
?>

In addition, the setSection() method can be used to set the section body directly, instead of capturing it:

<?php
$this->setSection('local-nav', $this->render('_local-nav'));
?>

Using Helpers

The ViewFactory instantiates the View with an empty HelperRegistry to manage helpers. We can register closures or other invokable objects as helpers through the HelperRegistry. We can then call these helpers as if they are methods on the View.

<?php
$helpers = $view->getHelpers();
$helpers->set('hello', function ($name) {
    return "Hello {$name}!";
});

$view_registry = $view->getViewRegistry();
$view_registry->set('index', function () {
    echo $this->hello('World');
});

$view->setView('index');
$output = $view();
?>

This library does not come with any view helpers. You will need to add your own helpers to the registry as closures or invokable objects.

Custom Helper Managers

The View is not type-hinted to any particular class for its helper manager. This means you may inject an arbitrary object of your own at View construction time to manage helpers. To do so, pass a helper manager of your own to the ViewFactory.

<?php
class OtherHelperManager
{
    public function __call($helper_name, $args)
    {
        // logic to call $helper_name with
        // $args and return the result
    }
}

$helpers = new OtherHelperManager;
$view = $view_factory->newInstance($helpers);
?>

For a comprehensive set of HTML helpers, including form and input helpers, please consider the Aura.Html package and its HelperLocator as an alternative to the HelperRegistry in this package. You can pass it to the ViewFactory like so:

<?php
$helpers_factory = new Aura\Html\HelperLocatorFactory;
$helpers = $helpers_factory->newInstance();
$view = $view_factory->newInstance($helpers);
?>

Rendering a Two-Step View

To wrap the main content in a layout as part of a two-step view, we register layout templates with the View and then call setLayout() to pick one of them for the second step. (If no layout is set, the second step will not be executed.)

Let's say we have already set the browse template above into our view registry. We then set a layout template called default into the layout registry:

<?php
$layout_registry = $view->getLayoutRegistry();
$layout_registry->set('default', '/path/to/layouts/default.php');
?>

The default.php layout template might look like this:

<html>
<head>
    <title>My Site</title>
</head>
<body>
<?= $this->getContent(); ?>
</body>
</html>

We can then set the view and layout templates on the View object and then invoke it:

<?php
$view->setView('browse');
$view->setLayout('default');
$output = $view->__invoke(); // or just $view()
?>

The output from the inner view template is automatically retained and becomes available via the getContent() method on the View object. The layout template then calls getContent() to place the inner view results in the outer layout template.

N.b. We can also call setLayout() from inside the view template, allowing us to pick a layout as part of the view logic.

The view template and the layout template both execute inside the same View object. This means:

  • All data values are shared between the view and the layout. Any data assigned to the view, or modified by the view, is used as-is by the layout.

  • All helpers are shared between the view and the layout. This sharing situation allows the view to modify data and helpers before the layout is executed.

  • All section bodies are shared between the view and the layout. A section that is captured from the view template can therefore be used by the layout template.

Closures As Templates

The view and layout registries accept closures as templates. For example, these are closure-based equivlents of the browse.php and _item.php template files above:

<?php
$view_registry->set('browse', function () {
    foreach ($this->items as $item) {
        echo $this->render('_item', array(
            'item' => $item,
        ));
    }
);

$view_registry->set('_item', function (array $vars) {
    extract($vars, EXTR_SKIP);
    $id = htmlspecialchars($item['id'], ENT_QUOTES, 'UTF-8');
    $name = htmlspecialchars($item['name'], ENT_QUOTES, 'UTF-8')
    echo "Item ID #{$id} is '{$name}'." . PHP_EOL;
);
?>

When registering a closure-based template, continue to use echo instead of return when generating output. The closure is rebound to the View object, so $this in the closure will refer to the View just as it does in a file-based template.

A bit of extra effort is required with closure-based sub-templates (aka "partials"). Whereas file-based templates automatically extract the passed array of variables into the local scope, a closure-based template must:

  1. Define a function parameter to receive the injected variables (the $vars param in the _item template); and,

  2. Extract the injected variables using extract(). Alternatively, the closure may use the injected variables parameter directly.

Aside from that, closure-based templates work exactly like file-based templates.

Registering Template Search Paths

We can also tell the view and layout registries to search the filesystem for templates. First, we tell the registry what directories contain template files:

<?php
$view_registry = $view->getViewRegistry();
$view_registry->setPaths(array(
    '/path/to/foo',
    '/path/to/bar',
    '/path/to/baz'
));
?>

When we refer to named templates later, the registry will search from the first directory to the last. For finer control over the search paths, we can call prependPath() to add a directory to search earlier, or appendPath() to add a directory to search later. Regardless, the View will auto-append .php to the end of template names when searching through the directories.

Changing The Template File Extension

By default, each TemplateRegistry will auto-append .php to template file names. If the template files end with a different extension, change it usin the setTemplateFileExtension() method:

<?php
$view_registry = $view->getViewRegistry();
$view_registry->setTemplateFileExtension('.phtml');
?>

The TemplateRegistry instance used for the layouts is separate from the one for the views, so it may be necessary to change the template file extension on it as well:

<?php
$layout_registry = $view->getLayoutRegistry();
$layout_registry->setTemplateFileExtension('.phtml');
?>

Advanced Configuration

Alternatively you can pass $helpers, mapping information or paths for views and layouts as below.

<?php
$view_factory = new \Aura\View\ViewFactory;
$view = $view_factory->newInstance(
    $helpers = null,
    [
        'browse' => '/path/to/views/browse.php'
    ],
    [
        '/path/to/views/welcome',
        '/path/to/views/user',
    ],
    [
        'layout' => '/path/to/layouts/default.php'
    ],    
    [
        '/path/to/layouts',
    ],
);
?>

If you are passing the mapping information or paths to views and layouts you don't need to call the getViewRegistry or getLayoutRegistry and set the mapping information.

Eg :

$view_registry = $view->getViewRegistry();
$view_registry->set('browse', '/path/to/views/browse.php');

$layout_registry = $view->getLayoutRegistry();
$layout_registry->set('default', '/path/to/layouts/default.php');
Issues
  • Inspired by @reinink plates and @symfony template slot

    Inspired by @reinink plates and @symfony template slot

    This is adding sections in a view. The section must be rendered before the used variable.

    Featured-request 
    opened by harikt 10
  • Possible bug with the aura closure view

    Possible bug with the aura closure view

    Hi Paul,

    I was just playing around to learn and implement ADR in aura. See https://github.com/harikt/adr/commit/f7f79e898d182c4fb9e0222044b9d1224e3498ad

    In that I was writing a test on the render functionality done with aura/view. I am seeing something like

    PHPUnit 4.0.13 by Sebastian Bergmann.
    
    Configuration read from /var/www/adr/tests/phpunit.xml
    
    E.
    
    Time: 30 ms, Memory: 3.75Mb
    
    There was 1 error:
    
    1) Aura\Action_Bundle\AuraViewTest::testRenderHello
    Missing argument 1 for Aura\View\View::Aura\Action_Bundle\{closure}()
    
    /var/www/adr/tests/src/AuraViewTest.php:17
    /var/www/adr/vendor/aura/view/src/View.php:58
    /var/www/adr/vendor/aura/view/src/View.php:58
    /var/www/adr/vendor/aura/view/src/View.php:32
    /var/www/adr/src/AuraView.php:24
    /var/www/adr/tests/src/AuraViewTest.php:38
    
    FAILURES!
    Tests: 2, Assertions: 1, Errors: 1.
    

    This sounds to me that there is some sort of bug in the View.

    opened by harikt 8
  • Add a way to set map and path in factory

    Add a way to set map and path in factory

    This allows to pass the map array and paths to the template registry on constructor using the ViewFactory class.

    Improvement 
    opened by harikt 7
  • Helper updates

    Helper updates

    I added a markdown document for most of the helpers. It's a work in progress for sure. I added fluency to some of the helpers and updated the tests. I fixed the ordering of the styles helper to match that of the scripts helper. It was sorting via the tag first, then position. I think it should sort via the position, and then by the order it was added to the array. Would you agree?

    I also fixed a 'bool' in the checkboxes and radios helper for the 'checked' parameter.

    I probably should have had a single pr for some of these commits. I hope this one is ok. Also, I fixed my develop branch so it should work properly with the auraphp:develop branch.

    opened by jelofson 7
  • Aura.View/helper

    Aura.View/helper

    Hi Paul, added a $pos param to the meta helper and added 2 methods to the scripts helper, inline script and conditional script, thought you might be interested.

    Jeff Surgeson SA

    opened by jsurgeson 6
  • __construct() method, not __invoke() method, being called on helpers

    __construct() method, not __invoke() method, being called on helpers

    I am creating custom helpers, and registering them with the HelperRegistry. These helpers are objects, and the object is instantiated using Aura.Di, thusly:

    $di->params['Aura\View\HelperRegistry'] = [
        'map' => [
            'messages' => $di->lazyNew('Modus\Template\Helper\Messages'),
            'paginator' => $di->lazyNew('Modus\Template\Helper\Paginator'),
            'linkgenerator' => $di->lazyNew('Modus\Template\Helper\LinkGenerator'),
        ]
    ];
    

    The problem is, when I use them in my views, the __construct() method is called, not the __invoke() method. Meaning that to call these methods, I must do the following:

    <?php
    $result = $this->linkgenerator();
    
    echo $result('auth2');
    
    ?>
    

    This isn't the way helpers used to work. The only way it seems to fix this issue is to create a closure, like so:

    $di->params['Aura\View\HelperRegistry'] = [
        'map' => [
            'linkgenerator' => function($route) use ($di) {
                $obj = $di->newInstance('Modus\Template\Helper\LinkGenerator');
                return $obj($route);
            },
        ]
    ];
    

    This is clearly sub-optimal. Also, there seems to be an issue whereby using $di->lazyNew() is a problem, as though lazyNew() itself is not callable.

    opened by ghost 6
  • Experimental (better, branched it and fixed a PSR error)

    Experimental (better, branched it and fixed a PSR error)

    Now I did a correct branch so I don't soil the develop branch with experimental tinkering.

    Also fixed a PSR error in Checkboxes.php (the inline if statements in the for loop in invoke() )

    Here are the other PSR errors that showed up, which supposedly were already in before the fork:

    http://pastebin.com/ecBJvMuL

    opened by belgianguy 5
  • unit test to vfsStream

    unit test to vfsStream

    Try changing the unit tests to make use of https://github.com/mikey179/vfsStream .

    So we don't need to worry about the file system and permissions of directory system.

    Improvement 
    opened by harikt 5
  • Indirect modification

    Indirect modification

    Currently you cannot modify arrays that are set as view variables

    $view->a = [];
    $view->a[] = 1; // PHP Notice:  Indirect modification of overloaded property Aura/View/View::$a has no effect
    var_dump($view->a); // empty array
    

    is it a bug or expected behavior?

    The fix is simple: return field by reference

    public function &__get($key)
    

    I can make pr if you agree that it's a bug

    opened by arokettu 2
  • Add

    Add "Namespace" support

    Zend Expressive Template Interface defines support for namespaces using the :: scope resolution operator.

    Personally, I've just been using paths to basically simulate some approximation of this functionality, and had previously been considering trying to add some kind of PSR-4-like directory definition that would basically just pretend a directory structure was deeper than it was, but this seems like a solution, and seems to exist elsewhere too.

    Thoughts?

    (On an unrelated note, and thoughts/idea on starting 3.x anytime so we can modernize some syntax and get rid of some of the old cruft?)

    Ready for merge 
    opened by jakejohns 7
Releases(2.3.0)
  • 2.3.0(Jul 21, 2017)

    • Added ability to set map and path in ViewFactory. https://github.com/auraphp/Aura.View/pull/73
    • Removed CHANGES.md file.
    • Added CHANGELOG.md
    Source code(tar.gz)
    Source code(zip)
  • 2.2.1(Oct 3, 2016)

  • 2.2.0(Jan 21, 2016)

  • 2.1.1(Mar 27, 2015)

  • 2.1.0(Mar 16, 2015)

    This release has one feature addition, in addition to doucmentation and support file updates.

    Per @harikt, we have brought back the "finder" functionality from Aura.View v1. This means the TemplateRegistry can now search through directory paths to find templates implicitly, in addition to the existing explicitly registered templates. (Explicit mappings take precedence over search paths.)

    Thanks also to @iansltx for his HHVM-related testing work.

    Source code(tar.gz)
    Source code(zip)
  • 2.0.1(Nov 7, 2014)

    • TST: Update testing structure, and disable auto-resolve for container tests
    • DOC: Update README and docblocks
    • FIX: TemplateRegistry map now passes the array via set to make the file inside a closure
    Source code(tar.gz)
    Source code(zip)
  • 2.0.0(Aug 30, 2014)

    First stable 2.0 release.

    • DOC: Update docblocks and README.
    • CHG: View::render() now takes a second param, $data, for an array of vars to be extract()ed into the template scope. Closure-based templates will need to extract this on their own. (The previous technique of placing partial vars in the main template object still works.)
    Source code(tar.gz)
    Source code(zip)
  • 2.0.0-beta2(May 22, 2014)

    • [BRK] Stop using a "content variable" and begin using setContent()/getContent() instead. In your layouts, replace echo $this->content_var_name with echo $this->getContent(). (This also removes the setContentVar() and getContentVar() methods.)
    • [ADD] Add support for sections per strong desire from @harikt, which fixes #46. The new methods are setSection(), hasSection(), and getSection(), along with beginSection() and endSection().
    Source code(tar.gz)
    Source code(zip)
  • 2.0.0-beta1(May 14, 2014)

Owner
Aura for PHP
High-quality, well-tested, standards-compliant, decoupled libraries that can be used in any codebase.
Aura for PHP
A faster, safer templating library for PHP

Brainy Brainy is a replacement for the popular Smarty templating language. It is a fork from the Smarty 3 trunk. Brainy is still very new and it's lik

Box 65 Dec 20, 2021
Standalone Skeltch templating engine for PHP

SkeltchGo is a standalone version of Glowie Skeltch templating engine for PHP, intented to use from outside the framework.

glowie 1 Nov 5, 2021
SwitchBlade: Custom Directives for the Laravel Blade templating engine

SwitchBlade: Custom Directives for the Laravel Blade templating engine

Awkward Ideas 9 Sep 2, 2021
Provides a GitHub repository template for a PHP package, using GitHub actions.

php-package-template Installation ?? This is a great place for showing how to install the package, see below: Run $ composer require ergebnis/php-pack

null 262 Jan 16, 2022
Twig, the flexible, fast, and secure template language for PHP

Twig, the flexible, fast, and secure template language for PHP Twig is a template language for PHP, released under the new BSD license (code and docum

Twig 7.4k Jan 16, 2022
PHP Template Attribute Language — template engine for XSS-proof well-formed XHTML and HTML5 pages

PHPTAL - Template Attribute Language for PHP Requirements If you want to use the builtin internationalisation system (I18N), the php-gettext extension

PHPTAL 165 Dec 17, 2021
A complete and fully-functional implementation of the Jade template language for PHP

Tale Jade for PHP Finally a fully-functional, complete and clean port of the Jade language to PHP — Abraham Lincoln The Tale Jade Template Engine brin

Talesoft 93 May 4, 2021
Multi target HAML (HAML for PHP, Twig, )

Multi target HAML MtHaml is a PHP implementation of the HAML language which can target multiple languages. Currently supported targets are PHP and Twi

Arnaud Le Blanc 362 Aug 5, 2021
PHP template engine for native PHP templates

FOIL PHP template engine, for PHP templates. Foil brings all the flexibility and power of modern template engines to native PHP templates. Write simpl

Foil PHP 163 Nov 20, 2021
☕ Latte: the intuitive and fast template engine for those who want the most secure PHP sites.

Latte: amazing template engine for PHP Introduction Latte is a template engine for PHP which eases your work and ensures the output is protected again

Nette Foundation 754 Jan 16, 2022
The free-to-use template for your Imagehost-website made with PHP, HTML and CSS!

The free-to-use template for your Imagehost-website made with PHP, HTML and CSS! Some information before we start This repo is only code related, to a

Ilian 4 Dec 15, 2021
The free-to-use template for your Imagehost-website made with PHP, HTML and CSS!

The free-to-use template for your Imagehost-website made with PHP, HTML and CSS! Some information before we start This repo is only code related, to a

Ilian 4 Dec 15, 2021
⚡️ Simple and fastly template engine for PHP

EasyTpl ⚡️ Simple and fastly template engine for PHP Features It's simple, lightweight and fastly. No learning costs, syntax like PHP template It is s

PHPPkg 14 Jan 3, 2022
A Mustache implementation in PHP.

Mustache.php A Mustache implementation in PHP. Usage A quick example: <?php $m = new Mustache_Engine(array('entity_flags' => ENT_QUOTES)); echo $m->re

Justin Hileman 3.1k Jan 13, 2022
Smarty is a template engine for PHP, facilitating the separation of presentation (HTML/CSS) from application logic.

Smarty 3 template engine smarty.net Documentation For documentation see www.smarty.net/docs/en/ Requirements Smarty can be run with PHP 5.2 to PHP 7.4

Smarty PHP Template Engine 1.9k Jan 11, 2022
Native PHP template system

Plates Plates is a native PHP template system that's fast, easy to use and easy to extend. It's inspired by the excellent Twig template engine and str

The League of Extraordinary Packages 1.3k Jan 7, 2022
View template engine of PHP extracted from Laravel

Blade 【简体中文】 This is a view templating engine which is extracted from Laravel. It's independent without relying on Laravel's Container or any others.

刘小乐 145 Aug 13, 2021
PHP 5.3 Mustache implementation

Phly\Mustache MOVED! This package has moved to phly/phly-mustache, and the package name has changed to phly/phly-mustache. I have updated packagist to

phly 123 Jan 11, 2022
TextGenerator is a PHP package that aims to generate automated texts from data.

TextGenerator TextGenerator is a PHP package that aims to generate automated texts from data. Feel free to comment and contribute. Features Text gener

Vincent Brouté 85 Jul 19, 2021