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.
This library provides a comprehensive solution for working with TOML in PHP applications
- 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
You can install this library via composer:
composer require devium/toml
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));
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
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.
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);
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.
Contributions are welcome! Please feel free to submit a Pull Request
devium/toml is open-sourced software licensed under the MIT license.
Made with ❤️ in Ukraine