Download the PHP package php-collective/toml without Composer

PHP Toml

A TOML (v1.0 and v1.1) parser and encoder for PHP with AST access and collected parse errors.

Documentation

Features

• Strict validation for malformed keys, tables, strings, numbers, and datetimes
• Error recovery with multiple error collection for tooling workflows
• Clean architecture with separate Lexer, Parser, and AST
• Zero required extensions (optional php-ds for performance)
• AST access for analysis or editor integrations
• Explicit local date/time/datetime value objects for encoding

Requirements

• PHP 8.2 or higher

Installation

Demo

• Interactive Playground - Full-featured sandbox with all options.

Quick Start

API Reference

Decoding

Encoding

DocumentFormattingMode::SourceAware is lossless for unchanged parsed regions and uses local fallback rules for edited ones. See the Compatibility page for the exact editing contract. skipNulls lets encode() omit nulls instead of throwing. multilineThreshold (?int, default null) keeps current single-line strings when unset; when set, scalar strings longer than the threshold are encoded as multiline basic strings. inlineTableThreshold (?int, default null) keeps nested tables as table sections when unset; when set, flat nested arrays with at most that many keys are encoded inline, for example point = { x = 1, y = 2 }. integerBase (IntegerBase, default IntegerBase::Decimal) controls the radix for integers produced by encode() (and normalized encodeDocument() output). Hexadecimal, Octal, and Binary emit 0x/0o/0b literals. Since TOML allows a sign only on decimal integers, negative values always fall back to decimal. Source-aware document re-encoding preserves each integer's original source base regardless of this option.

Error Handling

The parser provides detailed error messages:

For tooling, use tryParse() to collect all errors:

Supported Syntax

The library currently supports:

• All string types (basic, literal, multi-line)
• Integers (decimal, hex, octal, binary)
• Floats (including inf, nan)
• Booleans
• Dates and times (offset, local datetime, local date, local time)
• Arrays (including multiline arrays and trailing commas)
• Inline tables (including multiline inline tables and trailing commas in TOML 1.1)
• Tables and array of tables
• Dotted keys

See the Support Matrix for current coverage and known gaps.

Versioned behavior is available through TomlVersion and EncoderOptions(version: ...). The default remains TOML 1.1-compatible; use TomlVersion::V10 when you need strict TOML 1.0 parsing or output rules.

For explicit local temporal encoding, use:

• PhpCollective\Toml\Value\LocalDate
• PhpCollective\Toml\Value\LocalTime
• PhpCollective\Toml\Value\LocalDateTime

For per-value integer bases, wrap values in PhpCollective\Toml\Value\TomlInteger (e.g. new TomlInteger(255, IntegerBase::Hexadecimal) → 0xFF).

Comparison with Other PHP Libraries

See Limitations for details.