Overview

This library is a templating engine for PHP that uses native PHP syntax to increase template flexibility and reduce processing overhead.

Part of https://github.com/computator/php-framework-utils.

Usage

Installation

The library is available on Packagist via composer, and is installable as computator/php-template-library or included in computator/framework-utils.

Method Overview

The primary engine interfaces are defined in the UserApi namespace.

• UserApi/TemplateClient: Primary methods for utilizing the engine in templates.
• UserApi/ResolvedTemplateClient: Methods available on objects retrieved using self::tpl() while rendering.
• UserApi/RenderClient: User-visible methods for interacting with the Renderer.
• UserApi/RenderManager: Internal methods the engine uses to control the Renderer during the render process.

Templates

Templates are executed with access to the methods defined in UserApi/TemplateClient and are intended to be called via the self object as self::method(), although $this->method() should also work. Template objects retrieved using self::tpl() have the methods defined in UserApi/ResolvedTemplateClient.

Using Short Open Tags, Alternative Control Structure Syntax, and leaving out the final semicolon in closing tags is encouraged to make templates more readable.

Template Types

There are several included template types:

• Templates/File: Directly executes the named PHP file. (default)
• Templates/PHPString: Executes the provided literal string of PHP code.
• Templates/Text: Plain text (no execution).

Examples

These examples demonstrate the primary concepts of the library with a main, parent, and child template. Note that the templates can be modified to avoid referencing literal .php filenames by using an alternative TemplateResolver.

Multiple Child Blocks

main.php

<? self::inherit('parent.php') ?>

<? self::define('paragraph_one') ?>
	Paragraph one text.

	Paragraph one has a list:
	<ul>
		<? foreach (range(1, 5) as $n): ?>
			<li>Item <?=$n?></li>
		<? endforeach ?>
	</ul>

	More text.
<? self::define_end() ?>

<? self::define('paragraph_two') ?>
	Paragraph two text.

	Paragraph two calls another template:
	<? self::tpl('child.php')->with(
		title: "Child Title",
		items: [
			"one",
			"two",
			"three",
		],
	)() ?>

	More text.
<? self::define_end() ?>

parent.php

<h1>Parent Page</h1>

<p class="one">
	<? self::block('paragraph_one') ?>
</p>

<p class="two">
	<? self::block('paragraph_two') ?>
</p>

<p class="three">
	<? if (!self::block('paragraph_three')): ?>
		Fallback text if paragraph three is not set
	<? endif ?>
</p>

child.php

<div class="child">
	<h2><?=htmlspecialchars($title)?></h2>
	<? foreach ($items as $i): ?>
		<div class="item">
			Item content: <?=htmlspecialchars($i)?>
		</div>
	<? endforeach ?>
</div>

Primary Child Content

main.php

<? self::inherit('parent.php') ?>

Main text.

Main has a list:
<ul>
	<? foreach (range(1, 5) as $n): ?>
		<li>Item <?=$n?></li>
	<? endforeach ?>
</ul>

More text.

Main calls another template:
<? self::tpl('child.php')->with(
	title: "Child Title",
	items: [
		"one",
		"two",
		"three",
	],
)() ?>

More text.

parent.php

<h1>Parent Page</h1>

<p class="main">
	<? self::primary() ?>
</p>

child.php

<div class="child">
	<h2><?=htmlspecialchars($title)?></h2>
	<? foreach ($items as $i): ?>
		<div class="item">
			Item content: <?=htmlspecialchars($i)?>
		</div>
	<? endforeach ?>
</div>

Rendering

Rendering is controlled by creating a new instance of a Renderer with a root template. The user-facing interface to the renderer instance is defined in UserApi/RenderClient.

The resolution of non-root template names to templates can be controlled by specifying an optional TemplateResolver. The default implementation passes the template name directly to the configured template class.

Examples

Default Resolver

<?php

use Computator\FrameworkUtils\PHPTemplate\Renderer;
use Computator\FrameworkUtils\PHPTemplate\Templates;

// to make the example runnable
require 'vendor/autoload.php';

$renderer = Renderer::create(
	// Note that here we are instantating the root template directly.
	// Only templates referenced in `main.php` or other templates it
	// calls will use the resolver.
	new Templates\File('main.php')
);
$renderer->render();

Specifying a Resolver

<?php

use Computator\FrameworkUtils\PHPTemplate\Renderer;
use Computator\FrameworkUtils\PHPTemplate\TemplateResolver;
use Computator\FrameworkUtils\PHPTemplate\Templates;

// to make the example runnable
require 'vendor/autoload.php';

$resolver = new TemplateResolver(
	// This is the class used to instantiate new templates.
	// In this case, `Templates\File` is the default so it
	// could also be left unspecified.
	Templates\File::class
);

$main_tpl = $resolver->resolve('main.php');
$renderer = Renderer::create(
	$main_tpl,
	$resolver,
);
$renderer->render();