Promotoolsbundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require xlabs/promotoolsbundle
   

   Publish the configuration (if needed):

   php artisan vendor:publish --provider="Xlabs\PromotoolsBundle\PromotoolsServiceProvider"
   

2. Service Provider & Facade Ensure the service provider is registered in config/app.php under providers:

   Xlabs\PromotoolsBundle\PromotoolsServiceProvider::class,
   

   Use the facade for quick access:

   use Xlabs\PromotoolsBundle\Facades\Promotools;
   

3. First Use Case: Promotional Logic Trigger a promotional check in a controller or service:

   $isEligible = Promotools::checkPromotion('discount_10_percent');
   if ($isEligible) {
       $discount = Promotools::applyDiscount(100, 'discount_10_percent');
       // Apply discount logic...
   }
   

4. Configuration Review config/promotools.php for default settings (e.g., promotion rules, caching).

Implementation Patterns

Core Workflows

1. Promotion Rules Engine

   • Define promotions in config/promotools.php or via migrations:

     'promotions' => [
         'discount_10_percent' => [
             'conditions' => ['min_cart_value' => 50],
             'discount' => 10,
             'type' => 'percentage',
         ],
     ],
     

   • Dynamically validate eligibility:

     $cartValue = 75;
     $promoCode = 'discount_10_percent';
     if (Promotools::isEligible($cartValue, $promoCode)) {
         $finalPrice = Promotools::calculateDiscountedPrice($cartValue, $promoCode);
     }
     

2. Integration with Cart/Checkout

   • Hook into CartUpdated events to auto-check promotions:

     public function handle(CartUpdated $event)
     {
         $promo = Promotools::getBestMatchingPromotion($event->cart->total);
         $event->cart->promotion = $promo;
     }
     

   • Store promotion state in the session or cart object.

3. API-Driven Promotions

   • Fetch promotions dynamically from an external service:

     $remotePromos = http_get('api/promotions');
     Promotools::syncPromotions($remotePromos);
     

4. Caching Strategies

   • Cache promotion rules to avoid repeated DB checks:

     Promotools::setCacheTTL(3600); // Cache for 1 hour
     

Advanced Patterns

• Composite Promotions Combine multiple promotions (e.g., "Buy X, Get Y + 10% Off"):

  Promotools::combinePromotions(['buy_x_get_y', 'discount_10_percent']);
  

• User-Specific Promotions Extend the Promotion model to include user segments:

  Promotools::filterPromotionsByUser($user);
  

• A/B Testing Use the bundle’s hooks to log promotion exposure:

  Promotools::trackPromotionView('discount_10_percent', $user);
  

Gotchas and Tips

Pitfalls

1. Configuration Overrides

   • Ensure config/promotools.php is not accidentally overwritten during updates. Use config_cache or environment variables for critical values.

2. Caching Quirks

   • Clear the cache after syncing promotions:

     php artisan cache:clear
     

   • Avoid caching user-specific promotions (e.g., "first-time user" discounts).

3. Race Conditions

   • Promotions tied to inventory (e.g., "limited stock") may cause race conditions. Use database transactions or optimistic locking.

4. Facade vs. Service Container

   • Prefer dependency injection over the facade in long-running processes (e.g., queues) to avoid singleton issues:

     public function __construct(private Promotools $promotools) {}
     

Debugging Tips

• Log Promotion Checks Enable debug mode in config/promotools.php:

  'debug' => env('APP_DEBUG', false),
  

  Logs will appear in storage/logs/laravel.log.

• Validate Promotion Rules Use the Promotools::validateRules() method to test configurations:

  $errors = Promotools::validateRules(['min_cart_value' => 'invalid']);
  

• Database Migrations If using migrations for promotions, ensure they’re idempotent:

  Schema::table('promotions', function (Blueprint $table) {
      $table->json('conditions')->nullable()->default('{}');
  });
  

Extension Points

1. Custom Conditions Extend the Xlabs\PromotoolsBundle\Contracts\PromotionCondition interface:

   class UserTierCondition implements PromotionCondition {
       public function isSatisfied($value, $promotion): bool {
           return auth()->user()->tier === $promotion['required_tier'];
       }
   }
   

2. Event Hooks Listen for promotion-related events:

   Promotools::on('promotion.applied', function ($promo, $user) {
       // Send notification, update analytics, etc.
   });
   

3. Testing Mock the Promotools facade in tests:

   Promotools::shouldReceive('isEligible')->andReturn(true);