https://github.com/php-collective/toml
PHP library for encoding and decoding TOML
https://github.com/php-collective/toml
configuration php toml
Last synced: 2 months ago
JSON representation
PHP library for encoding and decoding TOML
- Host: GitHub
- URL: https://github.com/php-collective/toml
- Owner: php-collective
- License: mit
- Created: 2026-03-24T17:24:10.000Z (2 months ago)
- Default Branch: master
- Last Pushed: 2026-03-25T09:46:23.000Z (2 months ago)
- Last Synced: 2026-03-26T06:47:45.583Z (2 months ago)
- Topics: configuration, php, toml
- Language: PHP
- Homepage: https://php-collective.github.io/toml/
- Size: 252 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- fucking-awesome-php - Toml - A TOML parser and encoder with AST access and error recovery. (Table of Contents / Configuration)
- awesome-php - Toml - A TOML parser and encoder with AST access and error recovery. (Table of Contents / Configuration)
README
# PHP Toml
[](https://github.com/php-collective/toml/actions)
[](https://packagist.org/packages/php-collective/toml)
[](https://packagist.org/packages/php-collective/toml)
[](https://phpstan.org/)
[](https://php.net)
[](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
- 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
```bash
composer require php-collective/toml
```
## Demo
- [Interactive Playground](https://sandbox.dereuromark.de/sandbox/toml) - Full-featured sandbox with all options.
## Quick Start
```php
use PhpCollective\Toml\Toml;
use PhpCollective\Toml\TomlVersion;
// Decode TOML to PHP array
$config = Toml::decode(<<<'TOML'
[database]
host = "localhost"
port = 5432
TOML);
echo $config['database']['host']; // "localhost"
// Opt into strict TOML 1.0 parsing/decoding
$strict = Toml::decode('time = 07:32:00', TomlVersion::V10);
// Encode PHP array to TOML
$toml = Toml::encode([
'server' => [
'host' => '0.0.0.0',
'port' => 8080,
],
]);
```
## API Reference
### Decoding
```php
// 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
```php
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));
// Strict TOML 1.0 output
$toml = Toml::encode($array, new EncoderOptions(version: TomlVersion::V10));
// 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.
## 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:
```php
$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
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`
## Comparison with Other PHP Libraries
| Feature | php-collective/toml | Others |
|---------|---------------------|--------|
| Error Recovery | Yes | No |
| Multiple Errors | Yes | No |
| AST Access | Yes | Limited/No |
| Round-trip formatting preservation | Partial | Varies |
See [Limitations](https://php-collective.github.io/toml/reference/limitations) for details.