README

A small, adapter-based view rendering layer for PHP. Write your application against one tiny interface and render with plain PHP, Blade or Twig — switching engines is a one-line change.

Requirements

• PHP 8.0 or higher

The bundled adapters need their engine only when you use them:

Installation

composer require initphp/views

Then install the engine for the adapter you want (skip this for the Pure PHP adapter):

composer require illuminate/view   # for BladeAdapter
composer require twig/twig         # for TwigAdapter

Quick start

Register an adapter once through the View facade, then render from anywhere with the global view() helper.

require 'vendor/autoload.php';

use InitPHP\Views\Facade\View;
use InitPHP\Views\Adapters\PurePHPAdapter;

View::via(new PurePHPAdapter(__DIR__ . '/views'));

echo view('dashboard', ['username' => 'admin']);

views/dashboard.php:

<h1>Welcome, <?= htmlspecialchars($username) ?></h1>

Rendering multiple views

Pass a list of names to render them in order and concatenate the output:

echo view(['header', 'content', 'footer'], ['title' => 'Home']);

Passing data

$data is an associative array, or an object whose public properties are used:

$user = new stdClass();
$user->username = 'admin';

echo view('profile', $user);

The view() helper and the View facade

The view() helper is a thin wrapper over the facade:

function view(string|array $views, array|object $data = []): string;

It queues the views, attaches the data and renders — equivalent to:

echo View::setView('header', 'footer')->setData(['title' => 'Home'])->render();

Every call you make on View is forwarded to the registered adapter:

View::via() accepts a ready-made adapter instance, or the class name of an adapter that can be built with no constructor arguments. Calling the facade before an adapter is registered throws a ViewException.

Adapters

Pure PHP adapter

Renders ordinary .php files. The .php extension is added automatically when missing, and each file is evaluated in an isolated scope: it receives the data as local variables and has no access to the adapter instance ($this).

use InitPHP\Views\Facade\View;
use InitPHP\Views\Adapters\PurePHPAdapter;

View::via(new PurePHPAdapter(__DIR__ . '/views'));

echo view('dashboard/index', ['username' => 'admin']);

A missing view file throws a ViewException.

Blade adapter

Bootstraps a standalone Blade engine — no full Laravel application required. Install illuminate/view first.

use InitPHP\Views\Facade\View;
use InitPHP\Views\Adapters\BladeAdapter;

View::via(new BladeAdapter(__DIR__ . '/views', __DIR__ . '/cache'));

echo view('dashboard', ['username' => 'admin']);

Both directories must exist. The first argument may also be an array of template directories. Register custom directives and conditionals on the adapter instance:

$blade = new BladeAdapter(__DIR__ . '/views', __DIR__ . '/cache');
View::via($blade);

$blade->directive('datetime', static function (string $expression): string {
    return "<?php echo ($expression)->format('Y-m-d H:i'); ?>";
});

$blade->if('admin', static fn ($user): bool => $user->isAdmin());

The adapter also exposes the most common factory methods — make(), file(), exists(), share(), composer(), creator(), addNamespace() and replaceNamespace() — and forwards any other call to the underlying Blade factory. See the Blade documentation.

Twig adapter

Bootstraps a Twig environment. Install twig/twig first.

use InitPHP\Views\Facade\View;
use InitPHP\Views\Adapters\TwigAdapter;

View::via(new TwigAdapter(__DIR__ . '/views', __DIR__ . '/cache'));

echo view('dashboard.html.twig', ['username' => 'admin']);

Both directories must exist. Twig does not add a file extension, so include it in the view name. Use getEnvironment() to add extensions, globals or filters:

$twig = new TwigAdapter(__DIR__ . '/views', __DIR__ . '/cache');
$twig->getEnvironment()->addGlobal('app_name', 'InitPHP');

View::via($twig);

Exceptions

All exceptions implement InitPHP\Views\Exceptions\ViewExceptionInterface, so a single catch can handle every failure this package raises.

use InitPHP\Views\Exceptions\ViewExceptionInterface;

try {
    echo view('dashboard', $data);
} catch (ViewExceptionInterface $e) {
    // handle any InitPHP Views failure
}

Custom adapters

Implement InitPHP\Views\Interfaces\ViewAdapterInterface (or extend AdapterAbstract, which already handles queueing and data) and register it with View::via(). See docs/custom-adapter.md.

Documentation

Full developer documentation lives in docs/:

• Getting started
• The facade and the view() helper
• Pure PHP adapter
• Blade adapter
• Twig adapter
• Writing a custom adapter
• Exceptions

Contributing

Bug reports and pull requests are welcome. Please read the org-wide contribution guide first. Run the full check suite locally before opening a PR:

composer ci   # php-cs-fixer (dry-run) + phpstan + phpunit

Credits

• Muhammet ŞAFAK <info@muhammetsafak.com.tr>

License

Released under the MIT License. Copyright © 2022 InitPHP.