Mustangostang Spyc Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require wp-cli/mustangostang-spyc
   

   Add to composer.json if not using global Composer.

2. First Use Case: Load a YAML file into a PHP array:

   use Spyc;
   
   $data = Spyc::YAMLLoad('path/to/file.yaml');
   

   Or dump an array to YAML:

   $yamlString = Spyc::YAMLDump(['key' => 'value']);
   

3. Where to Look First:

   • README: Basic usage.
   • Source Code: spyc.php for edge cases.
   • Laravel Integration: Use config_path() or storage_path() for file operations.

Implementation Patterns

Workflows

1. Configuration Loading: Load YAML configs in a service provider:

   public function boot()
   {
       $config = Spyc::YAMLLoad(config_path('custom.yaml'));
       config(['custom.settings' => $config]);
   }
   

2. Dynamic YAML Generation: Serialize Laravel collections/models to YAML:

   $users = User::all()->toArray();
   $yaml = Spyc::YAMLDump($users);
   Storage::disk('logs')->put('users.yaml', $yaml);
   

3. CLI Tools: Use in Artisan commands for data export:

   class ExportCommand extends Command
   {
       public function handle()
       {
           $data = Spyc::YAMLLoad('input.yaml');
           $this->info(Spyc::YAMLDump($data, 10)); // Pretty-print
       }
   }
   

4. Validation: Combine with Laravel’s Validator:

   $data = Spyc::YAMLLoad('input.yaml');
   $validator = Validator::make($data, [
       'name' => 'required|string',
       'email' => 'required|email',
   ]);
   

5. Legacy Migration: Convert old YAML configs to PHP arrays for Laravel’s native config:

   $legacyConfig = Spyc::YAMLLoad('legacy/config.yaml');
   config(['legacy' => $legacyConfig]);
   

Gotchas and Tips

Pitfalls

1. YAML 1.0 Only:

   • Fails on YAML 1.1/1.2 features (e.g., anchors, tags). Test with symfony/yaml if unsure.
   • Example failure:

     # This will break:
     defaults: &defaults
       adapter: mysql
       host: localhost
     

2. No Error Handling:

   • Malformed YAML throws Spyc_Exception. Wrap calls:

     try {
         $data = Spyc::YAMLLoad('file.yaml');
     } catch (Spyc_Exception $e) {
         Log::error("YAML parse error: " . $e->getMessage());
     }
     

3. Performance:

   • Slower than symfony/yaml for large files. Benchmark if parsing >1MB YAML.

4. No Laravel Facades:

   • Manual file I/O required (e.g., file_get_contents()). Avoid for sensitive paths.

5. Deprecation Risk:

   • WP-CLI’s fork is unmaintained. Avoid for new projects; prefer symfony/yaml.

Tips

1. Pretty-Printing: Use Spyc::YAMLDump($data, 10) for human-readable output (indent level = 10).

2. String Parsing: Parse YAML strings directly:

   $data = Spyc::YAMLLoadString($yamlString);
   

3. Laravel Service Binding (Optional): Bind to container for DI:

   $this->app->singleton('spyc', function () {
       return new \Spyc();
   });
   

4. Testing: Validate against symfony/yaml for critical data:

   $symfonyData = Symfony\Component\Yaml\Yaml::parseFile('file.yaml');
   $spycData = Spyc::YAMLLoad('file.yaml');
   $this->assertEquals($symfonyData, $spycData);
   

5. Alternatives:

   • Use spatie/laravel-yaml for Laravel-specific features.
   • Switch to symfony/yaml if YAML 1.2 or performance is needed.