Variator Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require coshi/variator
   

2. First Use Case: Generate a simple Cartesian product of values for testing or data seeding:

   use Coshi\Variator\VariationFactory;
   use Coshi\Variator\VariationsTreeBuilder;
   
   $factory = new VariationFactory();
   $builder = new VariationsTreeBuilder($factory);
   
   $config = [
       'status' => ['type' => 'enum', 'values' => ['active', 'inactive']],
       'priority' => ['type' => 'int', 'min' => 1, 'max' => 3],
   ];
   
   $variations = $builder->build($config);
   

Where to Look First

• VariationsTreeBuilder: Core class for building variations.
• VariationFactory: Handles value generation logic.
• README.md: Examples for enum, int, callback, and cross-referencing.

Implementation Patterns

Common Workflows

1. Data Seeding: Generate test data for Laravel factories:

   $builder->build($config); // Returns array of combinations
   foreach ($variations as $data) {
       Model::factory()->create($data);
   }
   

2. Dynamic Test Cases: Use in PHPUnit tests for parameterized test data:

   $variations = $builder->build($config);
   foreach ($variations as $data) {
       $this->assertSomething($data);
   }
   

3. API Response Variations: Simulate different API responses for testing:

   $responses = $builder->build([
       'status' => ['type' => 'enum', 'values' => [200, 404, 500]],
       'data' => ['type' => 'callback', 'callback' => [MockData::class, 'generate']],
   ]);
   

Integration Tips

• Laravel Service Provider: Bind VariationsTreeBuilder to the container for easy access:

  $this->app->bind(VariationsTreeBuilder::class, function ($app) {
      return new VariationsTreeBuilder(new VariationFactory());
  });
  

  Usage:

  $builder = app(VariationsTreeBuilder::class);
  

• Dynamic Configs: Load configs from JSON/YAML files for reusability:

  $config = json_decode(file_get_contents('variations.json'), true);
  $builder->build($config);
  

• Cross-Referencing: Use @key syntax for context-dependent values (e.g., @status):

  'priority' => [
      'type' => 'callback',
      'callback' => [PriorityLogic::class, 'getPriorities'],
      'context_dependent' => true,
  ],
  

Gotchas and Tips

Pitfalls

1. Callback Context:

   • Forgetting context_dependent: true for callbacks with @key references will throw errors.
   • Example:

     'callback' => [Class::class, 'method', ['@status']], // Requires context_dependent
     

2. Type Validation:

   • int/float ranges must have min <= max; otherwise, no values are generated.
   • Empty enum arrays will produce an empty result set.

3. Performance:

   • Cartesian products grow exponentially. For large datasets, consider:
     • Limiting ranges (e.g., min/max).
     • Using callback for dynamic filtering.

4. Class Autoloading:

   • Callbacks referencing classes (e.g., [Class::class, 'method']) require the class to be autoloadable.

Debugging Tips

• Inspect Config: Validate $config structure before building:

  if (empty($config['key']['values'])) {
      throw new \InvalidArgumentException("Missing values for key 'key'");
  }
  

• Log Variations: Debug output for complex configs:

  $variations = $builder->build($config);
  \Log::debug('Generated variations:', ['data' => $variations]);
  

Extension Points

1. Custom Value Types: Extend VariationFactory to support new types (e.g., date, uuid):

   class CustomFactory extends VariationFactory {
       public function generateDate($config) {
           return Carbon::now()->addDays(rand(0, 30))->toDateString();
       }
   }
   

2. Post-Processing: Filter or transform variations after generation:

   $variations = $builder->build($config);
   $filtered = array_filter($variations, fn($v) => $v['status'] === 'active');
   

3. Laravel Collections: Convert results to a Collection for Laravel-specific methods:

   collect($builder->build($config))->each(fn($item) => Model::create($item));
   

Config Quirks

• Callback Syntax: Supports:
  • Static methods: [Class::class, 'method'].
  • Instance methods: [new Class(), 'method'].
  • Anonymous functions: fn() => [1, 2, 3] (requires callback type).
• Default Values: No built-in defaults; explicitly define min/max or values in config.