Fractor Yaml Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require a9f/fractor-yaml --dev
   

   Ensure it’s listed under require-dev in composer.json.

2. Register the Service Provider Add to config/app.php under providers:

   AndreasWolf\FractorYaml\FractorYamlServiceProvider::class,
   

3. First Use Case: Basic YAML Parsing Use the YamlFileProcessor to read and analyze a YAML file:

   use AndreasWolf\FractorYaml\Processor\YamlFileProcessor;
   
   $processor = app(YamlFileProcessor::class);
   $filePath = storage_path('config/example.yaml');
   $result = $processor->process($filePath);
   
   // $result contains parsed YAML data and metadata
   

4. Define a Custom Rule Create a rule implementing a9f\FractorYaml\Contract\YamlFractorRule:

   use a9f\FractorYaml\Contract\YamlFractorRule;
   
   class ExampleRule implements YamlFractorRule {
       public function check(array $data, string $filePath): bool {
           return isset($data['required_key']);
       }
   }
   

   Tag it in a service provider:

   $this->app->tag([ExampleRule::class], 'fractor.yaml_rule');
   

Implementation Patterns

Workflows

1. Rule-Based Validation Use the processor to validate YAML files against custom rules:

   $processor = app(YamlFileProcessor::class);
   $violations = $processor->validate($filePath, [ExampleRule::class]);
   

2. Batch Processing Process multiple YAML files in a directory:

   $files = Storage::files('config/yaml');
   foreach ($files as $file) {
       $processor->process($file);
   }
   

3. Integration with Fractor Chain with other Fractor processors (e.g., PhpFileProcessor) for multi-file analysis:

   $fractor = app(\a9f\Fractor\Fractor::class);
   $fractor->addProcessor($processor);
   $fractor->run();
   

Integration Tips

• Leverage Laravel’s Config Store YAML configs (e.g., services.yaml) and validate them during deployment:

  $processor->process(config_path('services.yaml'));
  

• Custom Rule Reusability Group rules by concern (e.g., ValidationRules, SchemaRules) and tag them collectively:

  $this->app->tag([
      ValidationRules::class,
      SchemaRules::class,
  ], 'fractor.yaml_rule');
  

• Event-Driven Extensions Listen for fractor.processed events to react to YAML parsing results:

  Event::listen('fractor.processed', function ($event) {
      if ($event->getProcessor() instanceof YamlFileProcessor) {
          // Handle YAML-specific logic
      }
  });
  

Gotchas and Tips

Pitfalls

1. YAML Parsing Quirks

   • Trailing Comments: YAML comments (e.g., # comment) may not parse as expected. Use Symfony/Yaml directly if needed:

     $yaml = Yaml::parseFile($filePath);
     

   • Anchors/References: Complex YAML features (e.g., &anchor, *ref) may break simple parsers. Pre-process with spatie/flysystem-yaml if required.

2. Rule Injection

   • Tagging Errors: Forgetting to tag rules with 'fractor.yaml_rule' will silently exclude them from processing.
   • Dependency Hell: Rules may depend on other services. Use constructor injection:

     public function __construct(private SomeService $service) {}
     

3. Performance

   • Large Files: Parsing massive YAML files (e.g., 10MB+) may hit memory limits. Stream processing with yamlparse/yaml is an alternative.

Debugging

• Enable Fractor Logging Add to config/logging.php:

  'channels' => [
      'fractor' => [
          'driver' => 'single',
          'path' => storage_path('logs/fractor.log'),
          'level' => 'debug',
      ],
  ],
  

  Then configure Fractor to use this channel.

• Dump Parsed Data Inspect raw YAML data for debugging:

  $data = $processor->getParsedData($filePath);
  dd($data);
  

Extension Points

1. Custom Processors Extend YamlFileProcessor to add pre/post-processing:

   class CustomYamlProcessor extends YamlFileProcessor {
       protected function preProcess(array $data): array {
           return $this->sanitizeData($data);
       }
   }
   

2. Rule Composition Combine rules into composite rules for complex logic:

   class CompositeRule implements YamlFractorRule {
       public function __construct(private array $rules) {}
   
       public function check(array $data, string $filePath): bool {
           return array_reduce($this->rules, fn($carry, $rule) =>
               $carry && $rule->check($data, $filePath), true);
       }
   }
   

3. File System Abstraction Use Laravel’s Filesystem contracts to support cloud storage (e.g., S3):

   $processor = new YamlFileProcessor(app(\Illuminate\Contracts\Filesystem\Filesystem::class));