Toml Laravel Package

Product Decisions This Supports

• Standardized Configuration Format: Replace fragmented config formats (JSON, YAML, INI) with TOML for PHP services, improving readability and tooling consistency. TOML’s structured syntax (tables, arrays, inline tables) aligns with modern infrastructure tools (Kubernetes, Terraform) and reduces cognitive load for nested configurations.
• Build vs. Buy: Buy to avoid reinventing TOML parsing/encoding logic, which would require deep validation against the TOML 1.1 spec. This package provides spec-compliant, dual functionality (parse/encode) with minimal maintenance overhead.
• Developer Experience (DX) Investments:
  • Dynamic Config Generation: Enable runtime TOML creation (e.g., for CI/CD pipelines, feature flags, or environment-specific overrides) via Toml::encode().
  • Schema Validation: Integrate with tools like toml-validator to enforce config schemas, reducing runtime errors.
  • Infrastructure as Code (IaC): Use TOML for generating Kubernetes manifests or Terraform configs from PHP data structures (e.g., Toml::encode($phpData)).
• Roadmap Priorities:
  • Multi-Format Config Support: Add TOML as an optional format in Laravel’s config/ directory or Symfony’s parameter bags, alongside YAML/JSON.
  • CLI Tooling: Adopt TOML for internal scripts (e.g., deployment generators, migration tools) where human-readable syntax and structured data are critical.
  • Open-Source Contribution: If TOML gains traction, propose this package as the standard library for PHP TOML support (similar to symfony/yaml).
• Use Cases:
  • Microservices: Store service-specific configs in TOML files (e.g., services/auth/config.toml) and load them via Toml::parseToArray().
  • Legacy Modernization: Replace hardcoded PHP configs or INI files with TOML for better maintainability and tooling (e.g., syntax highlighting, linting).
  • Dynamic Workflows: Generate TOML for external systems (e.g., Terraform, Kubernetes) from PHP data (e.g., Toml::encode($k8sManifest)).

When to Consider This Package

• Adopt When:

  • Your project requires TOML 1.0/1.1 (e.g., for configs, Kubernetes, or Terraform integration) and targets PHP 8.1+.
  • You need both parsing and encoding (e.g., to generate TOML from PHP data or edit TOML files programmatically).
  • Your team prioritizes spec compliance and maintainability over community size (this package is stable but has low activity).
  • You’re building a new project or migrating from ad-hoc formats (e.g., JSON, YAML, or INI) to a standardized config format.
  • Your stack includes Laravel, Symfony, or custom PHP frameworks where TOML aligns with DX goals (e.g., human-readable configs with structured data).

• Look Elsewhere If:

  • You need active community support or frequent updates (consider spatie/toml or rubix/ml-toml).
  • Your project targets PHP < 8.1 (this package drops support for older versions).
  • You require advanced TOML features (e.g., custom decoders, plugin systems) not covered in the basic API.
  • Your team prefers YAML or JSON for simplicity (TOML adds minor complexity for nested data but improves readability for configs).
  • You’re in a high-security context where package maturity (e.g., audit history, dependents) is critical (this package has no dependents and limited activity).

How to Pitch It (Stakeholders)

For Executives/Business Leaders:

"Adopting this TOML parser/encoder standardizes configuration management across our PHP services with a modern, industry-adopted format. TOML is used in Kubernetes, Terraform, and Rust ecosystems, and by adopting it, we align with best practices while reducing technical debt. This package provides a lightweight, dual parser/encoder (parse TOML to PHP arrays and encode PHP data to TOML) with full TOML 1.1 support, ensuring compatibility with our existing and future tools. The BSD-3 license and PHP 8.1+ focus minimize risks, and early adopters have successfully used TOML for configs, reducing errors and improving developer productivity. This is a low-risk, high-reward investment to future-proof our infrastructure."

For Engineering Teams:

*"Why TOML? It’s stricter than YAML/JSON (no trailing commas, explicit types) and more readable than INI for nested data. This package gives us:

• Parsing: Convert TOML configs (e.g., config.toml) to PHP arrays for runtime use.
• Encoding: Generate TOML from PHP data (e.g., for CI/CD templates, Kubernetes manifests, or dynamic configs).
• TOML 1.1 Support: Handles dates, booleans, inline tables, arrays, and edge cases like hex numbers or bare keys.
• PHP 8.1+: Leverages modern PHP features for performance and security.

Use Cases:

• Replace config.php or JSON/YAML configs with TOML for cleaner, version-controlled settings.
• Generate TOML for Terraform/Kubernetes from PHP data structures.
• Validate configs at runtime with Toml::parse() (throws on invalid TOML).

Setup:

composer require internal/toml

Example:

// Parse TOML to PHP array
$data = Toml::parseToArray(file_get_contents('config.toml'));

// Encode PHP to TOML
$toml = (string) Toml::encode(['database' => ['host' => 'localhost']]);

Trade-offs:

• Low stars/contributors (but stable and actively maintained by the author).
• PHP 8.1+ only (blocker if you’re on older versions).

Proposal:

1. Pilot: Use in one service (e.g., replace YAML configs for a microservice).
2. Standardize: Document TOML best practices (e.g., schema validation with toml-validator).
3. Expand: Roll out to CLI tools, Kubernetes manifests, or feature flags."*

For Developers:

*"Need to read/write TOML files in PHP? This package is your go-to solution:

• Parse TOML → PHP arrays: Toml::parseToArray(file_get_contents('config.toml')).
• Encode PHP → TOML: Toml::encode(['key' => 'value']).
• Supports TOML 1.1: Dates, booleans, inline tables, and arrays out of the box.

Example Use Cases:

• Replace Laravel’s config/ arrays with TOML files for better version control and readability.
• Generate TOML for Terraform or Kubernetes manifests from PHP data.
• Validate TOML configs at runtime with Toml::parse() (throws on invalid TOML).

Setup:

composer require internal/toml

Key Features:

• Round-trip preservation: Hex numbers (0xDEADBEEF) stay hex, not converted to decimals.
• AST support: Parse TOML into an Abstract Syntax Tree for advanced use cases (e.g., modifying TOML structure programmatically).
• DateTime support: Automatically serialize DateTimeImmutable objects to ISO 8601 format.

Trade-offs:

• Smaller community (but no critical bugs reported).
• PHP 8.1+ requirement (use rubix/ml-toml for older versions).

Next Steps:

• Try it in a non-critical service first.
• Pair with toml-validator for schema enforcement.
• Document TOML conventions for your team (e.g., file naming, key formats)."*