{"id":20180577,"url":"https://github.com/ergebnis/twig-front-matter","last_synced_at":"2025-06-12T13:36:48.154Z","repository":{"id":179271096,"uuid":"663227517","full_name":"ergebnis/twig-front-matter","owner":"ergebnis","description":"🌱 + 👀 Provides a composer package with a Twig loader for files with YAML front-matter.","archived":false,"fork":false,"pushed_at":"2024-04-25T04:57:00.000Z","size":714,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-05-01T11:41:19.988Z","etag":null,"topics":["front-matter","loader","php","twig","yaml"],"latest_commit_sha":null,"homepage":null,"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/ergebnis.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["ergebnis","localheinz"]}},"created_at":"2023-07-06T20:54:35.000Z","updated_at":"2024-05-07T05:23:38.363Z","dependencies_parsed_at":"2023-10-11T06:33:54.398Z","dependency_job_id":"3e87019f-2256-41f0-841e-cd5262e91c50","html_url":"https://github.com/ergebnis/twig-front-matter","commit_stats":null,"previous_names":["ergebnis/twig-front-matter"],"tags_count":3,"template":false,"template_full_name":"ergebnis/php-package-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ergebnis%2Ftwig-front-matter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ergebnis%2Ftwig-front-matter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ergebnis%2Ftwig-front-matter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ergebnis%2Ftwig-front-matter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ergebnis","download_url":"https://codeload.github.com/ergebnis/twig-front-matter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248161264,"owners_count":21057554,"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":["front-matter","loader","php","twig","yaml"],"created_at":"2024-11-14T02:31:50.048Z","updated_at":"2025-04-10T04:57:56.982Z","avatar_url":"https://github.com/ergebnis.png","language":"PHP","funding_links":["https://github.com/sponsors/ergebnis","https://github.com/sponsors/localheinz"],"categories":[],"sub_categories":[],"readme":"# twig-front-matter\n\n[![Integrate](https://github.com/ergebnis/twig-front-matter/workflows/Integrate/badge.svg)](https://github.com/ergebnis/twig-front-matter/actions)\n[![Merge](https://github.com/ergebnis/twig-front-matter/workflows/Merge/badge.svg)](https://github.com/ergebnis/twig-front-matter/actions)\n[![Release](https://github.com/ergebnis/twig-front-matter/workflows/Release/badge.svg)](https://github.com/ergebnis/twig-front-matter/actions)\n[![Renew](https://github.com/ergebnis/twig-front-matter/workflows/Renew/badge.svg)](https://github.com/ergebnis/twig-front-matter/actions)\n\n[![Code Coverage](https://codecov.io/gh/ergebnis/twig-front-matter/branch/main/graph/badge.svg)](https://codecov.io/gh/ergebnis/twig-front-matter)\n\n[![Latest Stable Version](https://poser.pugx.org/ergebnis/twig-front-matter/v/stable)](https://packagist.org/packages/ergebnis/twig-front-matter)\n[![Total Downloads](https://poser.pugx.org/ergebnis/twig-front-matter/downloads)](https://packagist.org/packages/ergebnis/twig-front-matter)\n[![Monthly Downloads](http://poser.pugx.org/ergebnis/twig-front-matter/d/monthly)](https://packagist.org/packages/ergebnis/twig-front-matter)\n\nThis project provides a [`composer`](https://getcomposer.org) package with a [Twig](https://twig.symfony.com) loader for files with [YAML front-matter](https://github.com/ergebnis/front-matter).\n\n## Installation\n\nRun\n\n```sh\ncomposer require ergebnis/twig-front-matter\n```\n\n## Usage\n\n### Loading Twig templates with the `FrontMatterLoader`\n\nThis project ships with a [`FrontMatterLoader`](/src/FrontMatterLoader.php) that you can use to load Twig templates with YAML front-matter.\n\nThe `FrontMatterLoader`\n\n- parses a Twig template and separates the front-matter from the body-matter using [`ergebnis/front-matter](https://github.com/ergebnis/front-matter)\n- converts the front-matter data to Twig assignments using an implementation of  [`Converter\\FrontMatterConverter`](/src/Converter/FrontMatterConverter.php)\n- returns a new Twig Source that merges the Twig assignments from the front-matter data with the body-matter from the Twig template\n\n### YAML front-matter\n\nAssume that you have a Twig template with the following YAML front-matter:\n\n```yaml\nfoo: bar\nnumber: 1234\npi: 3.14159\ndate: 2016-05-27\nempty: ~\ninvalid-key: \"hmm\"\nmultiline: |\n  Multiple\n  Line\n  String\nobject:\n  key: value\n  datetime: 2020-11-12 12:54:12\n  values:\n    - one\n    - two\n```\n\n### Converting YAML front-matter to Twig assignments with the `Converter/ToMultipleAssignmentsFrontMatterConverter`\n\nThis project ships with a [`Converter/ToMultipleAssignmentsFrontMatterConverter.php`](/src/Converter/ToMultipleAssignmentsFrontMatterConverter.php) that you can use to convert the YAML front-matter to multiple Twig assignments.\n\nThe example below will convert the parsed YAML front-matter data to multiple Twig assignments that will assign data to Twig variables with force:\n\n```php\n\ndeclare(strict_types=1);\n\nuse Ergebnis\\Twig;\n\n$frontMatterConverter = new Twig\\FrontMatter\\Converter\\ToMultipleAssignmentsFrontMatterConverter(true);\n\necho $frontMatterConverter-\u003econvert($data);\n```\n\n```twig\n{% set foo = \"bar\" %}\n{% set number = 1234 %}\n{% set pi = 3.14159 %}\n{% set date = (1464307200|date_modify('0sec')) %}\n{% set empty = null %}\n{% set multiline = \"Multiple\\nLine\\nString\\n\" %}\n{% set object = { key: \"value\", datetime: (1605185652|date_modify('0sec')), values: { 0: \"one\", 1: \"two\" } } %}\n```\n\nThe example below will convert the parsed YAML front-matter data to multiple Twig assignments that will assign data to Twig variables without force (taking into account that you may pass variables to the template and prefer not to override these variables with front-matter):\n\n```php\n\ndeclare(strict_types=1);\n\nuse Ergebnis\\Twig;\n\n$frontMatterConverter = new Twig\\FrontMatter\\Converter\\ToMultipleAssignmentsFrontMatterConverter(false);\n\necho $frontMatterConverter-\u003econvert($data);\n```\n\n```twig\n{% set foo = foo is defined ? foo : \"bar\" %}\n{% set number = number is defined ? number : 1234 %}\n{% set pi = pi is defined ? pi : 3.14159 %}\n{% set date = date is defined ? date : (1464307200|date_modify('0sec')) %}\n{% set empty = empty is defined ? empty : null %}\n{% set multiline = multiline is defined ? multiline : \"Multiple\\nLine\\nString\\n\" %}\n{% set object = object is defined ? object|merge({ key: \"value\", datetime: (1605185652|date_modify('0sec')), values: { 0: \"one\", 1: \"two\" } }) : { key: \"value\", datetime: (1605185652|date_modify('0sec')), values: { 0: \"one\", 1: \"two\" } } %}\n```\n\n### Converting YAML front-matter to a Twig assignment with the `Converter/ToSingleAssignmentFrontMatterConverter`\n\nThis project ships with a [`Converter/ToSingleAssignmentFrontMatterConverter.php`](/src/Converter/ToSingleAssignmentFrontMatterConverter.php) that you can use to convert the YAML front-matter to a single Twig assignment.\n\nThe example below will convert the parsed YAML front-matter data to a single Twig assignment that will assign data to a Twig variable with force:\n\n```php\n\ndeclare(strict_types=1);\n\nuse Ergebnis\\Twig;\n\n$frontMatterConverter = new Twig\\FrontMatter\\Converter\\ToSingleAssignmentFrontMatterConverter(\n    Twig\\Expression\\Name::fromString('data'),\n    false,\n);\n\necho $frontMatterConverter-\u003econvert($data);\n```\n\n```twig\n{% set data = { foo: \"bar\", number: 1234, pi: 3.14159, date: (1464307200|date_modify('0sec')), empty: null, invalid-key: \"hmm\", multiline: \"Multiple\\\\nLine\\\\nString\\\\n\", object: { key: \"value\", datetime: (1605185652|date_modify('0sec')), values: { 0: \"one\", 1: \"two\" } } } %}\n```\n\nThe example below will convert the parsed YAML front-matter data to a single Twig assignment that will assign data to a Twig variables without force (taking into account that you may pass a variable to the template and prefer not to override this variable with front-matter):\n\n```php\n\ndeclare(strict_types=1);\n\nuse Ergebnis\\Twig;\n\n$frontMatterConverter = new Twig\\FrontMatter\\Converter\\ToSingleAssignmentFrontMatterConverter(\n    Twig\\Expression\\Name::fromString('data'),\n    false,\n);\n\necho $frontMatterConverter-\u003econvert($data);\n```\n\n```twig\n{% set data = data is defined ? data|merge({ foo: \"bar\", number: 1234, pi: 3.14159, date: (1464307200|date_modify('0sec')), empty: null, invalid-key: \"hmm\", multiline: \"Multiple\\\\nLine\\\\nString\\\\n\", object: { key: \"value\", datetime: (1605185652|date_modify('0sec')), values: { 0: \"one\", 1: \"two\" } } }) : { foo: \"bar\", number: 1234, pi: 3.14159, date: (1464307200|date_modify('0sec')), empty: null, invalid-key: \"hmm\", multiline: \"Multiple\\\\nLine\\\\nString\\\\n\", object: { key: \"value\", datetime: (1605185652|date_modify('0sec')), values: { 0: \"one\", 1: \"two\" } } } %}\n```\n\n### Configuring services in a Symfony project\n\nAdjust your `config/services.php` as follows to register a `FrontMatterLoader` with a `Converter\\ToMultipleAssignmentsFrontMatterConverter`:\n\n```php\n\u003c?php\n\ndeclare(strict_types=1);\n\nuse Ergebnis\\FrontMatter;\nuse Ergebnis\\Twig;\nuse Symfony\\Component\\DependencyInjection;\n\nreturn static function (DependencyInjection\\Loader\\Configurator\\ContainerConfigurator $containerConfigurator): void {\n    $services = $containerConfigurator-\u003eservices();\n\n    $services-\u003edefaults()\n        -\u003eautoconfigure()\n        -\u003eautowire();\n\n    $services-\u003ealias(\n        FrontMatter\\Parser::class,\n        FrontMatter\\YamlParser::class,\n    );\n\n    $services-\u003eset(FrontMatter\\YamlParser::class)\n        -\u003eclass(FrontMatter\\YamlParser::class);\n\n\n    $services-\u003eset(Twig\\FrontMatter\\Converter\\FrontMatterConverter::class)\n        -\u003eclass(Twig\\FrontMatter\\Converter\\ToMultipleAssignmentsFrontMatterConverter::class)\n        -\u003eargs([\n            '$force' =\u003e false, // or true, as you prefer\n        ]);\n\n    $services-\u003eset(Twig\\FrontMatter\\FrontMatterLoader::class)\n        -\u003eargs([\n            '$loader' =\u003e new DependencyInjection\\Loader\\Configurator\\ReferenceConfigurator('twig.loader.native_filesystem'),\n        ]);\n});\n```\n\n## Changelog\n\nThe maintainers of this project record notable changes to this project in a [changelog](CHANGELOG.md).\n\n## Contributing\n\nThe maintainers of this project suggest following the [contribution guide](.github/CONTRIBUTING.md).\n\n## Code of Conduct\n\nThe maintainers of this project ask contributors to follow the [code of conduct](https://github.com/ergebnis/.github/blob/main/CODE_OF_CONDUCT.md).\n\n## General Support Policy\n\nThe maintainers of this project provide limited support.\n\nYou can support the maintenance of this project by [sponsoring @localheinz](https://github.com/sponsors/localheinz) or [requesting an invoice for services related to this project](mailto:am@localheinz.com?subject=ergebnis/twig-front-matter:%20Requesting%20invoice%20for%20services).\n\n## PHP Version Support Policy\n\nThis project supports PHP versions with [active and security support](https://www.php.net/supported-versions.php).\n\nThe maintainers of this project add support for a PHP version following its initial release and drop support for a PHP version when it has reached the end of security support.\n\n## Security Policy\n\nThis project has a [security policy](.github/SECURITY.md).\n\n## License\n\nThis project uses the [MIT license](LICENSE.md).\n\n## Social\n\nFollow [@localheinz](https://twitter.com/intent/follow?screen_name=localheinz) and [@ergebnis](https://twitter.com/intent/follow?screen_name=ergebnis) on Twitter.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fergebnis%2Ftwig-front-matter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fergebnis%2Ftwig-front-matter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fergebnis%2Ftwig-front-matter/lists"}