Toml Laravel Package

Product Decisions This Supports

• Build vs. buy on parsing infrastructure. TOML looks trivial and isn't. The 1.0.0 spec carries four datetime types, dotted keys, inline tables, arrays of tables, multi-line literal strings, and strict round-trip rules. A compliant, fuzzed parser is a multi-week engineering sink; a 41-star MIT dependency is a cheap "buy" provided it passes conformance. This package is the buy-side of that decision.
• Interoperability scope for developer-facing features. This only earns roadmap space if a planned feature must read or emit files owned by another ecosystem: pyproject.toml, Cargo.toml, Hugo/Zola/Netlify configs, or CI manifests. That is a genuine decision for CLI tools, project scaffolders, codegen utilities, and import/migration wizards — and a non-decision for a typical CRUD SaaS.
• Config import/export feature scope. It unlocks one concrete user story: "import my existing Rust/Python project config into our dashboard," or "export this project as a TOML manifest." If that story is not on the roadmap with a named owner, TOML is a format checkbox, not a feature.
• Format conversion as an internal capability. The realistic use is a pipeline — TOML → PHP array → validated internal model → JSON/YAML out. The parser is a component of that pipeline, never the product.
• Laravel integration depth. A second, separate decision: composer require plus a service class, or a full service provider, Toml facade, config/*.toml loader, and Artisan command? With zero dependents and modest adoption, the correct answer is almost always the thin adapter, not the framework-native driver.
• Portfolio priority. Treat it as a utility dependency, not a strategic bet. It will not move conversion, retention, or differentiation, and it should be scheduled inside the feature that needs the format — never as its own roadmap line.

Planning verdict: a narrow, low-regret, low-upside dependency. Approve it only as a leaf node inside a feature that already has a business case and a customer.

When to Consider This Package

Adopt when:

• You have a hard, externally dictated interop requirement — a partner format, a language ecosystem, or a file format you do not control — and TOML is unavoidable.
• You need both directions (decode and encode). Read-only config loading is rarely worth a parser dependency in Laravel, where PHP arrays and JSON are already first-class.
• You need fidelity on the awkward parts: datetimes, arrays of tables, dotted keys, inline tables. If your inputs are flat key/value files, you are paying for capability you will not use.
• You need to emit TOML for another tool to consume — correct string escaping, table ordering, and inline-vs-standard table selection are deceptively fiddly, and this is where a library earns its keep.
• Your risk tolerance allows a pinned, vendored dependency. Pin the version, wrap it behind your own interface, and assume you may inherit maintenance.

Look elsewhere — or say no — when:

• The requirement is really "configuration." Laravel already ships PHP config arrays, .env, and first-class JSON/YAML tooling. Adding TOML to your own product's config surface is a self-inflicted support burden with no user demand.
• You only need validation. A parser gives you syntax, not schema. "Reject bad configs" still requires your own validator or a conversion into JSON Schema — budget for it separately.
• You need lossless, comment-preserving round-trips. Most parsers model values, not documents. If users edit files in your UI and you write them back, verify this before committing. If it fails, you need a format-preserving parser and this is not it.
• You need throughput. Large-file or hot-path parsing in PHP is CPU-bound. Benchmark first; the answer there is caching parsed results, not a faster TOML library.
• You need vendor-backed longevity, SLAs, or security response. Single maintainer, no dependents, bus-factor risk. Compare against established alternatives (e.g. yosymfony/toml) and against simply owning a small fork.
• You have not verified conformance. Before writing code: run the official toml-test valid and invalid corpora, confirm PHP version support against your matrix, confirm errors include line/column, and check the parse path for eval, unserialize, or other unsafe constructs.

Gate to pass before adoption: conformance suite green, license clean (MIT — fine), no transitive surprises, last commit within ~18 months, and a written "what happens if upstream goes quiet" plan.

How to Pitch It (Stakeholders)

For executives — one paragraph. This is a small, MIT-licensed PHP library that lets our product read and write TOML, the configuration format used across the Rust and Python tooling ecosystems. It is not a strategic investment; it is a bolt-on that unlocks one specific integration — importing or exporting project configuration from those ecosystems — and it costs us nothing in license fees. The risk is maintenance, not money: it is a single-maintainer project, so we would pin the version, wrap it behind our own interface, and be ready to take the code over if needed. Recommendation: approve it only as a component inside a feature that already has a customer or roadmap owner. We should not adopt TOML as a supported config format for our own product without a specific demand signal.

For engineering — the ask:

• Do not hand-roll a parser. If we need TOML at all, buying is cheaper than a compliant, fuzzed implementation.
• Wrap it, don't spread it. One TomlCodec contract, one adapter, zero direct library calls in domain code — that gives us a swap path and a fork path in a single file.
• Prove conformance before merge. Run the toml-test valid and invalid corpora in CI, plus our own fixtures for datetimes, arrays of tables, and inline tables. Normalize exceptions into our own error type with file/line/column; raw parser errors must not leak into user-facing output.
• Confirm the integration ceiling. Default position: a service class, not a service provider. Only build a Laravel config driver or Toml facade if a roadmap feature explicitly calls for TOML as a first-class config format.
• Gate the write path. Encoding is higher-risk than decoding — type coercion, key ordering, and escaping can silently corrupt config. Enable TOML output only after round-trip tests pass; otherwise emit JSON/YAML on write.
• Record the contingency. Note the fork point, the pinned version, and the reassessment trigger: upstream inactive >12 months, a CVE, or a conformance regression.