Download the PHP package mougrim/yaml-cst without Composer

mougrim/yaml-cst

A PHP library for parsing and manipulating YAML documents while preserving format using Tree-sitter via FFI (Foreign Function Interface).

It exposes a Concrete Syntax Tree (CST) — every byte of the original source is accounted for, including whitespace and comments — and provides a high-level API for:

• Path-based lookups — navigate to any mapping pair with a dotted path like database.host.
• Non-destructive patching — queue text replacements and apply them all at once without re-formatting the rest of the file.
• Precise error reporting — syntax errors include the exact line and byte offset.
• Line/column mapping — convert any byte offset to a human-readable line and column.

Note: Path-based access via YamlIndex is limited to mapping pairs (key–value entries). Sequences (YAML arrays) are not indexed by path. To traverse sequences or other non-mapping constructs, use YamlDocument::$tree and the YamlCstNodeRef API directly.

Note: Multi-document YAML files (with --- document separators) are not supported. YamlCstParser::parse() expects a single YAML document. Passing a multi-document file may produce unexpected results or a syntax error.

Note: Parsing an empty string ('') is valid and produces a YamlDocument with an empty index. YamlDocument::isEmpty() returns true for empty strings and for documents containing only comments.

Requirements

The native .so libraries must be present on the system. The included Dockerfile builds and installs them automatically.

Quick start

See Setting up the parser for detailed construction notes and DI container recommendations.

Installation

Building the native libraries

The library uses tree-sitter's C API through PHP FFI. You need two shared libraries:

• libtree-sitter.so — core tree-sitter runtime
• libtree-sitter-yaml.so — YAML grammar

Option A — Docker (recommended)

The provided Dockerfile compiles both libraries from source:

Option B — Build manually

Then enable FFI in php.ini:

Usage

Setting up the parser

It is recommended to create the parser and its dependencies using a dependency-injection (DI) container so that all collaborators are wired and shared automatically. The example below shows manual construction for illustration purposes.

The YamlTreeSitterCore instance wraps the native FFI bindings and is expensive to initialise. Create it once per process (e.g. as a DI singleton) and reuse it for every parse() call.

Parsing a YAML document

Path-based access

Limitation: YamlIndex only indexes mapping pairs (key–value entries). Sequences (YAML lists) are not accessible by path — traverse them via YamlDocument::$tree and YamlCstNodeRef instead.

Key normalization: Quoted keys are stripped of their surrounding quotes and only the following escape sequences are unescaped: \" inside double-quoted keys, and '' inside single-quoted keys. Other YAML escape sequences (\n, \t, \\, \uXXXX, etc.) are not unescaped. Keys with such sequences will be stored with the literal backslash in the path index.

Dot-collision: If a YAML file contains a quoted key whose text includes a literal . (e.g. "foo.bar": value), the dot-path convenience methods (getByPath, hasByPath, etc.) cannot distinguish it from a nested key foo → bar. Use the primary segment-based API to be unambiguous: get(['foo.bar']) is one key named foo.bar; get(['foo', 'bar']) is a nested key bar inside foo.

The primary API uses list<string> segments. Dot-path strings are available as convenience wrappers (getByPath, hasByPath, findByPath, childrenOfByPath) for simple cases where key names are known not to contain dots.

Patching a document

Patches are text replacements applied atomically. The original document is never mutated.

Applying overlapping patches throws PatchConflictException. The exception exposes $previousSpan and $currentSpan so you can inspect which patches conflict.

Traversing sequences with YamlCstSearcher

YamlIndex only covers mapping pairs. To work with sequences (YAML arrays) or to navigate the raw CST, use YamlCstSearcher together with YamlDocument::$tree.

Common recipes

Reading a value

Note: valueText() returns the raw source text as-is, including any YAML quoting (e.g. "localhost" not localhost). To strip surrounding quotes use either:

• YamlTextStyleHelper::normalizeScalar() — minimal unescaping (\" and '' only)
• YamlTextStyleHelper::fullyNormalizeScalar() — all YAML 1.2 escape sequences

Reading the raw pair text

pairText() returns the full source text of a mapping pair (key + colon + value), useful for debugging or when you need the raw representation:

Replacing a value

The shortest form uses YamlMappingPatchHelper::replacementPatch():

Alternatively, build the patch manually from the value span:

Deleting a key–value pair

YamlMappingPatchHelper handles the span calculation automatically — it covers the full line including the trailing newline so no empty line is left behind:

Inserting a new key–value pair

YamlMappingPatchHelper::insertionPatch() matches the indent and end-of-line sequence of the reference pair automatically:

Error handling

Line/column mapping

Text-style helpers

YamlTextStyleHelper provides low-level utilities for working with raw YAML source text. These are useful when building patches that must preserve the original formatting style.

Custom library paths

If the .so files are not in /usr/local/lib, pass explicit paths to the factory:

Docker

A Dockerfile is included for a fully reproducible environment.

Development

See CONTRIBUTING.md for the full guide.

Quick start:

Available make targets:

Node types reference

YamlNodeType is the vocabulary you need when calling YamlCstSearcher methods or checking YamlCstNodeRef::type(). The most common cases:

The full list is in src/Enum/YamlNodeType.php. YamlNodeType::tryFrom(string) returns null for any type string not in the enum (future grammar additions).

API overview

It is recommended to create all objects via a DI container with auto-wiring. For manual construction see the Setting up the parser example above.

Core classes

Domain model

Exceptions

All library exceptions implement YamlCstExceptionInterface, so a single catch is enough:

License

This project is licensed under the MIT License.