devium / toml
A PHP encoder/decoder for TOML compatible with specification 1.0.0
Fund package maintenance!
vanodevium
Installs: 6 380
Dependents: 2
Suggesters: 1
Security: 0
Stars: 21
Watchers: 2
Forks: 0
Open Issues: 0
Requires
- php: >=8.1
- ext-json: *
- php-ds/php-ds: ^1.5
- symfony/polyfill-mbstring: ^1.30
Requires (Dev)
- laravel/pint: ^1.17.1
- pestphp/pest: ^2.35
- phpstan/phpstan: ^1.11.9
- rector/rector: ^1.2.2
- symfony/var-dumper: ^6.4|^7.1
Suggests
- ext-ds: For best performance
- ext-mbstring: For best performance
README
Devium/Toml
A robust and efficient PHP library for encoding and decoding TOML compatible with v1.0.0
This library tries to support the TOML specification as much as possible.
Overview
This library provides a comprehensive solution for working with TOML in PHP applications
Features
- Encoding PHP arrays and objects to TOML format
- Decoding TOML strings into PHP data structures
- Preserves data types as specified in TOML
- Handles complex nested structures
- Supports TOML datetime formats
- Error handling with informative messages
Installation
You can install this library via composer:
composer require devium/toml
Usage
Decoding:
$toml = <<<TOML # This is a TOML document title = "TOML Example" [owner] name = "Tom Preston-Werner" dob = 1979-05-27T07:32:00-08:00 TOML; dump(\Devium\Toml\Toml::decode($toml, asArray: true)); dump(\Devium\Toml\Toml::decode($toml, asArray: false)); // or use global helper dump(toml_decode($toml, asArray: false)); dump(toml_decode($toml, asArray: true));
Encoding:
$data = [ "title" => "TOML Example", "owner" => [ "name" => "Tom Preston-Werner", "dob" => "1979-05-27T15:32:00.000Z", ], ]; dump(\Devium\Toml\Toml::encode($data)); // or use global helper dump(toml_encode($data));
About TOML datetime formats
This library tries to parse TOML datetime formats into next variants (according to the specification):
Devium\Toml\TomlDateTime
(for the offset date time)Devium\Toml\TomlLocalDatetime
(for the local date time)Devium\Toml\TomlLocalDate
(for the local date)Devium\Toml\TomlLocalTime
(for the local time)
Example:
offset-date-time-1 = 1979-05-27T07:32:00Z offset-date-time-2 = 1979-05-27T00:32:00-07:00 offset-date-time-3 = 1979-05-27T00:32:00.999999-07:00 offset-date-time-4 = 1979-05-27 07:32:00Z local-date-time-1 = 1979-05-27T07:32:00 local-date-time-2 = 1979-05-27T00:32:00.999999 local-date-1 = 1979-05-27 local-time-1 = 07:32:00 local-time-2 = 00:32:00.999999
If you use
dump(toml_decode($toml, true));
TOML will be parsed into array
array:9 [ "offset-date-time-1" => Devium\Toml\TomlDateTime @296638320 {#29 date: 1979-05-27 07:32:00.0 +00:00 } "offset-date-time-2" => Devium\Toml\TomlDateTime @296638320 {#35 date: 1979-05-27 00:32:00.0 -07:00 } "offset-date-time-3" => Devium\Toml\TomlDateTime @296638320 {#41 date: 1979-05-27 00:32:00.999999 -07:00 } "offset-date-time-4" => Devium\Toml\TomlDateTime @296638320 {#47 date: 1979-05-27 07:32:00.0 +00:00 } "local-date-time-1" => Devium\Toml\TomlLocalDateTime {#55 +year: 1979 +month: 5 +day: 27 +hour: 7 +minute: 32 +second: 0 +millisecond: 0 } "local-date-time-2" => Devium\Toml\TomlLocalDateTime {#61 +year: 1979 +month: 5 +day: 27 +hour: 0 +minute: 32 +second: 0 +millisecond: 999 } "local-date-1" => Devium\Toml\TomlLocalDate {#59 +year: 1979 +month: 5 +day: 27 } "local-time-1" => Devium\Toml\TomlLocalTime {#70 +millisecond: 0 +hour: 7 +minute: 32 +second: 0 } "local-time-2" => Devium\Toml\TomlLocalTime {#77 +millisecond: 999 +hour: 0 +minute: 32 +second: 0 } ]
Each class implements Stringable
interface.
TomlLocal*
classes are marked with TomlDateTimeInterface
for usability. Each class has public properties.
There is TomlDateTime
class to support TOML offset date time format also.
Of course any DateTimeInterface
or TomlDateTimeInterface
are encoded into TOML datetime string.
So
$data = [ 'DateTimeInterface' => new DateTimeImmutable('1979-05-27T07:32:00Z'), 'TomlDateTimeInterface' => new TomlDateTime('1979-05-27T07:32:00Z'), ];
will be encoded into
DateTimeInterface = 1979-05-27T07:32:00.000Z TomlDateTimeInterface = 1979-05-27T07:32:00.000Z
About informative errors
If there is parsing error, TomlError
has the approximate location of the problem in the message.
Something like:
Invalid TOML document: unexpected non-numeric value 5: [owner] 6: name = Tom Preston-Werner ^ 7: dob = 1979-05-31T07:32:00-08:00
Else it has message about whole input.
About floating-point values
The decoder returns each floating-point value as a string by default.
You can force it to return a float type by setting the $asFloat argument:
toml_decode($toml, asFloat: true); // or \Devium\Toml\Toml::decode($toml, asFloat: true);
About NULL
TOML does not support null values.
If the array contains a null value, an exception will be thrown.
The only thing possible is a null value for the keys in the tables. Such keys are simply skipped during encoding.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request
License
devium/toml is open-sourced software licensed under the MIT license.
Made with ❤️ in Ukraine