Toml Laravel Package

Product Decisions This Supports

• Standardized Configuration Format: Replace fragmented config formats (JSON, YAML, INI) with TOML across PHP services, improving maintainability and developer experience. TOML’s structured syntax (tables, arrays, inline tables) is ideal for nested configurations like database connections, feature flags, or multi-environment setups.
• Build vs. Buy Decision: Buy this package to avoid reinventing TOML parsing logic, which would require significant validation effort against the TOML 1.1 spec. The package’s dual parser/encoder reduces development time and ensures compliance with the spec (e.g., handling hex numbers, datetime formats, or bare keys correctly).
• Developer Experience (DX) Enhancements:
  • Round-Trip Editing: Enable developers to generate TOML files dynamically (e.g., for CI/CD pipelines, Kubernetes manifests, or cloud provider configs) and parse them back into PHP arrays for runtime use.
  • Schema Validation: Integrate with tools like toml-validator to enforce config schemas, reducing runtime errors.
  • CLI Tooling: Use TOML for internal CLI tools (e.g., deployment scripts, migration generators) where human-readable syntax and structured data are critical.
• Roadmap Priorities:
  • Multi-Format Config Support: Add TOML as an optional format alongside existing YAML/JSON in Laravel’s config/ directory or Symfony’s parameter bags.
  • Infrastructure as Code (IaC): Adopt TOML for Terraform or Kubernetes manifests generated from PHP (e.g., using this package to encode PHP data structures into TOML for IaC tools).
  • Open-Source Contribution: If TOML gains traction in PHP, contribute to or adopt this package as the standard library for TOML support (similar to symfony/yaml).
• Use Cases:
  • Microservices Configs: Store service-specific configurations in TOML files (e.g., services/auth/config.toml) and load them at runtime.
  • Dynamic Configuration Generation: Generate TOML files from PHP arrays (e.g., for feature flags, A/B testing rules, or environment-specific overrides).
  • Legacy System Modernization: Replace outdated INI files or hardcoded PHP configs with TOML for better maintainability and tooling support.

When to Consider This Package

• Adopt When:

  • Your project requires TOML 1.0/1.1 support (e.g., for configs, Kubernetes, or Terraform integration) and targets PHP 8.1+.
  • You need both parsing and encoding capabilities (e.g., to generate TOML from PHP data or edit TOML files programmatically).
  • Your team prioritizes maintainability and spec compliance 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 your 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/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
```"