Download the PHP package scottchiefbaker/yaml-polyfill without Composer

yaml-polyfill

A pure-PHP polyfill for the php-yaml extension, written for PHP 8.2+.

This library provides the same core API: yaml_emit(), yaml_parse(), etc. It is a single, dependency-free PHP file, so projects that need simple, reliable YAML input/output don't have to install a C extension.

It aims to cover roughly 90% of real-world YAML usage. Output is valid, readable YAML, but it is not guaranteed to be byte-identical to libyaml. If you need byte-exact fidelity to libyaml, use the php-yaml.

Features

• yaml_emit($data, $encoding, $linebreak) - serialize nested arrays, scalars, and simple objects to block-style YAML. Also yaml_emit_file($filename, $data, ...).
• yaml_parse($input, $pos, &$ndocs, $callbacks) - parse plain, quoted, and block scalars, block mappings and sequences, single-line flow collections, comments, and multi-document streams (first document). Also yaml_parse_file($filename, ...) and yaml_parse_url($url, ...).
• Handles string quoting, integers, floats (including .inf / .nan), booleans, and null.
• DateTimeInterface values are serialized as ISO-8601 strings; objects are serialized via get_object_vars(); JsonSerializable objects are serialized via jsonSerialize().
• The $encoding and $linebreak parameters are accepted for API parity; output is always UTF-8 with LF, CR, or CRLF line breaks.
• Errors are intentional and well-behaved: parse/emit failures raise an E_USER_WARNING and return false, matching PECL behavior rather than throwing exceptions.

Requirements

• PHP 8.2+

Installation

Install with Composer:

Or, if you'd rather not use Composer, drop the file somewhere and require it once:

Usage

Emitting YAML

Output:

Writing to and reading from files

Parsing YAML

Output:

Multi-document streams

Only the first document in a stream is parsed, matching the PECL extension's behavior when $pos is 0:

Error handling

Parse errors do not throw; they raise an E_USER_WARNING and return false (PECL behavior):

Limitations

This polyfill favors simplicity over full spec compliance. YAML Features not supported:

• Anchors, aliases, and merge keys (&anchor, *alias, <<).
• Tags (!!str, !!binary, !!timestamp, !php/object, etc.), YAML 1.1 timestamps, and sexagesimal numbers.
• Callbacks (the $callbacks argument is ignored).
• Multi-line plain and quoted scalars (continuation lines); multi-line flow collections (flow must be on a single line).
• Block scalar keep-chomping (+|, +>).
• Complex mapping keys (? key) and explicit key indicators.
• Tab indentation.
• Empty arrays always emit as []; empty maps and empty lists are not distinguished.
• No anchors/tags/callbacks on emit; no flow style; no control over indent unit or line width.
• Byte-exact output parity with libyaml is not a goal.
• $pos is ignored; $ndocs is always 1; only the first document is read.
• UTF-16 output is not produced; $encoding is ignored.

Testing

Run the test suite with PHP from the repository root:

License

GPL-2.0.