Avito Support Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require baks-dev/avito-support
   

   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\AvitoSupport\AvitoSupportServiceProvider::class,
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="BaksDev\AvitoSupport\AvitoSupportServiceProvider" --tag="config"
   

   Access via facade:

   use BaksDev\AvitoSupport\Facades\AvitoSupport;
   

3. First Use Case: Sending a Support Message

   AvitoSupport::sendMessage([
       'user_id' => 123,
       'message' => 'Test message from Laravel',
       'priority' => 'high',
   ]);
   

Key Files to Review

• config/avito-support.php: Configuration (API endpoints, defaults).
• src/AvitoSupport.php: Core class methods.
• src/Facades/AvitoSupport.php: Facade for cleaner syntax.

Implementation Patterns

Core Workflows

1. Message Handling

   • Sending Messages:

     AvitoSupport::sendMessage($data); // $data = ['user_id', 'message', 'priority', ...]
     

     Supports optional fields like attachments, metadata, and callback_url.
   • Batch Processing:

     AvitoSupport::sendBatch([$message1, $message2]);
     

2. Webhook Integration

   • Register a route to handle Avito callbacks:

     Route::post('/avito/support/webhook', [AvitoSupportController::class, 'handleWebhook']);
     

   • Validate incoming webhooks using:

     AvitoSupport::validateWebhook($request);
     

3. Event Listeners

   • Listen for AvitoSupportSent events:

     public function handle(AvitoSupportSent $event) {
         // Log, notify, or process the sent message
     }
     

4. Configuration Overrides

   • Override defaults in config/avito-support.php:

     'api_endpoint' => env('AVITO_API_URL', 'https://api.avito.example/support'),
     'default_priority' => 'medium',
     

Integration Tips

• Queue Jobs for Async Processing:

  AvitoSupport::dispatchMessage($data)->onQueue('avito');
  

• Laravel Mixins: Extend the core class via traits or decorators:

  AvitoSupport::extend(function ($support) {
      $support->macro('customMethod', function () { ... });
  });
  

• Testing: Use the avito-support test group:

  php artisan test --group=avito-support
  

Gotchas and Tips

Pitfalls

1. API Rate Limits

   • Monitor AvitoSupport::getRateLimit() to avoid hitting API thresholds.
   • Implement retries with exponential backoff for failed requests:

     AvitoSupport::retry($data, 3, 1000); // Retry 3 times with 1s delay
     

2. Webhook Validation

   • Always validate webhooks to prevent spoofing:

     if (!AvitoSupport::validateWebhook($request)) {
         abort(403, 'Invalid webhook signature');
     }
     

   • Store and verify AVITO_WEBHOOK_SECRET in .env.

3. Deprecated Methods

   • Check release/v7.4.6.md for breaking changes (e.g., renamed methods like send() → sendMessage()).

4. Core Dependency

   • Ensure baks-dev/core (≥7.4) is installed. Conflicts may arise with older versions.

Debugging

• Enable Logging:

  AvitoSupport::setLogLevel(\Monolog\Logger::DEBUG);
  

  Logs appear in storage/logs/avito-support.log.

• Mock API Calls in Tests:

  AvitoSupport::shouldReceive('sendMessage')->andReturn(true);
  

Extension Points

1. Custom Transport Override the HTTP client:

   AvitoSupport::setHttpClient(new CustomHttpClient());
   

2. Message Transformers Extend message formatting:

   AvitoSupport::extendMessageTransformer(function ($message) {
       $message['custom_field'] = 'value';
       return $message;
   });
   

3. Event Customization Bind custom listeners to AvitoSupportSent:

   event(new AvitoSupportSent($data));
   

Configuration Quirks

• Environment Variables: Prefix Avito-related configs with AVITO_ (e.g., AVITO_API_KEY). Example .env:

  AVITO_API_URL=https://api.avito.example/support
  AVITO_WEBHOOK_SECRET=your_secret_here
  

• Fallback Behavior: Disable API calls entirely for testing:

  AvitoSupport::setApiEnabled(false);