grasmash/yaml-expander

Expands internal property references in a yaml file.

4.0.0 2026-06-11 12:53 UTC

Requires

• php: >=8.1
• grasmash/expander: ^3.0.1
• psr/log: ^2 || ^3
• symfony/yaml: ^6.4.40 || ^7.4.12 || ^8.0.12

Requires (Dev)

• phpunit/phpunit: ^10.5.62 || ^11.5.50 || ^12.5.8 || ^13
• squizlabs/php_codesniffer: ^3.13 || ^4.0

MIT

• Matthew Grasmick

README

This tool expands property references in YAML files.

Requirements

• PHP 8.1+

Installation

composer require grasmash/yaml-expander

Example usage:

Example dune.yml:

type: book
book:
  title: Dune
  author: Frank Herbert
  copyright: ${book.author} 1965
  protagonist: ${characters.0.name}
  media:
    - hardcover
characters:
  - name: Paul Atreides
    occupation: Kwisatz Haderach
    aliases:
      - Usul
      - Muad'Dib
      - The Preacher
  - name: Duncan Idaho
    occupation: Swordmaster
summary: ${book.title} by ${book.author}
product-name: ${${type}.title}
timezone: ${env.TZ}

Property references use dot notation to indicate array keys, and must be wrapped in ${}.

Expansion logic:

<?php

use Grasmash\YamlExpander\YamlExpander;
use Symfony\Component\Yaml\Yaml;

// Set an environmental variable, accessible via ${env.TZ}.
putenv("TZ=ES");

// Optionally pass any PSR-3 logger to see which placeholders were expanded
// or could not be resolved. Defaults to a no-op logger.
$expander = new YamlExpander();

// Parse a yaml string directly, expanding internal property references.
$yaml_string = file_get_contents("dune.yml");
$expanded = $expander->parse($yaml_string);
print_r($expanded);

// Parse an array, expanding internal property references.
$array = Yaml::parse(file_get_contents("dune.yml"));
$expanded = $expander->expandArrayProperties($array);
print_r($expanded);

// Expand references using both internal and supplementary values:
// a placeholder such as ${book.sequel} that exists nowhere in the YAML
// itself is resolved from the reference array.
$yaml_string = "sequels: \${book.sequel}, and others.";
$reference_properties = ['book' => ['sequel' => 'Dune Messiah']];
$expanded = $expander->parse($yaml_string, $reference_properties);
// $expanded['sequels'] === 'Dune Messiah, and others.'

Unresolvable placeholders are left intact (and reported to the logger). Invalid YAML throws Symfony\Component\Yaml\Exception\ParseException, and YAML that parses to a non-array value (e.g., a bare scalar) throws UnexpectedValueException.

Security

Only parse YAML from trusted sources. Placeholder expansion can reference any value in the document or reference array, including environment variables via ${env.*}, and deeply self-referencing placeholders can expand to very large strings. This library is designed for trusted configuration files, not for arbitrary user-supplied input.

Resultant array:

<?php

array (
  'type' => 'book',
  'book' =>
  array (
    'title' => 'Dune',
    'author' => 'Frank Herbert',
    'copyright' => 'Frank Herbert 1965',
    'protagonist' => 'Paul Atreides',
    'media' =>
    array (
      0 => 'hardcover',
    ),
  ),
  'characters' =>
  array (
    0 =>
    array (
      'name' => 'Paul Atreides',
      'occupation' => 'Kwisatz Haderach',
      'aliases' =>
      array (
        0 => 'Usul',
        1 => 'Muad\'Dib',
        2 => 'The Preacher',
      ),
    ),
    1 =>
    array (
      'name' => 'Duncan Idaho',
      'occupation' => 'Swordmaster',
    ),
  ),
  'summary' => 'Dune by Frank Herbert',
  'product-name' => 'Dune',
  'timezone' => 'ES',
);

Development

Local development commands:

composer install
composer test      # lint + unit tests + code sniffer
composer unit      # PHPUnit only
composer cs        # code sniffer only
composer cbf       # auto-fix code style
composer coverage  # generate clover coverage report