Download the PHP package snicco/templating without Composer

Snicco-Templating: A uniform API around various PHP template engines.

The Templating component of the Snicco project provides a simple, object-oriented API around popular PHP template engines.

Table of contents

1. Installation
2. Usage
   1. Overview
   2. Creating a view
   3. Directly render a view
   4. Finding the first existing view
   5. Referencing nested directories
   6. Global context / View composers
   7. View factories
   8. The PHPViewFactory
      1. Instantiation
      2. Template inheritance
3. Contributing
4. Issues and PR's
5. Security

Installation

Usage

This package consists of the following main components:

• An immutable View object, which can be rendered to its string representation with a given context.
• The TemplateEngine, which is a facade class used to create and render View objects.
• The ViewFactory interface, which abstracts away implementation details of how a View instance is rendered. See Using view factories;
• The ViewContextResolver, which is responsible for adding global context and view composer context to a view that is being rendered.

The following directory structure is assumed for the examples in this README:

Creating a view

An instance of View is always created by a call to TemplateEngine::make().

Context can be added to a View instance which will be available to the underlying template once the View is rendered.

Directly rendering a view

If you want to render a template right away you can use the render method on the TemplateEngine.

Finding the first existing view

Both the make and render method of the TemplateEngine accept an array of strings in order to use the first existing view.

If no view can be found, a ViewNotFound exception will be thrown.

Referencing nested directories

Both the make and render method of the TemplateEngine will expand dots to allow directory traversal. This works independently of the concrete ViewFactory that is being used.

Global context / View composers

Before a view is rendered, it's passed to the ViewContextResolver, which is responsible for applying:

1. global context that should be available in all views
2. context provided by view composers to some views

A view composer can be a Closure or class that implements ViewComposer.

The ViewContextResolver will be needed to instantiate the concrete implementations of the view factory interface.

Adding global context:

If you pass an array as the second argument to GlobalViewContext::add you can reference nested values in your views like so:

Adding view composers:

Using view factories

All view factories implement the ViewFactory interface.

They are used by the TemplateEngine and contain the underlying logic to render a View instance to its string representation.

It's possible to use multiple view factories together in which case the first factory that can render a given View will be used.

The following view factories are currently available:

• PHPViewFactory, included in this package. A bare-bones implementation that works great for small projects with only a handful of views.
• BladeViewFactory, included in a separate package. Integrates Laraval's Blade as a standalone template engine with this package, while retaining all features of both.
• TwigViewFactory - coming soon.

The PHPViewFactory

The PHPViewFactory is a bare-bones implementation that is great for small projects where you might only have a handful of views.

Instantiation

The PHPViewFactory takes a ViewContextResolver as the first argument and an array of root template directories as the second argument.

If a view exists in more than one template directory, the first matching one will be used. This is great for allowing certain templates to be overwritten by templates in another (custom) template directory.

Template inheritance

The PHPViewFactory allows for very basic template inheritance.

Assuming that we have the following two templates:

Rendering the post view will yield:

A couple of things to note:

• The parent template is indicated by putting Extends: parent-view-name inside /* */ comments within the first 100 bytes of the template.
• Context that is passed to a child view is available to the parent view.
• The parent view can output the child-content by using the $__content variable.
• Nested inheritance is possible. post-layout.php could for example extend layout.php

Contributing

This repository is a read-only split of the development repo of the Snicco project.

This is how you can contribute.

Reporting issues and sending pull requests

Please report issues in the Snicco monorepo.

Security

If you discover a security vulnerability, please follow our disclosure procedure.