Toml Laravel Package

Product Decisions This Supports

• Standardized Configuration Format: Adopt TOML as the primary configuration format for Laravel applications, replacing fragmented YAML/JSON/INI files. This aligns with the roadmap to modernize infrastructure-as-code (IaC) workflows and integrates seamlessly with tools like Terraform, Pulumi, and Kubernetes, which natively use TOML.
• Build vs. Buy Decision: Avoid reinventing TOML parsing logic (e.g., regex-based solutions or custom scripts) by leveraging a spec-compliant, maintained library. This reduces technical debt, improves reliability, and ensures compatibility with TOML 1.1 features (e.g., bare keys, table arrays).
• Dynamic Configuration and Feature Flags: Use TOML’s structured yet human-readable format for runtime configurations, environment-specific settings, or feature toggles. The round-trip editing and format preservation (e.g., hex numbers, comments) enable developers to modify TOML files directly without losing structure.
• Performance Optimization: Replace slower YAML/JSON configs for large-scale configurations (TOML is faster to parse in many cases) while maintaining readability. Ideal for applications with high-configuration complexity (e.g., SaaS platforms with multi-tenant settings).
• API and Data Export Use Cases: Generate TOML-formatted API responses or exportable data structures using the encoder’s support for DateTime, JsonSerializable, and nested tables. This expands Laravel’s data interchange capabilities beyond JSON/YAML.
• Developer Experience (DX) Improvements: Reduce onboarding friction for teams unfamiliar with TOML by providing a consistent, Laravel-agnostic API (Toml::parseToArray(), Toml::encode()). The AST access enables advanced workflows like validation or schema enforcement without custom code.
• Infrastructure Modernization: Enable native TOML support for Laravel’s integration with cloud-native tools (e.g., Terraform modules, Kubernetes manifests). This reduces manual conversion steps and ensures consistency across IaC pipelines.

When to Consider This Package

• Adopt if:
  • Your Laravel application requires TOML 1.1 compliance (e.g., bare keys, dotted keys, table arrays) for integration with Terraform, Pulumi, or Kubernetes.
  • You need reliable parsing of complex TOML syntax, including edge cases like mixed formatting ([key] = "value" vs. [key]="value") or hex/octal numbers.
  • Your team uses TOML for configuration files (e.g., config/toml/) and wants to eliminate manual parsing, ensuring consistency and reducing errors.
  • You require round-trip TOML editing (e.g., parsing, modifying, and re-encoding TOML files without losing comments, formatting, or structure).
  • Your project targets PHP 8.1+ and can accommodate a lightweight, dependency-agnostic package with a minimal API.
  • You need AST access for advanced use cases like TOML validation, transformation, or schema enforcement.
  • Your use case involves large-scale configurations where TOML’s performance (faster than YAML/JSON) is critical.
  • You’re migrating from YAML/JSON to TOML for better readability and tooling compatibility (e.g., cloud-native workflows).
• Look elsewhere if:
  • Your use case is simple TOML parsing/encoding without TOML 1.1 features, where a lighter package like spatie/toml (TOML 0.5.0) may suffice.
  • You require Laravel-specific integrations (e.g., service providers, config loader hooks, or merge() logic for config/array files). This package is framework-agnostic; consider building a thin wrapper or using vlucas/phpdotenv for Laravel-native config loading.
  • Your stack is not PHP-based or relies on non-Laravel frameworks (e.g., Symfony, where rubix/toml or Symfony’s YAML component may be better suited).
  • You prioritize write-heavy TOML generation (e.g., creative TOML output) over parsing, as this package’s strengths lie in spec-compliant ingestion.
  • You need real-time TOML validation or schema enforcement, which would require additional logic (e.g., integrating with symfony/yaml or webonyx/graphql-php for validation rules).
  • Your team lacks PHP 8.1+ support or cannot adopt a new dependency due to legacy constraints (e.g., shared hosting environments).

How to Pitch It (Stakeholders)

For Executives: "Adopting internal/toml (1.1.2) future-proofs our Laravel applications by ensuring seamless integration with modern cloud-native tools like Terraform, Pulumi, and Kubernetes—reducing integration errors and accelerating our IaC adoption. This package resolves critical TOML 1.1 compliance gaps (e.g., bare keys, table arrays), directly improving CI/CD reliability and developer productivity. With a minimal dependency and no vendor lock-in, we gain a spec-compliant, PHP-core-maintained TOML parser, aligning us with industry trends while reducing technical debt in configuration management. The investment is low-risk and high-reward for our infrastructure modernization roadmap."

For Engineering (Technical Leadership): *"We’re adopting internal/toml 1.1.2 to:

1. Fix TOML 1.1 parsing: Resolves issues with bare keys, dotted keys, and table arrays, ensuring compatibility with Terraform, Pulumi, and Kubernetes manifests.
2. Enable round-trip TOML editing: Supports parsing, modifying, and re-encoding TOML files without losing structure, comments, or formatting (e.g., hex numbers stay hex).
3. Reduce technical debt: Eliminates custom TOML parsers, saving time and reducing bugs in configuration handling.
4. Future-proof Laravel: As TOML becomes the default for cloud-native configs, this package keeps us aligned with modern workflows. Tradeoffs:

• The package is PHP-core maintained (not Laravel-specific), but the 1.1.2 fixes address real-world pain points (e.g., #5 for same-key names in different scopes).
• For simple use cases, spatie/toml might suffice, but this is the only TOML 1.1-compliant option for Laravel.
• Integration effort: Requires a custom service provider (~20 lines) to load TOML configs, but the payoff is worth it for strict compliance and performance gains over YAML/JSON. Recommendation: Start with a pilot in the infrastructure team (e.g., Terraform configs) and expand to feature flags or multi-tenant settings."*

For Developers: *"This package lets you work with TOML in Laravel like a pro:

• Parse TOML to PHP arrays in one line:

  $config = Toml::parseToArray(file_get_contents('config.toml'));
  

• Encode PHP data back to TOML with format preservation:

  $toml = (string) Toml::encode($phpArray); // Hex numbers stay hex!
  

• Edit TOML files programmatically with an AST for advanced use cases (e.g., validation, transformation).
• No more TOML syntax headaches: Handles bare keys, table arrays, and complex nested structures out of the box.
• Supports modern PHP features: Works with DateTimeImmutable, JsonSerializable, and custom objects. Getting started:

1. Install via Composer: composer require internal/toml.
2. Use Toml::parseToArray() for parsing or Toml::encode() for generation.
3. For Laravel configs, create a service provider to auto-load TOML files from config/toml/. Example use case: Replace config/app.php with config/app.toml for cleaner, tool-friendly configurations!"*