PHPackages php-collective/toml - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Parsing & Serialization](/categories/parsing) 4. / 5. php-collective/toml ActiveLibrary[Parsing & Serialization](/categories/parsing) php-collective/toml =================== A TOML parser and encoder for PHP with AST access and collected parse errors 0.1.5(2mo ago)142.4k[1 issues](https://github.com/php-collective/toml/issues)[1 PRs](https://github.com/php-collective/toml/pulls)1MITPHPPHP >=8.2CI passing Since Mar 25Pushed 2mo ago1 watchersCompare [ Source](https://github.com/php-collective/toml)[ Packagist](https://packagist.org/packages/php-collective/toml)[ Docs](https://php-collective.github.io/toml/)[ RSS](/packages/php-collective-toml/feed)WikiDiscussions master Synced 3w ago READMEChangelog (6)Dependencies (8)Versions (23)Used By (1) PHP Toml ======== [](#php-toml) [![CI](https://camo.githubusercontent.com/ac5e0392d6be4ab1de233a62ced7ab8641defd1e366a92e4bb82e6d692d30272/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7068702d636f6c6c6563746976652f746f6d6c2f63692e796d6c3f6272616e63683d6d6173746572267374796c653d666c61742d737175617265)](https://github.com/php-collective/toml/actions)[![Latest Stable Version](https://camo.githubusercontent.com/faa33bc8670f4dfa8503c1d2a3aeafe90cc1bb9b6e04d578766e96d3621a33b3/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7068702d636f6c6c6563746976652f746f6d6c3f7374796c653d666c61742d737175617265)](https://packagist.org/packages/php-collective/toml)[![Total Downloads](https://camo.githubusercontent.com/b9b20c45da67d172a59a476eb62da77052496ee662cd62f0fed5cdd87bb0c1b1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7068702d636f6c6c6563746976652f746f6d6c3f7374796c653d666c61742d737175617265)](https://packagist.org/packages/php-collective/toml)[![PHPStan](https://camo.githubusercontent.com/fff00cebb924e124a7335e6bd8ca8f8cf38869463c1654eff45d0939f1f21c57/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d6c6576656c253230382d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](https://phpstan.org/)[![PHP Version](https://camo.githubusercontent.com/958da9c49ec5d3a994a485695225cd5ec57cc5b1e093b49892f65dd7ae8db3a9/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344382e322d3838393242462e7376673f7374796c653d666c61742d737175617265)](https://php.net)[![Software License](https://camo.githubusercontent.com/6c711032aff1ca0eb6b211aa6cb3649ce7fd64a7714e1181d4bb457f9680e7cf/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e2e7376673f7374796c653d666c61742d737175617265)](LICENSE) A [TOML](https://toml.io/) (v1.0 and v1.1) parser and encoder for PHP with AST access and collected parse errors. **[Documentation](https://php-collective.github.io/toml/)** Features -------- [](#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 ------------ [](#requirements) - PHP 8.2 or higher Installation ------------ [](#installation) ``` composer require php-collective/toml ``` Demo ---- [](#demo) - [Interactive Playground](https://sandbox.dereuromark.de/sandbox/toml) - Full-featured sandbox with all options. Quick Start ----------- [](#quick-start) ``` use PhpCollective\Toml\Toml; use PhpCollective\Toml\TomlVersion; // Decode TOML to PHP array $config = Toml::decode( [ 'host' => '0.0.0.0', 'port' => 8080, ], ]); ``` API Reference ------------- [](#api-reference) ### Decoding [](#decoding) ``` // Decode string - throws ParseException on error $array = Toml::decode($tomlString); // Decode file $array = Toml::decodeFile('/path/to/config.toml'); // Parse without throwing - for tooling $result = Toml::tryParse($tomlString); if ($result->isValid()) { $array = $result->getValue(); } else { foreach ($result->getErrors() as $error) { echo $error->format($tomlString); } } // Parse to AST for analysis $document = Toml::parse($tomlString); // Parse without exceptions and keep diagnostics + partial AST $result = Toml::tryParse($tomlString); $document = $result->getDocument(); ``` ### Encoding [](#encoding) ``` use PhpCollective\Toml\Encoder\DocumentFormattingMode; use PhpCollective\Toml\Encoder\EncoderOptions; use PhpCollective\Toml\Ast\Value\StringStyle; use PhpCollective\Toml\Ast\Value\StringValue; use PhpCollective\Toml\TomlVersion; // Encode to TOML string $toml = Toml::encode($array); // Encode directly to file Toml::encodeFile('/path/to/config.toml', $array); // With options - e.g. omit nulls instead of throwing $toml = Toml::encode($array, new EncoderOptions(skipNulls: true)); // Opt into multiline strings for long scalar strings $toml = Toml::encode($array, new EncoderOptions(multilineThreshold: 80)); // Opt into inline tables for small flat nested arrays $toml = Toml::encode($array, new EncoderOptions(inlineTableThreshold: 3)); // Strict TOML 1.0 output $toml = Toml::encode($array, new EncoderOptions(version: TomlVersion::V10)); // Emit integers in hexadecimal (or Octal / Binary) use PhpCollective\Toml\Ast\Value\IntegerBase; $toml = Toml::encode(['mask' => 255], new EncoderOptions(integerBase: IntegerBase::Hexadecimal)); // mask = 0xFF // encodeDocument() is normalized by default $document = Toml::parse($tomlString, true); $toml = Toml::encodeDocument($document); // Encode document directly to file Toml::encodeDocumentFile('/path/to/output.toml', $document); // Opt into source-aware formatting for minimal-diff AST re-encoding $document = Toml::parse($tomlString, true); $document->items[0]->value = new StringValue('new value'); $toml = Toml::encodeDocument( $document, new EncoderOptions(documentFormatting: DocumentFormattingMode::SourceAware), ); ``` `DocumentFormattingMode::SourceAware` is lossless for unchanged parsed regions and uses local fallback rules for edited ones. See the [Compatibility](https://php-collective.github.io/toml/reference/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 -------------- [](#error-handling) The parser provides detailed error messages: ``` Parse error: unterminated string 3 | name = "value | ^ 4 | other = 123 Hint: Did you forget to close the string with "? ``` For tooling, use `tryParse()` to collect all errors: ``` $result = Toml::tryParse($input); foreach ($result->getErrors() as $error) { // $error->message - Error description // $error->span - Position (line, column, offset) // $error->hint - Optional suggestion } ``` Supported Syntax ---------------- [](#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](https://php-collective.github.io/toml/reference/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 ----------------------------------- [](#comparison-with-other-php-libraries) Featurephp-collective/tomlOthersError RecoveryYesNoMultiple ErrorsYesNoAST AccessYesLimited/NoRound-trip formatting preservationPartialVariesSee [Limitations](https://php-collective.github.io/toml/reference/limitations) for details. ### Health Score 45 — FairBetter than 91% of packages Maintenance85 Actively maintained with recent releases Popularity29 Limited adoption so far Community9 Small or concentrated contributor base Maturity47 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~11 days Total 7 Last Release 68d ago Major Versions 0.1.5 → v1.x-dev2026-05-31 PHP version history (2 changes)0.1.0PHP >=8.2 v1.x-devPHP >=8.1 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/39854?v=4)[Mark Scherer](/maintainers/dereuromark)[@dereuromark](https://github.com/dereuromark) --- Top Contributors [![dereuromark](https://avatars.githubusercontent.com/u/39854?v=4)](https://github.com/dereuromark "dereuromark (58 commits)") --- Tags configurationphptomlconfigurationconfigparserencoderdeveloper-toolstoml ### Code Quality TestsPHPUnit Static AnalysisPHPStan Type Coverage Yes ### Embed Badge ![Health badge](/badges/php-collective-toml/health.svg) ``` [![Health](https://phpackages.com/badges/php-collective-toml/health.svg)](https://phpackages.com/packages/php-collective-toml) ``` ### Alternatives [matomo/matomo Matomo is the leading Free/Libre open analytics platform 21.7k39.6k](/packages/matomo-matomo)[hassankhan/config Lightweight configuration file loader that supports PHP, INI, XML, JSON, and YAML files 97413.9M194](/packages/hassankhan-config)[helsingborg-stad/municipio A bootstrap theme for creating municipality sites. 4028.6k10](/packages/helsingborg-stad-municipio)[yosymfony/toml A PHP parser for TOML compatible with specification 0.4.0 2101.8M91](/packages/yosymfony-toml)[m1/vars Vars is a simple to use and easily extendable configuration loader with in built loaders for ini, json, PHP, toml, XML and yaml/yml file types. It also comes with in built support for Silex and more frameworks to come soon. 69124.3k1](/packages/m1-vars)[romanpitak/nginx-config-processor Nginx configuration files processor. 7236.1k1](/packages/romanpitak-nginx-config-processor) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)