README

Brace

brace is a simple template language written in PHP. Brace uses a handlebar style syntax.

Requirements
Installation
- Via composer
- Or Including the brace class
Usage
- Returning processes templates as a string
- Compiling to an external file
- Instance variables
Template Reference
- Variables
  - In-line "or" operator
  - Multiple In-line "or" operators
  - Return variable values by an array index value
- Iterators
  - In-line Iterators
- Nth children
- Row keys
- Iteration data variables
- Loops
  - Increasing
  - Decreasing
- Loop data variables
- Conditional Statements
  - Condition Blocks
- Else If Statements
  - In-line conditions
  - Conditions
- Including Templates
- Shortcodes
  - PHP Implementation Example
  - Content Template
- Array Counting
  - Display Count:
  - Check Count
- Comment Blocks
  - In-line Comment Block
  - Multiple Line Comment Block
- Clearing cached process string
- Running Tests

Requirements

Brace requires PHP version 8.1 or later.

Installation

Via composer

composer require alexoliverwd/brace

Or Including the brace class

/** Include brace */
include __DIR__.'/src/brace.php';

Usage

<?php

/** New brace instance */
$brace = new Brace\Parser();

/** Set instance variables (Optional) */
$brace->remove_comment_blocks = false;
$brace->template_path = __DIR__.'/';
$brace->template_ext = 'tpl';

/** Process template and echo out */
$brace->Parse('example',[
    'name' => [
        'first' => 'John',
        'last' => 'Doe'
    ]
]);

Returning processes templates as a string

<?php

/** New brace instance */
$brace = new Brace\Parser();

/** Process template and return string */
$template_string = $brace->Parse('example',[
    'name' => [
        'first' => 'John',
        'last' => 'Doe'
    ]
], false)->return();

Compiling to an external file

<?php

/** New brace instance */
$brace = new Brace\Parser();

/** Process template and compile to external file */
$brace->compile('example', 'example.html', [
    'name' => [
        'first' => 'John',
        'last' => 'Doe'
    ]
]);

Instance variables

Variable	Description	Default value
`remove_comment_blocks`	Keep or remove comment blocks from templates	[Boolean] `true`
`template_path`	Set directory to load template files from	[String] Current working directory
`template_ext`	Template file extension	[String] `tpl`

Template Reference

Variables

<?php

/** New brace instance */
$brace = new Brace\Parser();

/** Process template and echo out */
$brace->Parse('example',[
    'firstname' => 'John Doe'
]);

<p>{{firstname}}</p>

In-line "or" operator

<p>{{firstname || "No first name found"}}</p>

Multiple In-line "or" operators

<p>{{firstname || fname || "No first name found"}}</p>

Return variable values by an array index value

<p>Hi {{names->?first[Jane]->title}} {{names->?first[Jane]->last}}</p>

/** New brace instance */
$brace = new Brace\Parser();

/** Process template and echo out */
$brace->Parse('example',[
    'names' => [
        0 => [
            'title' => 'Mr',
            'first' => 'John',
            'last' => 'Smith'
        ],
        1 => [
            'title' => 'Miss',
            'first' => 'Jane',
            'last' => 'Doe'
        ],
        2 => [
            'title' => 'Dr',
            'first' => 'David',
            'last' => 'Jones'
        ]
    ]
]);

Result:

<p>Hi Miss Doe</p>

Iterators

<?php

/** New brace instance */
$brace = new Brace\Parser();

/** Process template and echo out */
$brace->Parse('example',[
    'products' => [
        0 => [
            'title' => 'Product 1',
            'price' => 22.99,
            'stock' => 15,
            'categories' => ['Textile','Cloths']
        ],
        1 => [
            'title' => 'Product 2',
            'price' => 10.00,
            'stock' => 62,
            'categories' => ['Electronics','PC','Hardware']
        ],
        2 => [
            'title' => 'Product 3',
            'price' => 89.98,
            'stock' => 120,
            'categories' => ['PC Game']
        ]
    ]
]);

<ul>
{{each products}}
    <li>{{title}}</li>
{{end}}
</ul>

<ul>
{{each products as product}}
    <li>
        {{product->title}}
        <ul>
        {{each product->categories as category}}
            <li>{{category}}</li>
        {{end}}
        </ul>
    </li>
{{end}}
</ul>

<?php

/** New brace instance */
$brace = new Brace\Parser();

/** Process template and echo out */
$brace->Parse('example',[
    'names' => ['John','Steve','Bert']
]);

{{each names as name}}
    <p>{{name}}</p>
{{end}}

In-line Iterators

<?php

/** New brace instance */
$brace = new Brace\Parser();

/** Process template and echo out */
$brace->Parse('example',[
    'names' => ['John','Steve','Bert']
]);

<ul>
    {{names as name "<li>__name__</li>"}}
</ul>

<ul>
    {{names as key value "<li data-key="__key__">__value__</li>"}}
</ul>

<ul>
    <li>John</li>
    <li>Steve</li>
    <li>Bert</li>
</ul>

Nth children

<?php

/** New brace instance */
$brace = new Brace\Parser();

/** Process template and echo out */
$brace->Parse('example',[
    'names' => ['John','Steve','Bert','Fred','Cindy']
]);

<!-- Is first item -->
{{each names as name}}
    <span{{_ITERATION === "is_first_item" ? " class=\"is_first\""}}>{{name}}</span>
{{end}}

<!-- Is last item -->
{{each names as name}}
    <span{{_ITERATION === "is_last_item" ? " class=\"is_last\""}}>{{name}}</span>
{{end}}

<!-- Is second item -->
{{each names as name}}
    <span{{_ITERATION == 2 ? " class=\"is_second_item\""}}>{{name}}</span>
{{end}}

Row keys

<?php

/** New brace instance */
$brace = new Brace\Parser();

/** Process template and echo out */
$brace->Parse('example',[
    'names' => [
        'name_1' => 'Dave',
        'name_2' => 'John',
        'name_3' => 'Barry'
    ]
]);

{{each names as name}}
    <span data-key="{{_KEY}}">{{name}}</span>
{{end}}

{{each names as key value}}
    <span data-key="{{key}}">{{value}}</span>
{{end}}

Iteration data variables

Variables that are added to each iteration.

ID	Description	Type
_ITERATION	Iteration value (is_first_item, is_last_item, 2, 3 etc)	String
_ROW_ID	Record/Row ID (1,2,3, etc)	Integer
_KEY	Record/Row key	Mixed
GLOBAL	An array of external record data that is accessible to all rows	Array

Loops

<?php

/** New brace instance */
$brace = new Brace\Parser();

/** Process template and echo out */
$brace->Parse('example',[]);

{{loop 3}}
<li>{{_KEY}}</li>
{{end}}

Increasing

{{loop 1 to 3}}
<li>{{_KEY}}</li>
{{end}}

Decreasing

{{loop 3 to 1}}
<li>{{_KEY}}</li>
{{end}}

Loop data variables

Variables that are added to each iteration.

ID	Description	Type
_KEY	Row key	Integer

Conditional Statements

Condition Blocks

<?php

/** New brace instance */
$brace = new Brace\Parser();

/** Process template and echo out */
$brace->Parse('example',[
    'first_name' => 'John',
    'last_name' => 'Doe'
]);

{{if first_name EXISTS}}
    <p>Hello {{first_name}}</p>
{{end}}

{{if first_name EXISTS && first_name == "John"}}
    <p>My first name is {{first_name}}</p>
{{else}}
    <p>Please enter your first name</p>
{{end}}

Else If Statements

<?php

/** New brace instance */
$brace = new Brace\Parser();

/** Process template and echo out */
$brace->Parse('example',[
    'names' => ['John','Steve','Bert','Fred','Cindy']
]);

{{each names as name}}
    {{if _ITERATION === "is_first_item"}}
        <span class="first_item" data-rowid="{{_ROW_ID}}">{{name}}</span>
    {{elseif _ITERATION === "is_last_item"}}
        <span class="last_item" data-rowid="{{_ROW_ID}}">{{name}}</span>
    {{elseif _ITERATION == 2}}
        <span class="second_item" data-rowid="{{_ROW_ID}}">{{name}}</span>
    {{else}}
        <span data-rowid="{{_ROW_ID}}">{{name}}</span>
    {{end}}
{{end}}

In-line conditions

<p>{{first_name !== "test" ? "__first_name__" : "is test"}}</p>

<p>{{first_name EXISTS ? "__first_name__" : "is test"}}</p>

<p>{{first_name EXISTS ? "my first name is __first_name__"}}</p>

Escaping quotations

<p>{{first_name !== "test" ? "Name is \"__first_name__\"" : "is test"}}</p>

Name is "John"

Conditions

Condition	Description
==	Is equal to (Loose equality comparison)
===	Is equal to (Strict equality comparison)
>=	More than or equal to
<=	Less than or equal to
>	More than
<	Less than
!=	Is not equal (Loose non equality comparison)
!!	Is not
!==	Is not equal (Same as !! operator, strict non equality comparison
EXISTS	Exists
!EXISTS	Does not exist

Including Templates

[@include sections/footer]

[@include header footer]

[@include {{section}}]

Shortcodes

PHP Implementation Example

<?php

/** New brace parser */
$brace = new Brace\Parser();

/** Return HTML link */
$button_function = function ($attributes){
    return '<a href="'.$attributes['url'].'" alt="'.$attributes['alt'].'" target="'.$attributes['target'].'" rel="noreferrer noopener">'.$attributes['title'].'</a>';
};

/** Register shortcode */
$brace->regShortcode('button', 'button_function');

/** Process content template */
$brace->Parse('content', []);

Content Template

<!-- Button shortcode -->
[button title="Hello world" url="https://hello.world" alt="Hello world button" target="_blank"]

Array Counting

Ability to check and display array item counts

Display Count:

<p>Total items is: {{COUNT(items)}}</p>

Total items is: 3

Check Count

{{if COUNT(items) == 3}}
<p>There are three items</p>
{{end}}

There are three items

Comment Blocks

In-line Comment Block

<!-- Inline comment block -->

Multiple Line Comment Block

<!--
    Comment block over multiple lines
-->

Clearing cached process string

The --clear-- method is useful when needing to processes multiple templates with differing data using the same brace instance.

By default brace does not clear a processed string at the end of executing a template/string parse.

<?php

// Init brace
$brace = new Brace\Parser();
$brace->template_path = __DIR__.'/';

// Process first template
$brace->Parse('example',[
    'name' => [
      'first' => 'John',
      'last' => 'Doe'
    ]
]);

// Process second template using the same brace instance
$brace->clear()->parse('example_two',[
    'name' => [
      'first' => 'Dave',
      'last' => 'Smith'
    ]
]);

Running Tests

Running PHPStan and PHPUnit tests can be achieved with the following commands

./vendor/bin/phpstan analyse -c phpstan.neon
./vendor/bin/phpunit -c ./tests/phpunit.xml

Or by running via composer composer test

alexoliverwd / brace

Maintainers

Details