Toml Laravel Package

Technical Evaluation

Architecture Fit

• Laravel Compatibility: The package is framework-agnostic but integrates seamlessly with Laravel’s dependency injection and config systems. It requires no Laravel-specific dependencies, making it a lightweight, portable solution for TOML parsing/encoding.
• TOML 1.1 Support: Critical for cloud-native integrations (Terraform, Pulumi, Kubernetes) and modern TOML features like bare keys, dotted keys, and table arrays. The package’s spec compliance (verified via TOML 1.1.0) ensures no edge cases (e.g., mixed formatting, hex/octal numbers) break parsing.
• Performance: TOML is faster to parse than YAML/JSON for large configs, making it ideal for high-complexity configurations (e.g., SaaS multi-tenant settings). The package’s minimal API (parseToArray, encode) avoids overhead.
• AST Access: Enables advanced workflows (validation, transformation, schema enforcement) without reinventing parsing logic. Useful for dynamic config generation or TOML-to-DTO mapping.

Integration Feasibility

• Minimal Laravel Integration:
  • Service Provider: ~20 lines to load TOML configs (e.g., config/toml/) into Laravel’s config/array.
  • Config Merge: Extend Laravel’s MergeConfigReader to support TOML files alongside PHP/ENV/YAML.
  • Facade: Optional Toml::parse() facade for convenience.
• Existing Ecosystem:
  • No conflicts with Laravel’s built-in config system (TOML files can coexist with config/*.php).
  • Composer-friendly: Single composer require with no global state.
• Tooling Support:
  • Works with Laravel Forge, Envoyer, and Homestead for deployment.
  • Integrates with Laravel Mix/Vite for frontend TOML configs (e.g., feature flags).

Technical Risk

Key Questions

1. Use Case Prioritization:
   • Should we pilot TOML for Terraform/Pulumi configs first (high compliance risk) or feature flags (lower risk)?
   • Will we need TOML validation (e.g., schema enforcement)? If so, integrate with symfony/yaml or webonyx/graphql-php.
2. Laravel Integration Depth:
   • Should TOML configs merge with PHP configs (like config/array) or replace them entirely?
   • Do we need TOML-specific artisan commands (e.g., php artisan toml:validate)?
3. Performance Baseline:
   • Benchmark TOML vs. YAML/JSON for large configs (e.g., 10KB+). If TOML is not faster, reconsider.
4. Developer Adoption:
   • Should we deprecate YAML configs in favor of TOML, or support both?
   • Provide migration guides for teams using spatie/toml or custom parsers.
5. Long-Term Maintenance:
   • Monitor PHP 8.2+ compatibility as the package evolves.
   • Plan for TOML 1.2 (if/when released) by tracking upstream changes.

Integration Approach

Stack Fit

• Laravel Core:
  • Config System: TOML files can replace/augment config/*.php via a custom config reader.
  • Environment Configs: Use TOML for .env.toml (e.g., APP_DEBUG = true) alongside .env.
  • Caching: Leverage Laravel’s cache drivers to store parsed TOML (e.g., cache()->forever('toml:config', $parsedArray)).
• Tooling:
  • Laravel Forge/Envoyer: Deploy TOML configs alongside PHP assets.
  • Laravel Scout: Use TOML for search engine configs (e.g., Algolia settings).
  • Laravel Horizon: Configure queues in TOML for dynamic worker pools.
• Third-Party Integrations:
  • Terraform/Pulumi: Parse TOML outputs directly into Laravel configs.
  • Kubernetes: Use TOML for Helm values or ConfigMap/YAML generation.
  • AWS CDK: Generate TOML-compatible configs for CDK stacks.

Migration Path

Compatibility

• Laravel Versions: Tested on Laravel 9+ (PHP 8.1+). For Laravel 8, use a PHP 8.1 runtime or spatie/toml.
• TOML Spec: 1.1.0-compliant (supports 1.0.0 for backward compatibility).
• Data Types:
  • In: TOML strings, numbers, booleans, arrays, tables, dates, inline tables.
  • Out: PHP array, DateTimeImmutable, JsonSerializable.
• Edge Cases:
  • Bare keys (e.g., key = "value" vs. [key] = "value").
  • Dotted keys (e.g., database.host).
  • Table arrays (e.g., [[servers]]).

Sequencing

1. Phase 1: Parsing
   • Replace spatie/toml or custom parsers with internal/toml.
   • Focus on config loading (e.g., config/toml/).
2. Phase 2: Encoding
   • Use Toml::encode() for API responses, exportable configs, or dynamic TOML generation.
3. Phase 3: AST Workflows
   • Implement TOML validation, schema enforcement, or transformations using the AST.
4. Phase 4: Tooling
   • Add TOML support to Artisan, Laravel Forge, and CI/CD pipelines.

Operational Impact

Maintenance

• Dependency Updates:
  • Monitor internal/toml for TOML 1.2 or PHP 8.2+ compatibility.
  • No breaking changes expected (BSD-3-Clause license allows forks if needed).
• Laravel-Specific Logic:
  • Maintain a custom service provider (~20 lines) for TOML config loading.
  • Document TOML config conventions (e.g., file naming, key structures).
• Testing:
  • Add TOML parsing/encoding tests to Laravel’s test suite.
  • Use property-based testing (e.g., pestphp) for TOML edge cases.

Support

• Developer Onboarding:
  • Provide a TOML quick-start guide for Laravel teams.
  • Example: php artisan toml:make scaffold for new TOML configs