Download the PHP package agashe/sigmaphp-template without Composer

SigmaPHP-Template

A powerful template engine for PHP. That you can use to build your web apps , with zero configuration and simple syntax.

Features

• Print variables and evaluate expressions
• Extend and include templates , with support for relative path
• Load templates from sub-directories using dot notation
• All basic conditional statements if, else if, else
• Support loops on all kinds of iterators (strings , numbers and arrays)
• Support Blocks , to structure your templates
• Defining variables in the template
• Share variables between templates
• Registering custom directives
• Support for single/multiple lines comments
• Caching

Installation

Documentation

Basic Usage

To start using SigmaPHP-Template , we start by including the autoload.php file , then create new instance from the Engine class , finally we call the render method

The Engine constructor accepts 2 arguments , the first is the root path for the templates for example views or templates , or whatever name you prefer. In case no path was provided , the Engine , will consider the root path of your project as the templates directory.

The second argument is path to the cache directory , is a path was set the cache will be enabled , otherwise the cache is disabled by default.

Template Files

SigmaPHP-Template uses template files with extension .template.html , it is just regular html files , but the Engine , will recognize the tags for different types of directives.

Render Method

The render method , which responsible for processing your template and returning the final html result that will be printed or sent in the response. This method accepts three arguments :

The first argument is the path to the template file , the dot notation , represents a real path on your machine , starting from the templates root path (we set in the constructor).

So in the example above the real path , that the Engine will look for is /path/to/my/project/templates/admin/users/edit.template.html

The second argument is an array holding the variables that we gonna pass to the the template for rendering. So in the example above we have a list of users , we need to loop throw in the template :

Finally we have the third argument which is boolean value to either return the result as a string or just print the final result. In most cases we will need the string representation for return HTTP response or as mail body. So by default this argument is set to false , to print the result , set it true.

Parenthesis & Quotes

SigmaPHP-Template uses 2 sets of parenthesis. Basic printing and expression evaluation both use double curly brackets :

For directives , curly brackets with pair of percentage symbol:

Finally comments with curly brackets and pair of double dashes :

For the quotes , both single ' and double " could be used with directives that accept quoted parameters, so the following are both valid :

Printing Variables

The most basic functionality that any template engine can handle , is printing :

in message.template.html :

And all variables require the $ sign , just like dealing with variables in PHP.

Expression Evaluation

Just like normal printing , we could evaluate any expression and print the result :

Normally all PHP built in functions will work except for unsafe methods , no one needs eval or exit to run in his template !!

Additional point is variable assigning , so in case you wanted to reassign a value for an variable in the template , we could simply write :

Please note , that assigning values to variables won't render anything !

Comments

Comments could be on single line or multiple lines , and all the content wrapped inside comment won't be executed.

Extend & Include Templates

Usually when developing apps , we create base template which we extend in other templates. The Engine provides 2 directives to extend base templates and include sub templates.

So assuming we have base.template.html :

We could easily extend this template in app.template.html as following :

The extend directive accepts the base template name without the extension part (template.html).

Next is the include directive , which allow us to re-use other templates in the current template , for example we could partial section on a page , or component like a button , alert .... etc

In the example above submit-button is another template , which has the button markup :

The final result will be :

Dot Notation Path

To structure your templates in sub-directories , the Engine use the dot notation to access sub-directories , so assuming in the previous example , the submit-button was under components directory , we could easily access it :

The same feature works with the extend directive :

In both cases the Engine will search for these templates starting from the root directory of the templates (The one we set in the constructor) and load them :

Relative Path

Sometimes we might ending up in situation where have 2 templates in the directory , and one of them extend/include the other , so we forced to write the full path , even they both in the same directory !!

So let's take an example , assume we have 2 templates :

To include _partial inside default , you have write :

SigmaPHP-Template provides the relative-path operator ./ , in case you are extending or including templates that places in the same directory , we could add the ./ before the template's name , and the Engine will automatically look for the template in the same directory of the current template (under processing).

So in the previous example , we could write :

Blocks

When working with extend & include , we always need a way to structure the template in away that base template could be filled with a content from a the current template , for this purpose we have the block and show_block directives.

The block directive define the block body , while the show_block directive call the block body and add it to the template. Let's take an example :

Assuming we have master.template.html , which has the following content :

Then let's create app.template.html , which will extend the master template. The app template MUST implement the blocks defined in the master , or an exception will be thrown :

When running the example above the result is :

The block and show_block directives could be used in the same file , like we want to control the visibility of a block using an if condition. And in some cases it's a mandatory to have block definition before the show_block. for example in master template we can add a block for the js files :

Now we are forced to create the js block in all of our templates that extend master , instead we could define a default implementation for the js block :

Now no exceptions will be thrown , and the app will run. Also in the app template , we could easily call our js scripts , if needed :

Please note that child's blocks content , will always override parent's block content !! So in the previous example assume js block had some content in the master , all will be overridden by the app js block's content.

As for blocks naming , all litters capital/small , number and _ . - are allowed , so all the following names are valid and please note that block's name can't be just a number , but could start with a number:

Extra point : if you prefer to add the block name to the end_block directive , The Engine will accept that behavior :

Defining Variables

Although it's not recommended to define your variables in the templates , but sometimes we are forced to do so , like to format date or subtract string from long text. Whatever the case , the Engine provides define directive , to define your variables using the following syntax :

The naming convention for the variables is same as the PHP veriable naming convention. And all defined variables MUST have default value , the default value could be scaler or expression result :

Variables also could be assigned to each other , or with variables defined with the template :

2 Important Notes About Variables

1- Variables could be redefined and in this case it will be consider as re-assigning , so in the example below the final value for $x is 10:

2- Since variables are globally defined , you can not define a variable inside a local scope like : if conditions , loops and blocks !!

Share Variables

To share a variable(s) a cross multiple templates , the Engine provides the setSharedVariables , which accept an associative array containing the variables you would like to make accessible for all templates.

For example , assume we have some values like your application's social media accounts URLs , which you want to show on every page. Normally you would do something like that :

Instead you could simply do the following :

Conditions

In order to control your templates , conditions directives could be used to decide which part to show , hide or process. The condition is a regular PHP expression , that could be based on values from variables defined in the render method , defined in the template , or and other valid expression which could be evaluated to true/false.

if and else_if conditions should be warped by parenthesis (...). And all of the conditions directives could be used all together or just a simple if / end_if pair. Also could be written inline.

And finally nested conditions are welcome as well :

Loops

The looping directives , is the other type of the control statement , looping is a core feature in any template engine , so you could list stuff.

SigmaPHP-Template have loops directive for .. in , which has the ability to loop on numbers , strings and arrays.

In addition the Engine provides 2 directives for the loops break and continue , which can be used to control the loop. Both require a condition to evaluate.

And like conditions , nested loops is supported :

Custom Directives

Sometimes your application might require some kind of functionality in the templates to be implemented , like handle order's status , dealing with money and currency ... etc

The registerCustomDirective method could be used to define your own directives. the define directives take the form {% myDirective(.... parameters) %}. The custom directive is function that might/might not accept some parameters and return a value that could be rendered by the Engine , let's have some examples :

Caching

Out of the box SigmaPHP-Template support template caching , by saving the template's result into a cache file. The Engine will always return the cached version , unless changes were made on the template or the data passed to it , in this case the Engine will re-compile the template and cache the new result.

To enable the cache , all what you have to do , is to set the path for the cache directory in the Engine constructor :

Enable caching is very useful especially for production environment , but while developing , the cache directory's size could get huge by time. So it's recommended to clean its content by deleting all files inside it.

For machines running linux , you could simply run the following command :

Examples

In this section we can have a look for how we can we use the templates and the directives together to build our application.

License

(SigmaPHP-Template) released under the terms of the MIT license.