Avito Orders Laravel Package

Getting Started

Minimal Steps to First Use

1. Install the Package

   composer require baks-dev/avito-orders
   

2. Set Up Required Profiles, Payments, and Deliveries Choose either FBS (Fulfillment by Avito) or DBS (Delivery by Avito) and run the corresponding commands:

   # For FBS (Warehouse Delivery)
   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
   

3. Verify Installation Check the database for new tables related to Avito profiles, payments, and deliveries. Run the provided PHPUnit tests to ensure basic functionality:

   php artisan test --group=avito-orders
   

4. First Integration Use Case Create a Laravel controller to handle incoming Avito orders. Example:

   use BaksDev\AvitoOrders\Facades\AvitoOrder;
   
   public function handleAvitoOrder(Request $request) {
       $orderData = $request->all();
       $avitoOrder = AvitoOrder::createFromAvito($orderData);
       return response()->json(['status' => 'Order processed']);
   }
   

Implementation Patterns

Usage Patterns

1. Order Processing Workflow

   • Use the AvitoOrder facade to create, update, and retrieve orders:

     // Create an order from Avito data
     $order = AvitoOrder::createFromAvito($avitoOrderData);
     
     // Update order status
     $order->updateStatus('shipped');
     
     // Retrieve an order
     $order = AvitoOrder::find($orderId);
     

2. Profile Management

   • Assign Avito-specific profiles to users:

     use BaksDev\AvitoOrders\Models\AvitoProfile;
     
     $user->profile()->attach(AvitoProfile::whereType('avito-fbs')->first());
     

3. Payment Handling

   • Process payments via Avito’s payment system:

     use BaksDev\AvitoOrders\Facades\AvitoPayment;
     
     $payment = AvitoPayment::process($orderId, $amount);
     

4. Delivery Management

   • Manage delivery methods and statuses:

     use BaksDev\AvitoOrders\Facades\AvitoDelivery;
     
     $delivery = AvitoDelivery::createForOrder($orderId, 'avito-fbs');
     $delivery->updateStatus('delivered');
     

Workflows

1. FBS (Fulfillment by Avito) Workflow

   • Order Creation: Avito sends order data → Laravel processes via AvitoOrder::createFromAvito().
   • Warehouse Sync: Use AvitoDelivery::syncToWarehouse($orderId) to update Avito’s warehouse system.
   • Status Updates: Listen for Avito webhooks or poll Avito’s API to update order statuses in Laravel.

2. DBS (Delivery by Avito) Workflow

   • Order Creation: Similar to FBS, but delivery is handled directly to the customer.
   • Shipping Integration: Use AvitoDelivery::generateShippingLabel($orderId) to create shipping labels via Avito’s API.
   • Tracking: Update tracking info in Laravel and sync with Avito:

     $delivery->updateTrackingInfo(['tracking_number' => '1Z999AA10123456788']);
     

Integration Tips

1. Laravel-Symfony Bridge

   • Register Symfony services in Laravel’s service container:

     // config/app.php
     'providers' => [
         BaksDev\AvitoOrders\AvitoOrdersServiceProvider::class,
     ],
     

2. Event Listeners

   • Extend Avito’s events with Laravel listeners:

     // Example: Listen for order created events
     public function handleOrderCreated($event) {
         // Custom logic (e.g., send notification)
         Notification::send($event->order->user, new OrderCreated($event->order));
     }
     

3. Queue Jobs

   • Offload long-running tasks (e.g., delivery updates) to Laravel queues:

     use BaksDev\AvitoOrders\Jobs\UpdateAvitoDeliveryStatus;
     
     UpdateAvitoDeliveryStatus::dispatch($delivery)->onQueue('avito');
     

4. API Webhooks

   • Set up a Laravel route to handle Avito webhooks:

     Route::post('/avito/webhook', [AvitoWebhookController::class, 'handle']);
     

Gotchas and Tips

Pitfalls

1. Symfony Dependency Conflicts

   • The package relies on Symfony components (e.g., Console, HttpKernel). Ensure your Laravel project can handle these dependencies without conflicts.
   • Fix: Use spatie/laravel-symfony or manually bind Symfony services to Laravel’s container.

2. Database Schema Conflicts

   • Avito-specific tables (e.g., avito_orders, avito_deliveries) may conflict with existing Laravel migrations.
   • Fix: Review and merge migrations carefully or use a separate database schema for Avito.

3. Artisan Command Namespace Collisions

   • Symfony commands may conflict with Laravel’s Artisan commands.
   • Fix: Prefix Avito commands or namespace them properly in Laravel’s App\Console\Kernel.

4. PHP Version Mismatch

   • The package requires PHP 8.4+, which may not align with your Laravel version.
   • Fix: Upgrade to Laravel 11+ (PHP 8.3+) or 12+ (PHP 8.4+).

5. Undocumented Assumptions

   • The package assumes integration with baks-dev/core, which may introduce hidden dependencies.
   • Fix: Audit baks-dev/core dependencies and ensure compatibility with Laravel.

Debugging Tips

1. Enable Debug Logging

   • Configure Monolog to log Avito-related events:

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

2. Symfony Debug Dump

   • Use Symfony’s dump() function for debugging:

     use Symfony\Component\VarDumper\VarDumper;
     
     VarDumper::dump($avitoOrderData);
     

3. Test in Isolation

   • Test Avito-specific functionality in a separate Laravel environment before merging with production.

Configuration Quirks

1. Avito API Credentials

   • Ensure API credentials are stored securely (e.g., Laravel’s .env):

     AVITO_API_KEY=your_api_key
     AVITO_API_SECRET=your_api_secret
     

2. Delivery Method Configuration

   • Configure delivery methods in Laravel’s config:

     'avito' => [
         'delivery' => [
             'fbs' => [
                 'enabled' => true,
                 'warehouse_id' => 'your_warehouse_id',
             ],
             'dbs' => [
                 'enabled' => true,
                 'carrier_id' => 'your_carrier_id',
             ],
         ],
     ],
     

3. Event Dispatching

   • Avito events may not trigger Laravel’s default listeners. Manually bind them:

     AvitoOrder::created(function ($order) {
         // Custom logic
     });
     

Extension Points

1. Custom Order Validation

   • Extend Avito order validation logic:

     use BaksDev\AvitoOrders\Rules\AvitoOrderValidation;
     
     $validator = Validator::make($data, [
         'item_id' => ['required', new AvitoOrderValidation],
     ]);
     

2. Webhook Handlers

   • Extend the default webhook handler to support custom logic:

     public function handleWebhook(Request $request) {
         $payload = $request->json()->all();
         if ($payload['event'] === 'order_updated') {
             // Custom logic for order updates
         }
         return response()->json(['status' => 'success']);
     }
     

3. Delivery Status Transitions

   • Customize delivery status transitions:

     use BaksDev\AvitoOrders\Contracts\DeliveryStatus;
     
     class CustomDeliveryStatus implements DeliveryStatus {
         public function getStatuses(): array {
             return ['pending', 'shipped', 'delivered', 'cancelled'];
         }
     }
     

4. Payment Gateway Integration

   • Integrate with third-party payment gateways:

     use BaksDev\AvitoOrders\Contracts\PaymentGateway;
     
     class StripePaymentGateway implements PaymentGateway {
         public function processPayment