Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/aoliverwd/brace
A simple template language written in PHP
https://github.com/aoliverwd/brace
handlebars php template-language
Last synced: 2 months ago
JSON representation
A simple template language written in PHP
- Host: GitHub
- URL: https://github.com/aoliverwd/brace
- Owner: aoliverwd
- License: mit
- Created: 2020-05-24T23:29:47.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-08-08T19:19:30.000Z (5 months ago)
- Last Synced: 2024-10-01T15:04:10.883Z (3 months ago)
- Topics: handlebars, php, template-language
- Language: PHP
- Homepage:
- Size: 169 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
 [](//packagist.org/packages/alexoliverwd/brace) [](//packagist.org/packages/alexoliverwd/brace)
# 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
```php
/** Include brace */
include __DIR__.'/src/brace.php';
```
# Usage
```php
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
Parse('example',[
'name' => [
'first' => 'John',
'last' => 'Doe'
]
], false)->return();
```
## Compiling to an external file
```php
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
Parse('example',[
'firstname' => 'John Doe'
]);
```
```html
{{firstname}}
```
### In-line "or" operator
```html
{{firstname || "No first name found"}}
```
### Multiple In-line "or" operators
```html
{{firstname || fname || "No first name found"}}
```
### Return variable values by an array index value
```html
Hi {{names->?first[Jane]->title}} {{names->?first[Jane]->last}}
```
```php
/** 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:
```html
Hi Miss Doe
```
## Iterators
```php
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']
]
]
]);
```
```html
- {{title}}
{{each products}}
{{end}}
```
```html
-
{{product->title}}
- {{category}}
{{each product->categories as category}}
{{end}}
{{each products as product}}
{{end}}
```
```php
Parse('example',[
'names' => ['John','Steve','Bert']
]);
```
```html
{{each names as name}}
{{name}}
{{end}}
```
### In-line Iterators
```php
Parse('example',[
'names' => ['John','Steve','Bert']
]);
```
```html
- __name__ "}}
{{names as name "
```
Or
```html
- __value__ "}}
{{names as key value "
```
```html
- John
- Steve
- Bert
```
## Nth children
```php
Parse('example',[
'names' => ['John','Steve','Bert','Fred','Cindy']
]);
```
```html
{{each names as name}}
{{name}}
{{end}}
{{each names as name}}
{{name}}
{{end}}
{{each names as name}}
{{name}}
{{end}}
```
## Row keys
```php
Parse('example',[
'names' => [
'name_1' => 'Dave',
'name_2' => 'John',
'name_3' => 'Barry'
]
]);
```
```html
{{each names as name}}
{{name}}
{{end}}
```
Or
```html
{{each names as key value}}
{{value}}
{{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
Parse('example',[]);
```
```html
{{loop 3}}
{{end}}
```
### Increasing
```html
{{loop 1 to 3}}
{{end}}
```
### Decreasing
```html
{{loop 3 to 1}}
{{end}}
```
## Loop data variables
Variables that are added to each iteration.
| ID | Description | Type |
|-------------|---------------------------------------------------------------------|---------|
| \_KEY | Row key | Integer |
## Conditional Statements
### Condition Blocks
```php
Parse('example',[
'first_name' => 'John',
'last_name' => 'Doe'
]);
```
```html
{{if first_name EXISTS}}
Hello {{first_name}}
{{end}}
```
```html
{{if first_name EXISTS && first_name == "John"}}
My first name is {{first_name}}
{{else}}
Please enter your first name
{{end}}
```
## Else If Statements
```php
Parse('example',[
'names' => ['John','Steve','Bert','Fred','Cindy']
]);
```
```html
{{each names as name}}
{{if _ITERATION === "is_first_item"}}
{{name}}
{{elseif _ITERATION === "is_last_item"}}
{{name}}
{{elseif _ITERATION == 2}}
{{name}}
{{else}}
{{name}}
{{end}}
{{end}}
```
### In-line conditions
```html
{{first_name !== "test" ? "__first_name__" : "is test"}}
```
```html
{{first_name EXISTS ? "__first_name__" : "is test"}}
```
```html
{{first_name EXISTS ? "my first name is __first_name__"}}
```
Escaping quotations
```html
{{first_name !== "test" ? "Name is \"__first_name__\"" : "is test"}}
```
```txt
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
```html
[@include sections/footer]
```
```html
[@include header footer]
```
```html
[@include {{section}}]
```
## Shortcodes
### PHP Implementation Example
```php
'.$attributes['title'].'';
};
/** Register shortcode */
$brace->regShortcode('button', 'button_function');
/** Process content template */
$brace->Parse('content', []);
```
### Content Template
```html
[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:
```html
Total items is: {{COUNT(items)}}
```
```txt
Total items is: 3
```
### Check Count
```html
{{if COUNT(items) == 3}}
There are three items
{{end}}
```
```txt
There are three items
```
## Comment Blocks
### In-line Comment Block
```html
```
### Multiple Line Comment Block
```html
```
## 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
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
```bash
./vendor/bin/phpstan analyse -c phpstan.neon
./vendor/bin/phpunit -c ./tests/phpunit.xml
```
Or by running via composer ```composer test```