Avito Promotion Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require baks-dev/avito-promotion
   

   Ensure your project meets the PHP 8.4+ requirement and has baks-dev/core (≥7.4) installed.

2. Service Provider & Facade Register the package in config/app.php under providers:

   BaksDev\AvitoPromotion\AvitoPromotionServiceProvider::class,
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="BaksDev\AvitoPromotion\AvitoPromotionServiceProvider" --tag="config"
   

   Update your .env with Avito API credentials (see config/avito-promotion.php).

3. First Use Case: Fetching Promotions Use the facade to retrieve promotions for an ad:

   use BaksDev\AvitoPromotion\Facades\AvitoPromotion;
   
   $promotions = AvitoPromotion::getPromotionsForAd($adId);
   

   Verify the response structure in src/Response/PromotionResponse.php.

Implementation Patterns

Core Workflows

1. Promotion Management

   • Create/Update Promotions:

     $promotion = AvitoPromotion::createPromotion([
         'ad_id' => $adId,
         'start_date' => now()->addDays(7),
         'end_date' => now()->addDays(14),
         'budget' => 1000.00,
     ]);
     

   • Pause/Resume:

     AvitoPromotion::pausePromotion($promotionId);
     AvitoPromotion::resumePromotion($promotionId);
     

2. Event-Driven Integration Listen for Avito webhook events (e.g., promotion.status_changed):

   // In EventServiceProvider
   protected $listen = [
       'BaksDev\AvitoPromotion\Events\PromotionStatusChanged' => [
           \App\Listeners\UpdateAdStatus::class,
       ],
   ];
   

3. Bulk Operations Use the BulkPromotionManager for batch updates:

   $manager = app(\BaksDev\AvitoPromotion\Managers\BulkPromotionManager::class);
   $manager->updatePromotions($promotionIds, ['budget' => 1500.00]);
   

Integration Tips

• Laravel Queues: Offload promotion processing to queues:

  dispatch(new \BaksDev\AvitoPromotion\Jobs\ProcessPromotion($promotionData));
  

• Caching: Cache frequent promotion queries:

  $promotions = Cache::remember("avito_promotions_{$adId}", now()->addHours(1), function() use ($adId) {
      return AvitoPromotion::getPromotionsForAd($adId);
  });
  

• API Rate Limiting: Implement middleware to handle Avito API rate limits:

  // app/Http/Middleware/HandleAvitoRateLimit.php
  public function handle($request, Closure $next) {
      if (AvitoPromotion::isRateLimited()) {
          return response()->json(['error' => 'Rate limit exceeded'], 429);
      }
      return $next($request);
  }
  

Gotchas and Tips

Pitfalls

1. API Credentials

   • Issue: Hardcoded credentials in config may leak.
   • Fix: Use Laravel's .env and validate credentials on first run:

     if (!config('avito-promotion.client_id') || !config('avito-promotion.client_secret')) {
         throw new \RuntimeException('Avito API credentials not configured.');
     }
     

2. Timezone Mismatches

   • Issue: Avito expects UTC timestamps; local time may cause errors.
   • Fix: Convert dates explicitly:

     $startDate = now()->setTimezone('UTC')->toDateTimeString();
     

3. Idempotency

   • Issue: Retrying failed promotions may duplicate charges.
   • Fix: Use Avito’s idempotency_key in requests:

     $promotion->setIdempotencyKey(strtolower(md5(uniqid())));
     

Debugging

• Enable Logging Configure the log_channel in config/avito-promotion.php to single or stack for detailed logs:

  'log_channel' => 'avito',
  

  Add a channel in config/logging.php:

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

• Mocking Avito API Use the AvitoPromotionMock for testing:

  $mock = new \BaksDev\AvitoPromotion\Testing\AvitoPromotionMock();
  $mock->shouldReceive('getPromotionsForAd')->andReturn([...]);
  

Extension Points

1. Custom Promotion Rules Extend the PromotionRule interface to add business logic:

   class CustomBudgetRule implements \BaksDev\AvitoPromotion\Contracts\PromotionRule {
       public function validate(array $promotionData): bool {
           return $promotionData['budget'] >= 500.00;
       }
   }
   

   Register in config/avito-promotion.php:

   'rules' => [
       \App\Rules\CustomBudgetRule::class,
   ],
   

2. Webhook Handlers Override default event handlers by binding your listeners to the PromotionStatusChanged event.

3. Response Transformers Customize API responses by extending PromotionResponse:

   class CustomPromotionResponse extends \BaksDev\AvitoPromotion\Response\PromotionResponse {
       public function toArray(): array {
           $array = parent::toArray();
           $array['formatted_budget'] = number_format($array['budget'], 2);
           return $array;
       }
   }
   

   Bind the transformer in the service provider:

   $this->app->bind(
       \BaksDev\AvitoPromotion\Contracts\PromotionResponse::class,
       \App\Response\CustomPromotionResponse::class
   );