{"id":16288689,"url":"https://github.com/matronator/parsem","last_synced_at":"2025-12-27T07:54:29.013Z","repository":{"id":58340656,"uuid":"530793175","full_name":"matronator/parsem","owner":"matronator","description":"Parser for YAML, JSON and NEON templates.","archived":false,"fork":false,"pushed_at":"2024-05-22T12:59:03.000Z","size":124,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-05-23T01:46:01.791Z","etag":null,"topics":["json","json-parser","json-template","json-templates","mtrgen","neon","parse","parser","parsing-engine","parsing-library","php","template-engine","template-language","template-parser","templating","templating-engine","yaml","yaml-parser","yaml-template","yaml-templates"],"latest_commit_sha":null,"homepage":"https://packagist.org/packages/matronator/parsem","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/matronator.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["matronator"],"patreon":"matronator","open_collective":null,"ko_fi":"matronator","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":["https://www.paypal.me/matronator","https://www.blockchain.com/btc/address/35VRpVQaqFWjUCnVRpGineShz76QyYgSVg"]}},"created_at":"2022-08-30T19:04:45.000Z","updated_at":"2024-06-05T00:31:44.434Z","dependencies_parsed_at":"2023-11-15T23:25:20.235Z","dependency_job_id":"93aea949-1cb6-4513-8848-c3a5fc16196e","html_url":"https://github.com/matronator/parsem","commit_stats":{"total_commits":23,"total_committers":1,"mean_commits":23.0,"dds":0.0,"last_synced_commit":"c8a57ffbf980bcb9a6e8e68b58d3265e8ee62b67"},"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matronator%2Fparsem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matronator%2Fparsem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matronator%2Fparsem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matronator%2Fparsem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matronator","download_url":"https://codeload.github.com/matronator/parsem/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244543719,"owners_count":20469550,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["json","json-parser","json-template","json-templates","mtrgen","neon","parse","parser","parsing-engine","parsing-library","php","template-engine","template-language","template-parser","templating","templating-engine","yaml","yaml-parser","yaml-template","yaml-templates"],"created_at":"2024-10-10T19:49:07.207Z","updated_at":"2025-12-27T07:54:29.004Z","avatar_url":"https://github.com/matronator.png","language":"PHP","readme":"# Pars'Em Template Engine\n\n![Pars'Em logo](.github/parsem-logo.png)\n\nSimple lightweight templating engine made in PHP.\n\nEnhance your files with variables, conditional blocks and PHP functions as filters. Create re-usable templates by adding variable `\u003c% placeholder %\u003e`'s anywhere in your file and have the content change dynamically based on the arguments you provide.\n\n\u003c!-- @import \"[TOC]\" {cmd=\"toc\" depthFrom=2 depthTo=6 orderedList=false} --\u003e\n\n\u003c!-- code_chunk_output --\u003e\n\n- [Features](#features)\n- [Requirements](#requirements)\n- [Installation](#installation)\n  - [Templates Syntax Highlighting for VS Code](#templates-syntax-highlighting-for-vs-code)\n- [Usage](#usage)\n  - [Template syntax](#template-syntax)\n    - [Comments](#comments)\n    - [Conditions](#conditions)\n    - [Variables](#variables)\n      - [Default values](#default-values)\n    - [Filters](#filters)\n  - [Built-in filters](#built-in-filters)\n  - [Use in code](#use-in-code)\n    - [Parse string or file](#parse-string-or-file)\n    - [Methods](#methods)\n      - [`Parser::parseString`](#parserparsestring)\n      - [`Parser::parse`](#parserparse)\n\n\u003c!-- /code_chunk_output --\u003e\n\n## Features\n\n- Parse string templates to string\n  - Replace variable placeholders with provided arguments\n  - Apply filter functions to variables\n    - Use [built-in filters](#built-in-filters) or provide custom functions\n  - Use `\u003c% if %\u003e` blocks to conditionally parse the template\n    - Use `\u003c% else %\u003e` blocks to provide an alternative content if the condition is not met\n  - Include `\u003c# comments #\u003e` in the template files that are removed after patsing\n- Parse template files to string\n  - Parse the entire file as a string\n- Provide a custom regex pattern to parse functions to use a custom syntax\n- Get all variables from a template\n\n## Requirements\n\n- PHP \u003e= 8.2\n- Composer\n\n## Installation\n\nInstall with Composer:\n\n```\ncomposer require matronator/parsem\n```\n\nAnd then just add the dependency to your PHP file/s:\n\n```php\nuse Matronator\\Parsem\\Parser;\n```\n\n### Templates Syntax Highlighting for VS Code\n\nTo get syntax highlighting for template files (highlight `\u003c% variable|placeholders %\u003e` and `\u003c% if %\u003e\u003c% else %\u003e\u003c% endif %\u003e` even inside strings), you can download the [MTRGen Templates Syntax Highlighting](https://marketplace.visualstudio.com/items?itemName=matronator.mtrgen-yaml-templates) extension for VS Code.\n\n## Usage\n\n### Template syntax\n\n#### Comments\n\nYou can use comments in your templates by using the following syntax:\n\n```\n\u003c# This is a comment #\u003e\n```\n\nComments are ignored by the parser and will be removed from the parsed output.\n\n#### Conditions\n\nYou can use conditions in your templates by using the `\u003c% if %\u003e` and `\u003c% endif %\u003e` tags. The condition must be a valid PHP expression that will be evaluated and if it returns `true`, the content between the tags will be included in the final output.\n\nYou can also use the `\u003c% else %\u003e` tag to provide an alternative content if the condition is not met.\n\nTo use a variable provided in the arguments array in a condition, you must use the `$` sign before the variable name, like this: `\u003c% if $variable == 'value' %\u003e`. The `$` sign is used to differentiate between the template variable and a keyword such as `true` or `null`.\n\n##### Example:\n\n```yaml\nsome:\n  key\n  \u003c% if $variable == 'value' %\u003e\n  with value\n  \u003c% else %\u003e\n  without value\n  \u003c% endif %\u003e\n```\n\nIf you provide an argument `['variable' =\u003e 'value']`, the final output will be this:\n\n```yaml\nsome:\n  key\n  with value\n```\n\nAnd if you provide an argument `['variable' =\u003e 'other value']`, the final output will be this:\n\n```yaml\nsome:\n  key\n  without value\n```\n\n#### Variables\n\nVariables are wrapped in `\u003c%` and `%\u003e` with optional space on either side (both `\u003c%nospace%\u003e` and `\u003c% space %\u003e` are valid) and the name must be an alphanumeric string with optional underscore/s (this regex `[a-zA-Z0-9_]+?`).\n\n##### Default values\n\nVariables 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: `\u003c% variable='Default' %\u003e`\n\nIf you're going to use filters, the default value comes before the filter, ie.: `\u003c% variable='Default'|filter %\u003e`\n\nIf default value is empty (ie. `\u003c% var= %\u003e`), it will be treated as null.\n\n#### Filters\n\nYou 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: `\u003c% variable|filter %\u003e`.\n\nThe filter can be any PHP function with the variable used as the function's argument.\n\n##### Example:\n\n\u003e If we have `\u003c% foo|strtoupper %\u003e` in the template and we provide an argument `['foo' =\u003e 'hello world']`, the final (parsed) output will be this: `HELLO WORLD`.\n\nFilters can also have additional arguments apart from the variable itself. To pass additional arguments to a filter, write it like this: `\u003c% var|filter:'arg','arg2',20,true %\u003e`. Each argument after the colon is separated by a comma and can have any scalar type as a value.\n\nThe first argument will always the variable on which we're declaring the filter, with any other arguments passed after that.\n\n##### Example:\n\n\u003e If we have `\u003c% foo|substr:1,3 %\u003e` and provide an argument `['foo' =\u003e '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`.\n\n*So far you can specify only one filter per variable declaration, but that will probably change in the future.*\n\n### Built-in filters\n\nThere are a few built-in filters that you can use:\n\n`upper` - Converts the variable to uppercase\n\n`lower` - Converts the variable to lowercase\n\n`upperFirst` - Converts the first character of the variable to uppercase\n\n`lowerFirst` - Converts the first character of the variable to lowercase\n\n`first` - Returns the first character of the variable\n\n`last` - Returns the last character of the variable\n\n`camelCase` - Converts the variable to camelCase\n\n`snakeCase` - Converts the variable to snake_case\n\n`kebabCase` - Converts the variable to kebab-case\n\n`pascalCase` - Converts the variable to PascalCase\n\n`titleCase` - Converts the variable to Title Case\n\n`length` - Returns the length of the variable\n\n`reverse` - Reverses the variable\n\n`random` - Returns a random character from the variable\n\n`truncate` - Truncates the variable to the specified length\n\n### Use in code\n\n#### Parse string or file\n\nThere are two main functions that will be of most interest to you: `parseString` and `parse`. Both are static functions and are used like this:\n\n```php\nuse Matronator\\Parsem\\Parser;\n\n// parseString()\necho Parser::parseString('some \u003c%text%\u003e.', ['text' =\u003e 'value']);\n// Output: some value.\n\n// parse()\n$arguments = [\n    'variableName' =\u003e 'value',\n    'key' =\u003e 'other value',\n];\n$parsedFile = Parser::parse('filename.yaml', $arguments);\necho $parsedFile;\n// Output: Will print the parsed contents of the file as string.\n```\n\n#### Methods\n\n##### `Parser::parseString`\n\n```php\n/**\n * Parses a string, replacing all template variables with the corresponding values passed in `$arguments`.\n * @return mixed The parsed string or the original `$string` value if it's not string\n * @param mixed $string String to parse. If not provided with a string, the function will return this value\n * @param array $arguments Array of arguments to find and replace while parsing `['key' =\u003e 'value']`\n * @param bool $strict [optional] If set to `true`, the function will throw an exception if a variable is not found in the `$arguments` array. If set to `false` null will be used.\n * @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 `\u003c% name|filter %\u003e`\n * @throws RuntimeException If a variable is not found in the `$arguments` array and `$strict` is set to `true`\n */\nParser::parseString(mixed $string, array $arguments = [], bool $strict = true, ?string $pattern = null): mixed\n```\n\n##### `Parser::parse`\n\n```php\n/**\n * @param string $filename Path to the file to parse\n * @see Parser::parseString() for rest of the parameter descriptions\n */\nParser::parse(string $filename, array $arguments = [], bool $strict = true, ?string $pattern = null): string\n```\n","funding_links":["https://github.com/sponsors/matronator","https://patreon.com/matronator","https://ko-fi.com/matronator","https://www.paypal.me/matronator","https://www.blockchain.com/btc/address/35VRpVQaqFWjUCnVRpGineShz76QyYgSVg"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatronator%2Fparsem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatronator%2Fparsem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatronator%2Fparsem/lists"}