petalbranch/toml

A TOML parser and generator for PHP

Maintainers

Details

github.com/PetalBranch/toml

Source

Issues

Installs: 1

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 0

Forks: 0

Open Issues: 0

pkg:composer/petalbranch/toml

v1.0.2 2025-10-14 10:26 UTC

Requires

Requires (Dev)

MIT 6142542c44e2bbf645975c95994389b83337e00e

  • Petalbranch <branch.woop@petalmail.com>

This package is auto-updated.

Last update: 2025-10-14 10:28:47 UTC

README

😜 本人学艺不精，如有问题请及时反馈。

简介

PetalBranch/toml 是一款 PHP 库，用于 解析 TOML 字符串 或 生成 TOML 字符串。
它能够方便地在 PHP 中处理 TOML 数据结构，支持数组和对象，兼容 TOML 1.0 规范。

适用场景：

  • 配置文件管理（如应用配置、服务配置）
  • 将 PHP 数据结构序列化为 TOML
  • 支持多维数组和对象嵌套编码
  • 保持日期时间、浮点数、布尔值等原始类型

特性

  • 兼容 TOML 1.0 规范
  • 支持 PHP 数组和对象 直接编码
  • 支持 多维数组和对象嵌套
  • 日期时间类型格式支持：
    • 本地日期 (YYYY-MM-DD)
    • 本地时间 (HH:MM:SS)
    • 本地日期时间 (YYYY-MM-DDTHH:MM:SS)
    • 带时区的日期时间 (YYYY-MM-DDTHH:MM:SS±HH:MM)
  • 支持 布尔、整数、浮点、字符串 类型
  • 特殊字符（换行、制表符、引号等）自动转义
  • 键名支持 空格、中文及特殊字符
  • 生成的 TOML 文件可以被大多数 TOML 解析器解析

安装

PHP 版本要求：>= 8.0
⚠ 开发环境：PHP 8.3 , 低于此版本请先自行测试。

  • 使用 Composer 安装 （推荐）

    composer require petalbranch/toml

  • 手动下载

    从 GitHub 仓库下载最新版本 ZIP 文件：
    https://github.com/PetalBranch/toml
    🏷Tags
    将所有内容解压到项目目录，例如 vendor/petalbranch/toml
    在 PHP 文件中引入自动加载文件或手动 require：

    // 加载辅助函数
require_once 'vendor/petalbranch/toml/src/helpers.php';
// 加载类文件
require_once 'vendor/petalbranch/toml/src/Toml.php';

快速开始

  • 生成 TOML 字符串

    • 参考数据

      <?php
$data = [
          'title' => "TOML 示例",

          'owner' => [
              'name' => "Tom Preston-Werner",
              'dob' => new DateTimeImmutable("1979-05-27T07:32:00-08:00")
          ],
          'database' => [
              'enabled' => true,
              'ports' => [8001, 8001, 8002],
              'data' => [["delta", "phi"], [3.14]],
              'temp_targets ' => [
                  'cpu' => 79.5,
                  'case' => 72.0
              ],
          ],
          'servers' => [
              'alpha' => [
                  'ip' => '10.0.0.1',
                  'role' => '前端'
              ],
              'beta' => [
                  'ip' => '10.0.0.2',
                  'role' => '后端'
              ]
          ],
      ];

    • 辅助函数

      <?php
// $data 引入参考数据
$result = toml_encode($data);
echo $result;

    • 类方法

      <?php
// $data 引入参考数据
use Petalbranch\Toml\Toml;
$result = Toml::encode($data);
echo $result;

    • 生成的 TOML 文件内容如下：

      title = "TOML 示例"
[owner]
name = "Tom Preston-Werner"
dob = 1979-05-27T07:32:00-08:00

[database]
enabled = true
ports = [8000, 8001, 8002]
data = [["delta", "phi"], [3.14]]
[database.temp_targets ]
cpu = 79.5
case = 72.0


[servers]
[servers.alpha]
ip = "10.0.0.1"
role = "前端"

[servers.beta]
ip = "10.0.0.2"
role = "后端"

  • 解析 TOML 字符串

    • 参考数据

      # 这是一个 TOML 文档

title = "TOML 示例"

[owner]
name = "Tom Preston-Werner"
dob = 1979-05-27T07:32:00-08:00

[database]
enabled = true
ports = [ 8000, 8001, 8002 ]
data = [ ["delta", "phi"], [3.14] ]
temp_targets = { cpu = 79.5, case = 72.0 }

[servers]

[servers.alpha]
ip = "10.0.0.1"
role = "前端"

[servers.beta]
ip = "10.0.0.2"
role = "后端"

    • 辅助函数

      // $toml 引入参考数据
$result = toml_decode($toml);
var_dump($result);

    • 类方法

      // $toml 引入参考数据
use Petalbranch\Toml\Toml;
$result = Toml::decode($toml);
var_dump($result)

    • 生成的 PHP 数据结构如下：

      array(4) {
["title"]=>
string(11) "TOML 示例"
["owner"]=>
array(2) {
    ["name"]=>
    string(18) "Tom Preston-Werner"
    ["dob"]=>
    object(DateTimeImmutable)#47 (3) {
    ["date"]=>
    string(26) "1979-05-27 07:32:00.000000"
    ["timezone_type"]=>
    int(1)
    ["timezone"]=>
    string(6) "-08:00"
    }
}
["database"]=>
array(4) {
    ["enabled"]=>
    bool(true)
    ["ports"]=>
    array(3) {
    [0]=>
    int(8000)
    [1]=>
    int(8001)
    [2]=>
    int(8002)
    }
    ["data"]=>
    array(2) {
    [0]=>
    array(2) {
        [0]=>
        string(5) "delta"
        [1]=>
        string(3) "phi"
    }
    [1]=>
    array(1) {
        [0]=>
        float(3.14)
    }
    }
    ["temp_targets"]=>
    array(2) {
    ["cpu"]=>
    float(79.5)
    ["case"]=>
    float(72)
    }
}
["servers"]=>
array(2) {
    ["alpha"]=>
    array(2) {
    ["ip"]=>
    string(8) "10.0.0.1"
    ["role"]=>
    string(6) "前端"
    }
    ["beta"]=>
    array(2) {
    ["ip"]=>
    string(8) "10.0.0.2"
    ["role"]=>
    string(6) "后端"
    }
}
}

使用示例

解析 TOML 字符串 与 生成 TOML 字符串 常规示例请参考👉快速开始

多维数组与对象支持

// 创建对象
class Server {
    public string $host = 'localhost';
    public int $port = 8080;
}

// 创建多维数组
$data = [
    'servers' => [
        'alpha' => new Server(),
        'beta'  => new Server(),
    ]
];

// 生成 TOML
echo TomlEncode::encode($data);

生成的 TOML 文件内容如下：

[servers]
[servers.alpha]
host = "localhost"
port = 8080

[servers.beta]
host = "localhost"
port = 8080

特殊字符与字符串转义

$data = [
    'text' => "特殊字符: \"\t\n\r",
    'path' => "C:\\User\\Desktop"
];

echo TomlEncode::encode($data);

生成的 TOML 文件内容如下：

text = "特殊字符: \"\t\n\r"
path = "C:\\User\\Desktop"

类型支持与转换说明

以下是 PHP 类型与 TOML 类型的对应关系说明。

PHP 类型 TOML 类型 示例值 输出示例
string 字符串 "hello" key = "hello"
int 整数 42 key = 42
float 浮点数 / 科学计数法 1.23, 6.626e-34 key = 1.23 或 key = 6.626e-34
bool 布尔值 true, false key = true
null 不支持 — —
array（索引数组） 数组 [1, 2, 3] key = [1, 2, 3]
array（关联数组） 表（table） ['a' => 1, 'b' => 2] [key] a = 1 b = 2
object 表（table） new User() [user] name = "xxx"
DateTimeInterface 带时区日期时间 new DateTimeImmutable('2024-01-01T00:00:00Z') key = 2024-01-01T00:00:00+00:00
TomlLocalDate 本地日期 — key = 2024-01-01
TomlLocalTime 本地时间 — key = 07:32:00
TomlLocalDateTime 本地日期时间 — key = 2024-01-01T07:32:00

注意事项

  • 浮点数：
    • PHP 中的 INF, -INF, NAN 会被输出为 inf, -inf, nan
    • 超大或极小的数会自动转为科学计数法表示
  • 字符串：
    • 自动转义特殊字符，如 \n, \t, \", \\ 等
  • 键名：
    • 含空格、中文或特殊字符的键名会自动加引号，例如 
      "含空格 键名" = "值"
"中文键" = "测试"

许可证