Weave Code
Toml Laravel Package
internal/toml
TOML 1.0.0/1.1.0 parser and encoder for PHP 8.1+. Parse TOML files straight into PHP arrays or encode arrays back to TOML, with support for tables, arrays of tables, and standard value types. A small, dependency-free tool for config files.
TOML parser and encoder for PHP 8.1+
Frequently asked questions about Toml
- How do I install internal/toml in a Laravel project?
- Run composer require internal/toml; the package requires PHP 8.1 or newer and has no other dependencies. There is no service provider, facade, or config file to register, so installation is just the Composer step. You then use the Internal\Toml\Toml class directly wherever you need parsing or encoding.
- Does internal/toml support Laravel 10 and Laravel 11?
- Yes. The package is framework-agnostic and only requires PHP 8.1+, which aligns with the PHP requirements of modern Laravel releases including 9, 10, and 11. It has no container wiring or framework coupling, so there is nothing to break on a Laravel upgrade. Because there is no published Laravel compatibility matrix, it is worth running the package through your own CI matrix before pinning it.
- How do I parse a TOML file into a PHP array in Laravel?
- Use Toml::parseToArray() and pass the file contents, for example Toml::parseToArray(file_get_contents(config_path('services.toml'))). You get a plain associative PHP array back, with nested tables as nested arrays and arrays of tables as lists of arrays. From there you can merge it into config() or hand it to your own configuration layer.
- How do I encode a PHP array back to TOML?
- Call Toml::encode($array) and cast the returned Stringable to a string. Nested associative arrays are emitted as TOML tables, and numeric-indexed arrays of associative arrays become arrays of tables. The encoder targets TOML 1.0 output for maximum interoperability even though the parser also accepts 1.1.0 input.
- What is the difference between Toml::parse and Toml::parseToArray?
- Toml::parseToArray returns plain PHP arrays, which is the simplest option for reading config. Toml::parse returns an AST Document that retains structure and formatting details such as comments, key order, and literal representations, which enables format-preserving round-trip edits. Use the AST when you need to modify a TOML file in place rather than blindly re-serialize it.
- Can I replace Laravel config/*.php files with TOML?
- You can use internal/toml as a thin loader that reads TOML files and merges the resulting arrays into Laravel's config repository, but TOML is static and declarative, so you lose PHP expressions, env() calls, and computed values. Keep in mind that php artisan config:cache serializes the merged config array, so you must re-run it after editing TOML files. A safer pattern is to confine TOML to low-criticality config or generated artifacts first and keep core app config in PHP.
- Does internal/toml support TOML 1.0.0 and TOML 1.1.0?
- Yes, the parser handles the TOML 1.0.0 and 1.1.0 specifications, including tables, arrays of tables, and the standard value types. The encoder deliberately targets TOML 1.0 output for interoperability with the widest set of TOML consumers. The changelog shows spec-conformance fixes around bare keys and scoped keys, which is a good sign for correctness.
- Is internal/toml safe to use in production?
- It is a reasonable low-risk dependency but not risk-free. The code is permissively BSD-3-Clause licensed, dependency-free, and actively released through 1.1.2, but it has a single maintainer, very few stars, and no known production dependents, and the README notes it was built with Claude Code. Pin an exact version, review diffs on upgrade, verify the internal/ vendor namespace is stable, and gate adoption on running the canonical toml-test suite internally.
- How do I test TOML parsing and encoding in a Laravel test suite?
- Because the API is stateless and has no container or global state, you can test it directly in Pest or PHPUnit without bootstrapping the application. Pass heredoc TOML strings to Toml::parseToArray() and assert the resulting arrays, then round-trip them through Toml::encode() and assert the output string. For extra confidence, wire the reference toml-test conformance suite into CI at the exact version you pin.
- What are the alternatives to internal/toml for parsing TOML in PHP?
- Other PHP TOML implementations exist, such as yosymfony/toml and devium/toml, and you can always hand-roll a minimal parser for a narrow subset of the spec. internal/toml differentiates itself with a dependency-free footprint, TOML 1.1 parsing, and an AST that supports format-preserving edits. Because its API is only three static methods, wrapping it behind a small adapter keeps a swap to an alternative to roughly a sprint of effort.
Weaver
How can I help you explore Laravel packages today?