Pars'Em Template Engine

Simple lightweight templating engine made for (primarily) JSON, YAML and NEON templates.

Enhance your JSON/YAML/NEON files with variables and PHP functions as filters. Create re-usable templates by adding variable <% placeholder %>'s anywhere in your file and have the content change dynamically based on the arguments you provide.

• Features
• Requirements
• Installation
  • Templates Syntax Highlighting for VS Code
• Usage
  • Template syntax
    • Variables
    • Filters
  • Built-in filters
  • Use in code
    • Parse string or file
    • Methods
      • Parser::parseString
      • Parser::parseFile
      • Parser::parseFileToString
    • Using custom parser

Features

• Parse string templates to string
  • Replace variable placeholders with provided arguments
  • Apply filter functions to variables
• Parse template files to string
  • Parse the entire file as a string regardless of extension
• Provide a custom regex pattern to parse functions to use a custom syntax
• Convert JSON, YAML and NEON files to a PHP object
• Convert any file type to a PHP object by providing a custom parsing function
• Get all variable placeholders from a string
• Validate a template file against the mtrgen-template-schema

Requirements

• PHP >= 7.4
• Composer

Installation

Install with Composer:

composer require matronator/parsem

And then just add the dependency to your PHP file/s:

use Matronator\Parsem\Parser;

Templates Syntax Highlighting for VS Code

To get syntax highlighting for template files (highlight <% variable|placeholders %> even inside strings), you can download the MTRGen Templates Syntax Highlighting extension for VS Code.

Usage

Template syntax

Variables

Variables are wrapped in <% and %> with optional space on either side (both <%nospace%> and <% space %> are valid) and the name must be an alphanumeric string with optional underscore/s (this regex [a-zA-Z0-9_]+?).

Default values

Variables can optionally have a default value that will be used if no argument is provided for that variable during parsing. You can specify a default value like this: <% variable='Default' %>

If you're going to use filters, the default value comes before the filter, ie.: <% variable='Default'|filter %>

Filters

You can optionally provide filter to a variable by placing the pipe symbol | right after the variable name and the filter right after that (no space around the | pipe symbol), like this: <% variable|filter %>.

The filter can be any PHP function with the variable used as the function's argument.

Example:

If we have <% foo|strtoupper %> in the template and we provide an argument ['foo' => 'hello world'], the final (parsed) output will be this: HELLO WORLD.

Filters can also have additional arguments apart from the variable itself. To pass additional arguments to a filter, write it like this: <% var|filter:'arg','arg2',20,true %>. Each argument after the colon is separated by a comma and can have any scalar type as a value.

The first argument will always the variable on which we're declaring the filter, with any other arguments passed after that.

Example:

If we have <% foo|substr:1,3 %> and provide an argument ['foo' => 'abcdef'], the filter will get called like this using the arguments provided: substr('abcdef', 1, 3). And the final parsed output will thus be this: bcd.

So far you can specify only one filter per variable declaration, but that will probably change in the future.

Built-in filters

There are a few built-in filters that you can use:

upper - Converts the variable to uppercase

lower - Converts the variable to lowercase

upperFirst - Converts the first character of the variable to uppercase

lowerFirst - Converts the first character of the variable to lowercase

first - Returns the first character of the variable

last - Returns the last character of the variable

camelCase - Converts the variable to camelCase

snakeCase - Converts the variable to snake_case

kebabCase - Converts the variable to kebab-case

pascalCase - Converts the variable to PascalCase

titleCase - Converts the variable to Title Case

length - Returns the length of the variable

reverse - Reverses the variable

random - Returns a random character from the variable

truncate - Truncates the variable to the specified length

Use in code

Parse string or file

There are three main functions that will be of most interest to you: parseString, parseFile and parseFileToString. Both are static functions and are used like this:

use Matronator\Parsem\Parser;

echo Parser::parseString('some <%text%>.', ['text' => 'value']);
// Output: some value.

$arguments = [
    'variableName' => 'value',
    'key' => 'other value',
];
$object = Parser::parseFile('filename.yaml', $arguments);
// Output: The YAML file converted to an object with all
// variable placeholders replaced by the provided arguments.

echo Parser::parseFileToString('filename.yaml', $arguments);
// Output: Will print the parsed contents of the file as string.

Methods

Parser::parseString

/**
 * Parses a string, replacing all template variables with the corresponding values passed in `$arguments`.
 * @return mixed The parsed string or the original `$string` value if it's not string
 * @param mixed $string String to parse. If not provided with a string, the function will return this value
 * @param array $arguments Array of arguments to find and replace while parsing `['key' => 'value']`
 * @param string|null $pattern [optional] You can provide custom regex with two matching groups (for the variable name and for the filter) to use custom template syntax instead of the default one `<% name|filter %>`
 */
Parser::parseString(mixed $string, array $arguments = [], ?string $pattern = null): mixed

Parser::parseFile

/**
 * @see Parser::parseString() for parameter descriptions
 */
Parser::parseFile(string $filename, array $arguments = [], ?string $pattern = null): object

Parser::parseFileToString

/**
 * @see Parser::parseString() for parameter descriptions
 */
Parser::parseFileToString(string $filename, array $arguments = [], ?string $pattern = null): string

Using custom parser

You can parse any file type to object, not only JSON/YAML/NEON, by providing a custom parser function as a callback to Parser::customParse() function.

use Matronator\Parsem\Parser;

// Parse XML file
$object = Parser::customParse('filename.xml', function($contents) {
    return simplexml_load_string($contents);
});