Download the PHP package petalbranch/toml without Composer

Petalbranch TOML

一个纯 PHP 实现的工业级 TOML 解析器与生成器（Parser & Dumper）。

基于词法分析（Lexer）与抽象语法树（AST）架构设计，将解析（Parse）与生成（Dump）彻底解耦。不仅提供高可靠的 TOML 读写能力，更具备 无损注释回写、O(1) 内存极速解析与等号对齐排版**等高级特性。

Language

• 中文
• English

✨ 核心特性

• 🧲 零学习成本 (Native-like DX) 提供开箱即用的全局辅助函数 toml_encode() 与 toml_decode()，肌肉记忆完美对标 PHP 原生的 JSON 函数，体验极其丝滑。
• 🛡️ 工业级类型安全 (PHPStan Level 9) 全代码满级通过 PHPStan（Level 9）静态分析，消灭一切隐式转换与类型盲区，提供绝对可靠的代码质量。
• 🚀 O(1) 内存极速解析 (Zero-Copy Lexer) 抛弃低效的 mb_str_split，采用底层字节游标与动态 UTF-8 探针技术。无论解析 1KB 还是 100MB 的配置文件，内存占用均趋近于 O( 1)，无惧超大体积文件。
• 🔄 真正的无损回写 (Lossless Round-Trip) AST 树完整保留开发者编写的前导注释与行尾注释。支持直接修改 AST 节点并重新 Dump，注释与排版原封不动，完美胜任“配置可视化面板”的底层引擎。
• 💅 极致美学转储 (Alignment Formatting) Dumper 支持智能等号对齐，自动计算键名视觉宽度（完美兼容中文字符与 Emoji），转储出极具秩序美的 TOML 代码。
• 🎯 严格规范实现 (Spec-Compliant) 完整通过 toml-test v2.1.0 测试套件：Decoder 100% 通过，Encoder 99.5% 通过。
• 🔍 精准错误诊断 (Rich Error Reporting) 提供结构化错误、源码片段与精确定位（行/列/像素级指针）。
• ⏱️ 原生时间类型支持 完整覆盖 TOML 1.1.0 时间模型（Offset / Local / Date / Time）。

❌ 精准错误诊断（Rich Error Reporting）

当 TOML 格式非法时，解析器会提供结构化错误信息 + 精确定位 + 上下文片段。游标指针（^ ）不仅能精确定位列数，还能根据全角/半角字符（如中文、Emoji）自动计算视觉宽度，实现像素级对齐：

支持的错误类型（部分）：

• UNEXPECTED_TOKEN：非法语法结构
• INVALID_CHAR：非法字符
• INVALID_TYPE：类型错误
• CONFLICTING_KEY：键冲突
• INVALID_TABLE_DEFINITION：非法表定义

每个错误均包含：

• 行号 / 列号
• 原始代码片段
• 精确指针（^）
• 可读错误描述

👉 不仅是解析器，也可以作为 TOML Linter / 校验工具 使用。

此外，详细错误信息是可配置的（默认开启）：

🔄 无损回写与动态修改 (Lossless Round-Trip)

大多数解析器在转储时会丢失注释。本库允许你直接操作 AST（抽象语法树），修改值后重新 Dump，所有注释和排版将被完美保留：

💅 极致美学转储 (Alignment Formatting)

强迫症福音！开启 alignEquals 配置后，Dumper 会自动预扫描同一层级的键名，并使用空格智能对齐所有等号：

🧪 测试覆盖（toml-test）

本项目基于官方 toml-test v2.1.0 测试套件进行验证：

说明：

• 解析（Decoder）：100% 通过
• 非法用例（Invalid）：100% 正确拒绝
• 生成（Encoder）：仅 1 项边界差异（不影响主流使用场景）

👉 覆盖 TOML 规范的大量边界情况，保证实现的可靠性与一致性。

⚠️ 唯一失败用例说明（encoder/key/quoted-unicode）：

该用例包含 \u0000（空字节）作为键名，并通过 JSON 传入编码器。 由于 PHP 在字符串/数组键层面对空字节存在底层限制，且 JSON 解析链路无法可靠承载该键，导致输入在进入编码器前即被判定为非法（ Invalid JSON input）。

👉 该行为与本库的「已知限制」一致，不影响常规 TOML 使用场景。

🤔 为什么选择 Petalbranch TOML？

🧠 架构简述

📦 安装

通过 Composer 安装（需要 PHP 8.3+）：

🚀 快速开始

0. 丝滑的全局辅助函数 (推荐)

如果你熟悉 PHP 的 JSON 函数，那么你已经掌握了本库 90% 的用法：

1. 解析 TOML (Parse)

2. 生成 TOML (Dump)

🎯 使用场景

• 配置文件解析（替代 JSON / YAML）
• CLI 工具配置系统
• 框架配置层（Webman / Laravel 风格）
• TOML 校验工具（CI / Lint）
• 构建工具 / 包管理器

⚙️ 性能与生产环境建议

在生产环境中，建议将解析后的 PHP 数组进行缓存以达到极致性能（如使用 OPcache）：

⚠️ 已知限制（Known Limitations）

由于 PHP 底层哈希表对象模型的限制，本库不支持使用空字节（\u0000）作为对象的键名。这在正常工程实践中极度罕见。

📄 开源协议

本项目基于 Apache License 2.0 协议开源 - 查看 LICENSE 文件了解更多细节。