Toml Laravel Package

Technical Evaluation

Architecture Fit

• TOML as a Configuration Standard: Fits Laravel’s need for structured, human-readable configs (e.g., replacing config.php arrays or JSON/YAML). TOML’s explicit syntax (e.g., tables, arrays) aligns with Laravel’s service container and environment management.
• Dual Parser/Encoder: Critical for Laravel’s dynamic config generation (e.g., encoding PHP arrays to TOML for Kubernetes manifests) and runtime parsing (e.g., loading config.toml files).
• TOML 1.1 Compliance: Supports modern features like inline tables, date-time parsing, and hex/octal numbers, which are useful for:
  • Database configs (e.g., ports = [8000, 0x1F40]).
  • Feature flags (e.g., enabled = true with explicit booleans).
  • Multi-environment setups (e.g., dev.toml, prod.toml with shared schemas).
• AST Support: Enables advanced use cases like:
  • Schema validation (e.g., ensure required keys exist before parsing).
  • Partial updates (e.g., merge TOML files at runtime).
  • Custom encoding logic (e.g., serialize Laravel collections to TOML).

Technical Risk

• Low Risk:
  • Stable API: Minimal breaking changes (TOML 1.1 support added in 1.1.0).
  • No External Dependencies: Pure PHP; no risk of transitive vulnerabilities.
  • PHP 8.1+ Only: Aligns with Laravel’s modern stack (PHP 8.0+).
• Mitigable Risks:
  • Limited Adoption: No dependents or active community (but BSD-3 license allows forks if needed).
  • Edge Cases: TOML 1.1 features (e.g., bare keys, multi-line literals) may require testing.
  • Performance: AST parsing adds overhead for large configs (benchmark against spatie/toml if critical).
• Critical Questions:
  1. Does Laravel’s config system need TOML’s strictness? (TOML rejects trailing commas; JSON/YAML may be more forgiving.)
  2. Will TOML replace .env files? (TOML is better for structured data; .env is still needed for secrets.)
  3. How will this integrate with Laravel’s config() helper? (Need a service provider to auto-load TOML files.)
  4. What’s the migration path from JSON/YAML? (Tooling needed to convert existing configs.)
  5. How will this handle Laravel’s cached configs? (TOML files may need to be re-parsed on changes.)

Integration Approach

Stack Fit

• Laravel Compatibility:
  • PHP 8.1+: Works with Laravel 9/10 (PHP 8.0+).
  • Service Provider: Bind Toml class to Laravel’s container for dependency injection.
  • Config Loading: Replace config.php arrays with TOML files in config/ directory.
  • Artisan Commands: Use TOML for CLI tool configs (e.g., php artisan config:toml).
• Symfony Compatibility:
  • Works with Symfony’s ParameterBag or YamlFileLoader replacements.
  • Can integrate with Symfony’s config component for framework-wide TOML support.

Migration Path

1. Pilot Phase:
   • Replace one config file (e.g., database.php) with database.toml.
   • Use a service provider to auto-parse TOML files:

     // app/Providers/TomlConfigServiceProvider.php
     public function register() {
         $toml = new \Internal\Toml\Toml();
         $config = $toml->parseToArray(file_get_contents(config_path('toml.php')));
         $this->app->instance('config.toml', $config);
     }
     

2. Gradual Rollout:
   • Add a toml.php config loader alongside existing JSON/YAML configs.
   • Use facades or helpers to unify access:

     // config('database.connection') // Works for TOML/JSON/YAML
     

3. Tooling:
   • Build an Artisan command to convert JSON/YAML to TOML:

     php artisan config:convert json_to_toml
     

   • Add TOML validation to Laravel’s config:cache command.

Compatibility

• TOML vs. Laravel’s Config:
  • Pros: TOML’s tables map to Laravel’s nested arrays; arrays of tables support dynamic configs.
  • Cons: TOML lacks environment variables (use .env for secrets).
  • Workaround: Merge TOML with .env (e.g., config('database.host') falls back to .env).
• Encoding Edge Cases:
  • Laravel Collections: Implement JsonSerializable for custom encoding.
  • Carbon Instances: Use DateTimeImmutable support for dates.
  • Hex/Octal Numbers: Preserved in round-trips (e.g., 0xDEADBEEF stays hex).

Sequencing

1. Phase 1: Parse TOML configs (replace config.php).
2. Phase 2: Add encoding (generate TOML from PHP arrays).
3. Phase 3: Integrate with Laravel’s cache and validation systems.
4. Phase 4: Deprecate JSON/YAML configs in favor of TOML (long-term).

Operational Impact

Maintenance

• Pros:
  • No External Dependencies: Easy to audit and update.
  • Lightweight: Minimal runtime overhead for parsing.
  • BSD-3 License: Allows forks or modifications if needed.
• Cons:
  • Author Support: Relies on a single maintainer (monitor GitHub/Patreon for updates).
  • Testing: TOML 1.1 edge cases (e.g., bare keys, multi-line literals) may need custom tests.
• Mitigation:
  • Add to CI: Test TOML parsing/encoding in Laravel’s test suite.
  • Document: Create a README.md for Laravel-specific usage (e.g., config loading).

Support

• Debugging:
  • AST Errors: TOML parsing errors include line numbers (helpful for debugging).
  • Round-Trip Issues: Use Toml::encode() + Toml::parseToArray() to verify data integrity.
• Community:
  • GitHub Issues: Low activity; expect slower responses than spatie/toml.
  • Alternatives: spatie/toml has more stars but lacks encoding.

Scaling

• Performance:
  • Parsing: AST-based parsing is slower than JSON/YAML but acceptable for configs.
  • Encoding: Optimized for small-to-medium configs (benchmark for large files).
• Large-Scale Use:
  • Caching: Cache parsed TOML configs in Laravel’s config cache.
  • Streaming: For huge TOML files, consider chunked parsing (not natively supported; may need custom logic).

Failure Modes

Ramp-Up

• Onboarding:
  • Documentation: Add Laravel-specific examples to the package’s README.md.
  • Scaffolding: Provide a starter TomlServiceProvider for new projects.
• Training:
  • TOML Syntax: Train devs on TOML’s strictness (e.g., no trailing commas).
  • Tooling: Show how to use php artisan toml:validate for config checks.
• Adoption Barriers:
  • Resistance to Change: Highlight TOML’s clarity vs. JSON/YAML’s ambiguity.
  • Legacy Code: Provide migration scripts for existing configs.