Avito Orders Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require baks-dev/avito-orders
   

   Ensure your project uses PHP 8.4+ and Laravel 10/11 (or Symfony/Lumen if leveraging Symfony bridge).

2. Register Required Commands: Choose either FBS (Fulfillment by Avito) or DBS (Delivery by Avito):

   # For FBS (warehouse fulfillment)
   php artisan baks:users-profile-type:avito-fbs
   php artisan baks:payment:avito-fbs
   php artisan baks:delivery:avito-fbs
   
   # For DBS (direct delivery)
   php artisan baks:users-profile-type:avito-dbs
   php artisan baks:payment:avito-dbs
   php artisan baks:delivery:avito-dbs
   

   Note: Commands assume baks-dev/core is installed. If using Laravel, bind Symfony commands to Laravel’s App\Console\Kernel.

3. First Use Case:

   • Sync an Avito Order: Use the package’s event listeners (e.g., AvitoOrderCreated) to trigger Laravel jobs or notifications. Example:

     // In a Laravel service
     event(new \BaksDev\AvitoOrders\Events\AvitoOrderCreated($orderData));
     

   • Test with PHPUnit: Run the provided test group:

     php artisan test --group=avito-orders
     

4. Verify Setup:

   • Check database tables for avito_profile_types, avito_payments, and avito_deliveries.
   • Validate CLI output for command success messages.

Implementation Patterns

Usage Patterns

1. Order Lifecycle Integration

• Listen to Avito Events: Laravel’s event system can subscribe to Avito’s order transitions (e.g., order.paid, delivery.shipped).

  // In EventServiceProvider
  protected $listen = [
      \BaksDev\AvitoOrders\Events\AvitoOrderPaid::class => [
          \App\Listeners\UpdateInventory::class,
      ],
  ];
  

• Dispatch Laravel Jobs: Use Laravel’s queues to process Avito orders asynchronously:

  // Example job for inventory updates
  class UpdateInventory implements ShouldQueue
  {
      use Dispatchable, InteractsWithQueue;
  
      public function handle()
      {
          // Logic to update inventory after Avito order is paid
      }
  }
  

2. Profile and Delivery Workflows

• Dynamic Profile Assignment: Attach Avito profile types to Laravel users/models:

  $user->profile()->attach(\BaksDev\AvitoOrders\Enums\ProfileType::AVITO_FBS);
  

• Delivery Method Selection: Use Laravel’s polymorphic relationships to link deliveries:

  $order->delivery()->associate(new \BaksDev\AvitoOrders\Models\AvitoDelivery(
      $orderId,
      \BaksDev\AvitoOrders\Enums\DeliveryMethod::AVITO_FBS
  ));
  

3. Payment Processing

• Webhook Handling: Avito payments may require webhook validation. Use Laravel’s HasApiTokens for secure endpoints:

  Route::post('/avito/payment/webhook', [AvitoWebhookController::class, 'handle'])
       ->middleware('throttle:60');
  

• Refund Logic: Extend Laravel’s Payment facade or create a custom service:

  class AvitoRefundService
  {
      public function refund(Order $order, float $amount)
      {
          // Use BaksDev's refund logic via Avito API
          $refund = \BaksDev\AvitoOrders\Facades\AvitoPayment::refund($order->avito_id, $amount);
          $order->update(['status' => 'refunded']);
      }
  }
  

4. CLI-Driven Configuration

• Automate Setup: Schedule commands in Laravel’s app/Console/Kernel.php:

  protected function schedule(Schedule $schedule)
  {
      $schedule->command('baks:delivery:avito-fbs')->daily();
  }
  

• Custom Commands: Extend Symfony commands for Laravel-specific logic:

  // app/Console/Commands/ExtendAvitoDelivery.php
  class ExtendAvitoDelivery extends Command
  {
      protected $signature = 'avito:delivery:extend {orderId}';
      public function handle()
      {
          $delivery = \BaksDev\AvitoOrders\Models\AvitoDelivery::find($orderId);
          $delivery->extendDeadline();
      }
  }
  

Workflows

FBS (Fulfillment by Avito) Workflow

1. Order Creation:
   • Avito order → Trigger AvitoOrderCreated event → Laravel creates Order model.
2. Inventory Sync:
   • Listen for AvitoOrderPaid → Dispatch UpdateInventory job.
3. Fulfillment:
   • CLI command baks:delivery:avito-fbs → Avito handles shipping; update Laravel’s Order status via webhook.

DBS (Delivery by Avito) Workflow

1. Order Placement:
   • Avito order → Assign AVITO_DBS profile → Trigger AvitoOrderReceived event.
2. Delivery Coordination:
   • Use Laravel’s DeliveryService to generate tracking:

     $tracking = \BaksDev\AvitoOrders\Facades\AvitoDelivery::generateTracking($order);
     

3. Status Updates:
   • Avito webhook → Update Laravel’s Order status (e.g., shipped, delivered).

Integration Tips

Laravel-Symfony Bridge

• Service Binding: Bind Symfony services to Laravel’s container in AppServiceProvider:

  $this->app->bind(
      \BaksDev\Core\Avito\Client::class,
      fn($app) => new \BaksDev\Core\Avito\Client(config('avito.api_key'))
  );
  

• Command Registration: Register Symfony commands in App\Console\Kernel:

  protected $commands = [
      \BaksDev\AvitoOrders\Command\AvitoFbsCommand::class,
      // Add custom commands here
  ];
  

Database Schema

• Migrations: Use Laravel’s Schema builder to extend Avito tables:

  Schema::table('avito_deliveries', function (Blueprint $table) {
      $table->foreignId('order_id')->constrained()->onDelete('cascade');
  });
  

• Model Relationships: Define Laravel Eloquent relationships:

  class Order extends Model
  {
      public function delivery()
      {
          return $this->hasOne(AvitoDelivery::class);
      }
  }
  

Testing

• PHPUnit: Extend Avito’s test group for Laravel-specific assertions:

  public function testAvitoOrderCreation()
  {
      $this->artisan('baks:users-profile-type:avito-fbs')
           ->expectsOutput('Profile type registered');
  
      $this->assertDatabaseHas('profile_types', [
          'name' => 'avito_fbs',
      ]);
  }
  

• Mocking Avito API: Use Laravel’s Mockery to stub Avito responses:

  $mock = Mockery::mock(\BaksDev\Core\Avito\Client::class);
  $mock->shouldReceive('createOrder')->andReturn($avitoOrder);
  
  $this->app->instance(\BaksDev\Core\Avito\Client::class, $mock);
  

Gotchas and Tips

Pitfalls

1. Symfony Dependency Conflicts:

   • Issue: baks-dev/core may pull in Symfony components (e.g., HttpKernel) that conflict with Laravel.
   • Fix: Use composer why-not to identify conflicts. Isolate Symfony dependencies in a separate service if possible.

2. Database Schema Mismatches:

   • Issue: Avito’s migrations may assume Symfony’s Doctrine ORM, causing Laravel Eloquent errors.
   • Fix: Override migrations or use raw SQL:

     Schema::raw('ALTER TABLE avito_orders ADD COLUMN laravel_order_id INT');
     

3. Event System Collisions:

   • Issue: Laravel’s event system may not recognize Symfony’s event dispatchers.
   • Fix: Create a bridge service:

     class AvitoEventDispatcher
     {
         public function dispatch($event)
         {
             event(new LaravelAvitoEvent($event));
         }
     }
     

4. CLI Command Namespace Conflicts:

   • Issue: Symfony commands may clash with Laravel’s php artisan namespace.
   • Fix: Prefix commands or use