Download the PHP package taufik-nurrohman/y-a-m-l without Composer

PHP YAML Parser

Motivation

People don’t seem to be looking for content management systems anymore. There are so many blogging services already that allow them to just write. Personalization and monetization don’t seem to be the main concerns anymore in this era of big data. Or, if monetization is their only concern, they will tend to leave it up to the services they use, sacrificing their freedom to pick a web design that fits their personality.

This project is actually an internal feature of my content management system, Mecha, but I decided to make it a stand-alone project now so that other people can use it too. People seem to have a tendency to look for PHP YAML parsers, far more than their tendency to look for content management systems. So, this project is also my attempt to drive people who need a PHP YAML parser to my content management system project that I’m proud of (which is apparently not very popular since people seem to be more interested in static site generators these days).

Why should you choose my YAML parser over any other similar YAML parser out there?

• mustangostang/spyc consists of one PHP file which is 35.1 KB in size and contains a total of 1186 lines of code since the time of writing. It is out of date (only supports YAML 1.0 and is buggy in various cases) and is still comparatively bigger than my YAML parser.
• symfony/yaml prioritizes reliability and stability for use in large-scale applications. This library contains a lot of dependencies that will make your application overly bloated if your main goal is simply to convert YAML syntax to PHP data.
• yaml requires that your server allows you to install the PHP extension. In terms of conversion speed, it should be faster because it uses C, but it’s not guaranteed to be available on all PHP servers in the world that you can rent, considering that this PHP extension is not bundled with PHP by default.

Features

Anchor

asdf-1: &asdf 1
asdf-2: *asdf
asdf-3: *asdf
asdf-4: *asdf

asdf-1: &asdf
  a: asdf
  s: asdf
  d: asdf
  f: asdf
asdf-2: *asdf
asdf-3: *asdf
asdf-4: *asdf

[!NOTE]

This anchor feature only duplicates the values and does not perform proper memory management by linking the anchored values to their aliases as references, for simplicity [^1].

[!WARNING]

Anchored mapping key is not supported.

# :(
asdf: &asdf 1234
*asdf: asdf

[^1]: See issue: Anchors as “Real” References

Array

List

- asdf
- asdf
- asdf
- asdf

Flow

[ asdf, asdf, asdf, asdf ]

Map

? asdf
  asdf
: asdf

[!NOTE]

This is an experimental feature and I have no intention to support it officially. PHP array does not support storing complex data as its key. Even the SplObjectStorage and WeakMap classes only support object as their key, so this feature will be impossible to achieve. Current behavior is to convert this complex data into a serialized data. To mark it as a complex key, a null character is prepended and appended to it. This does not apply to float, integer, and string data types:

Input

? 12.3
: asdf
? 1234
: asdf
? asdf
: asdf
? asdf:
  - asdf
  - asdf
  - asdf
: asdf
? false
: asdf
? null
: asdf
? true
: asdf

Output

return (object) array(
    '12.3' => 'asdf',
    '1234' => 'asdf',
    'asdf' => 'asdf',
    "\0" . 'O:8:"stdClass":1:{s:4:"asdf";a:3:{i:0;s:4:"asdf";i:1;s:4:"asdf";i:2;s:4:"asdf";}}' . "\0" => 'asdf',
    "\0" . 'b:0;' . "\0" => 'asdf',
    "\0" . 'N;' . "\0" => 'asdf',
    "\0" . 'b:1;' . "\0" => 'asdf'
);

I wouldn’t recommend you to have this kind of syntax in your YAML document, even though this parser is able to read some of it. By the time you get there, you may already be using a better YAML parser due to various bugs.

Object

Block

a: asdf
s: asdf
d: asdf
f: asdf

Flow

{ a: asdf, s: asdf, d: asdf, f: asdf }

Comment

# asdf

Scalar

Boolean [^2]

false

true

Constant [^2]

.INF

.NAN

Date [^2]

2023-09-25

2023-09-25 20:22:42

2023-09-25T20:22:42.025Z

2023-09-25T20:22:42+07:00

Number

Float

0.5

.5

Float as Exponential Number [^2]

1.2e+34

Integer

12

Integer as Hexadecimal [^2]

0xC

Integer as Octal [^2]

0o14

014

Null [^2]

null

~

String

Block

Fold

> # Clip (default)
  asdf asdf asdf asdf
  asdf asdf asdf asdf

  asdf asdf asdf asdf

>4 # Clip and indent with 2 space(s)
      asdf asdf asdf asdf
      asdf asdf asdf asdf

      asdf asdf asdf asdf

>+ # Keep
  asdf asdf asdf asdf
  asdf asdf asdf asdf

  asdf asdf asdf asdf

>+4 # Keep and indent with 2 space(s)
      asdf asdf asdf asdf
      asdf asdf asdf asdf

      asdf asdf asdf asdf

>- # Strip
  asdf asdf asdf asdf
  asdf asdf asdf asdf

  asdf asdf asdf asdf

>-4 # Strip and indent with 2 space(s)
      asdf asdf asdf asdf
      asdf asdf asdf asdf

      asdf asdf asdf asdf

Literal

| # Clip (default)
  asdf asdf asdf asdf
  asdf asdf asdf asdf

  asdf asdf asdf asdf

|4 # Clip and indent with 2 space(s)
      asdf asdf asdf asdf
      asdf asdf asdf asdf

      asdf asdf asdf asdf

|+ # Keep
  asdf asdf asdf asdf
  asdf asdf asdf asdf

  asdf asdf asdf asdf

|+4 # Keep and indent with 2 space(s)
      asdf asdf asdf asdf
      asdf asdf asdf asdf

      asdf asdf asdf asdf

|- # Strip
  asdf asdf asdf asdf
  asdf asdf asdf asdf

  asdf asdf asdf asdf

|-4 # Strip and indent with 2 space(s)
      asdf asdf asdf asdf
      asdf asdf asdf asdf

      asdf asdf asdf asdf

Flow

Double Quote

"asdf asdf \"asdf\" asdf"

Single Quote

'asdf asdf ''asdf'' asdf'

Plain

asdf asdf 'asdf' asdf

Tag

These built-in tags are supported:

• !!binary
• !!bool
• !!float
• !!int
• !!map
• !!null
• !!seq
• !!str
• !!timestamp

Users who want to add their own custom tags can define them in the $lot parameter of the from() function as a closure. Note that this parameter is provided as a live reference, so you cannot put an array of tag definitions directly into it. Instead, you must put it into a temporary variable:

// <https://symfony.com/doc/7.3/reference/formats/yaml.html#symfony-specific-features>
$lot = [
    '!php/const' => static function ($value) {
        if (is_string($value) && defined($value)) {
            return constant($value);
        }
        return null;
    },
    '!php/enum' => static function ($value) {
        if (!is_string($value)) {
            return null;
        }
        [$a, $b] = explode('::', $value, 2);
        if ('->value' === substr($b, -7)) {
            return (new ReflectionEnumBackedCase($a, substr($b, 0, -7)))->getBackingValue();
        }
        return (new ReflectionEnumBackedCase($a, $b))->getValue();
    },
    '!php/object' => static function ($value) {
        return is_string($value) ? unserialize($value) : null;
    }
];

$value = from_yaml($value, false, $lot);

// Here, the `$lot` variable will probably contain anchors as well. Anchor data will have a key started with ‘&’.

var_dump($lot, $value);

[!WARNING]

Tagged mapping key is not supported.

# :)
asdf: !!str asdf

# :(
!!str asdf: asdf

[^2]: To simplify the parsing process, the parser does not care about case sensitivity.

Usage

This converter can be installed using Composer, but it doesn’t need any other dependencies and just uses Composer’s ability to automatically include files. Those of you who don’t use Composer should be able to include the from.php and to.php files directly into your application without any problems.

Using Composer

From the command line interface, navigate to your project folder then run this command:

composer require taufik-nurrohman/y-a-m-l

Require the generated auto-loader file in your application:

function to_yaml(...$v) {
    return x\y_a_m_l\to(...$v);
}

Document

This converter does not support multiple document feature in one YAML file, but can be supported with a little effort:

// Ensure line break after `---` and `...`
$value = preg_replace('/^(-{3}|[.]{3})\s+/m', '$1' . "\n", $value);

// Remove `---\n` prefix if any
if (0 === strpos($value, "---\n")) {
    $value = substr($value, 4);
}

$values = [];
foreach (explode("\n---\n", $value . "\n") as $v) {
    // Remove everything after `...`
    $v = explode("\n...\n", $v . "\n", 2)[0];
    $values[] = from_yaml($v);
}

var_dump($values);

Variable

There are several ways to declare variables in YAML, and all of them are not standard. The most common are variables with a format like {{ var }}. To add a variable feature, you need to convert the variable to a YAML value before parsing the data:

$variables = [
    'var_1' => 'asdf',
    'var_2' => true,
    'var_3' => 1,
    'var_4' => 1.5
];

if (false !== strpos($value, '{{')) {
    $value = preg_replace_callback('/"\{\{\s*[a-z]\w*\s*\}\}"|\'\{\{\s*[a-z]\w*\s*\}\}\'|\{\{\s*[a-z]\w*\s*\}\}/', static function ($m) use ($variables) {
        $variable = $m[0];
        // `"{{ var }}"`
        if ('"' === $variable[0] && '"' === substr($variable, -1)) {
            $variable = substr($variable, 1, -1);
        }
        // `'{{ var }}'`
        if ("'" === $variable[0] && "'" === substr($variable, -1)) {
            $variable = substr($variable, 1, -1);
        }
        // Trim variable from `{{` and `}}`
        $variable = trim(substr($variable, 2, -2));
        // Get the variable value if available, default to `null`
        $variable = $variables[$variable] ?? null;
        // Return the variable value as YAML string
        return to_yaml($variable);
    }, $value);
}

$value = from_yaml($value);

var_dump($value);

License

This library is licensed under the MIT License. Please consider donating 💰 if you benefit financially from this library.