Overview

Description

Caldera View is a view abstraction layer.

As with the other Caldera components it has been built to be swappable and modular.

Installation

The easisest way to install it is to use Composer:

composer require vecode/caldera-view

Requires

• php: >=8.1
• ext-mbstring: *

---

Basic usage

Getting started

PHP is, at its core, a templating engine.

But sometimes, you may want to use an additional layer above this to provide better safety, re-usability or to make it easier for designers to craft templates without requiring an experienced developer to do so.

Currently there are several templating systems, for example Blade, used by Laravel or Twig, used by Symfony.

When you are building your app without a framework picking a templating engine can be a daunting task due to the differences in their usage, once you go for one you must do a refactor should you want to switch to another.

Caldera View aims to abstract this allowing you switch painlessly between providers, for example, to use Blade you con do the following:

use Caldera\View\Adapter\BladeOneAdapter;
use Caldera\View\View;

$template_dir = dirname(__FILE__) . '/templates';
$cache_dir = dirname(__FILE__) . '/cache';

$adapter = new BladeOneAdapter($template_dir, $cache_dir);
$view = new View($adapter);

If you want to switch later to Twig, just change it to the following:

use Caldera\View\Adapter\TwigAdapter;
use Caldera\View\View;

$template_dir = dirname(__FILE__) . '/templates';
$cache_dir = dirname(__FILE__) . '/cache';

$adapter = new TwigAdapter($template_dir, $cache_dir);
$view = new View($adapter);

Now, to load a template use the template method:

$view->template('page-about.blade.php');

You may pass additional data to the template by using the with method, either for single values:

$view->with('version', $version);

Or multiple values in one go:

$view->with([
    'version' => $version,
    'build' => $build,
    'locale' => $locale,
]);

Finally when you are ready, call the render method to get the rendered code:

$content = $view->render();

Or just chain all the calls together:

$content = $view->template('page-about.blade.php')
    ->with([
        'version' => $version,
        'build' => $build,
        'locale' => $locale,
    ])
    ->render();

Each engine will cache the results differently, but you can clean the cache by calling the clear method of the addapter:

$adapter = new BladeOneAdapter($template_dir, $cache_dir);
$adapter->clear();

Also you can get an instance of the actual engine (or any of its components, if applicable), for example to define custom macros or fine-tune its settings:

$adapter = new BladeOneAdapter($template_dir, $cache_dir);
$engine = $adapter->getEngine(); // Gets an instance of eftec\bladeone\BladeOne

$adapter = new TwigAdapter($template_dir, $cache_dir);
$engine = $adapter->getEngine(); // Gets an instance of Twig\Environment
$engine = $adapter->getEngine('loader'); // Gets an instance of Twig\Loader\FilesystemLoader