Laravel Ab Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ben182/laravel-ab
   

   Publish the config file:

   php artisan vendor:publish --provider="Ben182\LaravelAB\LaravelABServiceProvider" --tag="config"
   

2. Publish Migrations:

   php artisan vendor:publish --provider="Ben182\LaravelAB\LaravelABServiceProvider" --tag="migrations"
   

   Run migrations:

   php artisan migrate
   

3. First Use Case: Define an experiment in config/laravel-ab.php:

   'experiments' => [
       'homepage_button_color' => [
           'variants' => [
               'red' => ['weight' => 50],
               'blue' => ['weight' => 50],
           ],
       ],
   ],
   

   Use the experiment in a Blade view:

   @php
       $variant = \Ben182\LaravelAB\Experiment::get('homepage_button_color');
   @endphp
   <button style="background-color: {{ $variant }};">Click Me</button>
   

Implementation Patterns

Core Workflows

1. Experiment Definition:

   • Define experiments in config/laravel-ab.php with variants and weights.
   • Use php artisan laravel-ab:create to scaffold new experiments via CLI.

2. Variant Assignment:

   • In Controllers:

     $variant = \Ben182\LaravelAB\Experiment::get('experiment_key');
     

   • In Blade:

     @laravelAB('experiment_key', 'default_variant')
     

   • Dynamic Assignment:

     $variant = \Ben182\LaravelAB\Experiment::get('experiment_key', request()->ip());
     

3. Tracking Conversions:

   • Log conversions for analysis:

     \Ben182\LaravelAB\Experiment::logConversion('experiment_key', $variant, 'user_id');
     

4. Middleware Integration:

   • Assign variants early in the request cycle:

     public function handle($request, Closure $next) {
         $request->merge(['ab_variant' => \Ben182\LaravelAB\Experiment::get('experiment_key')]);
         return $next($request);
     }
     

5. Dynamic Experiment Loading:

   • Load experiments from a database or external API:

     \Ben182\LaravelAB\Experiment::setExperiments($experimentsFromDB);
     

Integration Tips

• Cache Experiments: Cache experiment definitions in AppServiceProvider for performance:

  Cache::remember('laravel_ab_experiments', now()->addHours(1), function () {
      return \Ben182\LaravelAB\Experiment::getExperiments();
  });
  

• Segmentation: Use middleware to assign variants based on user segments (e.g., isPremiumUser):

  $variant = \Ben182\LaravelAB\Experiment::get('experiment_key', $user->id, ['is_premium' => true]);
  

• API Responses: Include variant info in API responses:

  return response()->json([
      'data' => $data,
      'ab_variant' => \Ben182\LaravelAB\Experiment::get('experiment_key'),
  ]);
  

Gotchas and Tips

Pitfalls

1. Weight Mismatch:

   • Ensure weights in config/laravel-ab.php sum to 100 (or use percentages). Otherwise, variants may not distribute as expected.
   • Fix: Validate weights in a custom validator or use the laravel-ab:validate CLI command.

2. Overwriting Variants:

   • Manually overriding variants (e.g., via ?variant=red in URLs) can skew results. Use middleware to enforce consistency:

     if ($request->has('variant')) {
         \Ben182\LaravelAB\Experiment::forceVariant($request->variant);
     }
     

3. Database Bloat:

   • The ab_experiments and ab_conversions tables grow with usage. Archive old data periodically:

     DB::table('ab_conversions')->where('created_at', '<', now()->subMonths(6))->delete();
     

4. Race Conditions:

   • Concurrent requests may assign the same variant to multiple users if not handled atomically. Use transactions for critical assignments:

     DB::transaction(function () {
         $variant = \Ben182\LaravelAB\Experiment::get('experiment_key', $userId);
     });
     

Debugging

1. Variant Assignment:

   • Log variant assignments for debugging:

     \Log::debug('Assigned variant', ['experiment' => 'key', 'variant' => $variant, 'user_id' => $userId]);
     

2. CLI Tools:

   • Use php artisan laravel-ab:list to inspect active experiments.
   • Use php artisan laravel-ab:stats to view conversion stats.

3. Testing:

   • Mock experiments in tests:

     \Ben182\LaravelAB\Experiment::setExperiments(['test_exp' => ['variants' => ['A' => 100]]]);
     $this->assertEquals('A', \Ben182\LaravelAB\Experiment::get('test_exp'));
     

Extension Points

1. Custom Storage:

   • Override the default Eloquent models (Experiment, Conversion) to use Redis or another storage backend.

2. Event Listeners:

   • Extend functionality by listening to ab.variant.assigned or ab.conversion.logged events:

     Event::listen('ab.variant.assigned', function ($experiment, $variant, $userId) {
         // Send analytics event
     });
     

3. Dynamic Weights:

   • Implement a WeightResolver interface to fetch weights dynamically (e.g., from an API):

     \Ben182\LaravelAB\Experiment::setWeightResolver(new ApiWeightResolver());
     

4. Custom Variant Logic:

   • Extend the VariantResolver class to add logic like time-based or geo-based variant selection:

     class CustomVariantResolver extends VariantResolver {
         public function resolve($experiment, $context = []) {
             if (now()->dayOfWeek === Carbon::SUNDAY) {
                 return 'weekend_special';
             }
             return parent::resolve($experiment, $context);
         }
     }