Toml Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer:

   composer require jamesmoss/toml
   

   No additional configuration is required—it’s a standalone parser.

2. First Use Case Parse a TOML string or file:

   use Jamesmoss\Toml\Toml;
   
   // Parse a string
   $tomlString = <<<TOML
   title = "Example"
   owner = { name = "John Doe", organization = "Acme Inc" }
   TOML;
   $parsed = Toml::parse($tomlString);
   // Returns: ['title' => 'Example', 'owner' => ['name' => 'John Doe', 'organization' => 'Acme Inc']]
   
   // Parse a file
   $parsedFile = Toml::parseFile(__DIR__ . '/config.toml');
   

3. Where to Look First

   • Documentation: The package is minimal; refer to the TOML spec for syntax rules.
   • Source: Check Toml.php for edge-case handling (e.g., nested tables, arrays).

Implementation Patterns

Common Workflows

1. Configuration Files Replace PHP arrays or JSON configs with TOML for better readability:

   // config/app.toml
   [database]
   host = "localhost"
   port = 3306
   

   $config = Toml::parseFile(config_path('app.toml'));
   DB::setHost($config['database']['host']);
   

2. User-Generated Data Parse TOML from user uploads (e.g., settings.toml):

   $userToml = $request->file('settings.toml')->getContent();
   $userPrefs = Toml::parse($userToml);
   

3. Integration with Laravel Services Use in Service Providers or Commands to load external configs:

   // app/Providers/AppServiceProvider.php
   public function boot()
   {
       $this->app->singleton('toml-config', function () {
           return Toml::parseFile(storage_path('config/overrides.toml'));
       });
   }
   

Tips for Seamless Integration

• Validation: Combine with Laravel’s Validator to ensure TOML structure matches expectations:

  $rules = [
      'database.host' => 'required|string',
      'database.port' => 'required|integer|between:1,65535',
  ];
  Validator::make($parsedToml, $rules)->validate();
  

• Caching: Cache parsed TOML files if they’re static:

  $cacheKey = 'toml_config_' . md5_file($filePath);
  $config = Cache::remember($cacheKey, now()->addHours(1), function () use ($filePath) {
      return Toml::parseFile($filePath);
  });
  

Gotchas and Tips

Pitfalls

1. Deprecated Package

   • Last updated in 2014; may not handle TOML v1.0 features (e.g., multi-line strings, 2024-01-01 dates).
   • Mitigation: Pre-process TOML strings to simplify syntax or use a modern alternative like spatie/toml.

2. No Error Handling

   • Throws generic exceptions on parse errors. Wrap parsing in a try-catch:

     try {
         $data = Toml::parse($tomlString);
     } catch (\Exception $e) {
         Log::error("Invalid TOML: " . $e->getMessage());
         return response()->json(['error' => 'Invalid config'], 400);
     }
     

3. Array of Tables Limitation

   • Does not natively support TOML’s [table.array] syntax. Workaround:

     [[users]]
     name = "Alice"
     [[users]]
     name = "Bob"
     

     Parse manually or pre-convert to a supported format.

Debugging

• Validate TOML Syntax: Use an online validator (e.g., toml.io) before parsing.
• Log Raw Input: Log the TOML string before parsing to debug:

  Log::debug("Parsing TOML:", ['input' => $tomlString]);
  

Extension Points

• Custom Parsers: Extend Jamesmoss\Toml\Toml for domain-specific TOML (e.g., add schema validation).
• Hybrid Configs: Merge TOML with Laravel’s config system:

  $tomlData = Toml::parseFile(config_path('toml_overrides.toml'));
  config()->set($tomlData);
  

Performance

• Large Files: Avoid parsing massive TOML files in memory. Stream or chunk the file if possible (though this package doesn’t support streaming natively).