README

Devium/Toml

一个健壮且高效的PHP库，用于编码和解码符合TOML v1.0.0规范的格式

此库尽可能支持TOML规范。

概述

此库为PHP应用程序中处理TOML提供全面的解决方案

特性

• 将PHP数组和对编码为TOML格式
• 将TOML字符串解码为PHP数据结构
• 保留TOML中指定的数据类型
• 处理复杂的嵌套结构
• 支持TOML日期时间格式
• 具有提示信息的错误处理

安装

您可以通过composer安装此库

composer require devium/toml

用法

解码

$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));

编码

$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));

关于TOML日期时间格式

此库尝试将TOML日期时间格式解析为以下变体（根据规范）

• Devium\Toml\TomlDateTime（用于偏移日期时间）
• Devium\Toml\TomlLocalDatetime（用于本地日期时间）
• Devium\Toml\TomlLocalDate（用于本地日期）
• Devium\Toml\TomlLocalTime（用于本地时间）

示例

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

如果您使用

dump(toml_decode($toml, true));

TOML将被解析为数组

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
  }
]

每个类都实现了Stringable接口。

TomlLocal*类带有TomlDateTimeInterface标记，以提高可用性。每个类都有公共属性。

还有一个TomlDateTime类来支持TOML偏移日期时间格式。

当然，任何DateTimeInterface或TomlDateTimeInterface都会编码为TOML日期时间字符串。所以

$data = [
    'DateTimeInterface' => new DateTimeImmutable('1979-05-27T07:32:00Z'),
    'TomlDateTimeInterface' => new TomlDateTime('1979-05-27T07:32:00Z'),
];

将被编码为

DateTimeInterface = 1979-05-27T07:32:00.000Z
TomlDateTimeInterface = 1979-05-27T07:32:00.000Z

关于提示性错误

如果有解析错误，TomlError的消息中包含问题的大致位置。例如

Invalid TOML document: unexpected non-numeric value

5:  [owner]
6:  name = Tom Preston-Werner
             ^
7:  dob = 1979-05-31T07:32:00-08:00

否则它有关于整个输入的消息。

关于浮点值

解码器默认将每个浮点值作为字符串返回。

您可以通过设置$asFloat参数强制它返回浮点类型

toml_decode($toml, asFloat: true);
// or
\Devium\Toml\Toml::decode($toml, asFloat: true);

关于NULL

TOML不支持null值。

如果数组包含null值，将抛出异常。

表中的键只能是null值。编码时简单地跳过这样的键。

贡献

欢迎贡献！请随时提交Pull Request

许可证

devium/toml是开源软件，采用MIT许可证。

Vano Devium

在乌克兰用❤️制作