Wildberries Package Laravel Package

Getting Started

Minimal Steps to First Use

1. Install the Package

   composer require baks-dev/wildberries-package
   

2. Set Up Configuration & Assets Run the CLI command to install default configurations and assets:

   php artisan baks:assets:install
   

   This generates:

   • Configuration files in config/wildberries.php
   • Asset files (Blade templates, JS/CSS) in resources/views/wildberries/ and public/wildberries/
   • Database migrations (if applicable)

3. Publish Configuration (Optional) If you need to customize the package’s behavior:

   php artisan vendor:publish --tag=wildberries-config
   

4. Run Database Migrations Check for new migrations and apply them:

   php artisan doctrine:migrations:diff
   php artisan doctrine:migrations:migrate
   

5. First Use Case: Packaging an Order Use the package’s service class to package an order:

   use BaksDev\WildberriesPackage\Facades\WildberriesPackage;
   
   $order = app('App\Models\Order'); // Your order model
   $packaging = WildberriesPackage::package($order);
   
   // Generate shipment label
   $label = $packaging->generateLabel();
   

Implementation Patterns

Core Workflows

1. Order Packaging Workflow

• Trigger: When an order is placed or marked as "ready to ship" in your system.
• Steps:
  1. Fetch the order data (ensure it includes required fields like customer_name, items, shipping_address).
  2. Use the package’s facade or service container to package the order:

     $packaging = WildberriesPackage::package($order);
     

  3. Generate the shipment label and barcode:

     $label = $packaging->generateLabel();
     $barcode = $packaging->generateBarcode();
     

  4. Attach the label to the order or shipment model:

     $order->shipment_label = $label->getData();
     $order->save();
     

  5. Send the shipment data to Wildberries API (if integrated):

     $packaging->sendToWildberries();
     

2. Integration with Wildberries API

• Use the package’s API client to interact with Wildberries:

  use BaksDev\WildberriesPackage\Services\WildberriesApi;
  
  $api = app(WildberriesApi::class);
  $response = $api->createShipment($shipmentData);
  

• Handle API responses and errors gracefully:

  try {
      $response = $api->createShipment($shipmentData);
  } catch (\BaksDev\WildberriesPackage\Exceptions\ApiException $e) {
      // Log error and retry or notify admin
      \Log::error('Wildberries API Error: ' . $e->getMessage());
  }
  

3. Event-Driven Extensions

• Listen to package events to extend functionality:

  use BaksDev\WildberriesPackage\Events\OrderPackaged;
  
  OrderPackaged::listen(function (OrderPackaged $event) {
      // Custom logic after order is packaged
      \Log::info('Order packaged: ' . $event->order->id);
  });
  

• Register listeners in EventServiceProvider:

  protected $listen = [
      OrderPackaged::class => [
          'App\Listeners\NotifyWarehouse',
      ],
  ];
  

4. CLI Automation

• Use the package’s CLI commands for bulk operations:

  # Package all orders ready for shipment
  php artisan wildberries:package-ready-orders
  
  # Generate labels for a specific order
  php artisan wildberries:generate-label 123
  

Integration Tips

Database Integration

• The package includes Doctrine migrations for order/shipment tracking. Ensure your Order and Shipment models extend or use the package’s entities if provided.
• Customize migrations by publishing them:

  php artisan vendor:publish --tag=wildberries-migrations
  

Configuration Customization

• Override default settings in config/wildberries.php:

  'api' => [
      'endpoint' => env('WILDBERRIES_API_ENDPOINT', 'https://api.wildberries.ru'),
      'token' => env('WILDBERRIES_API_TOKEN'),
  ],
  'packaging' => [
      'label_template' => 'wildberries::label.template',
      'barcode_format' => 'CODE128',
  ],
  

Testing

• Run package-specific tests:

  php artisan test --group=wildberries-package
  

• Mock Wildberries API responses in tests:

  use BaksDev\WildberriesPackage\Services\WildberriesApi;
  
  $api = Mockery::mock(WildberriesApi::class);
  $api->shouldReceive('createShipment')
      ->once()
      ->andReturn(['success' => true]);
  
  $this->app->instance(WildberriesApi::class, $api);
  

Extending Functionality

• Create custom packaging templates by extending the package’s base template:

  namespace App\Wildberries;
  
  use BaksDev\WildberriesPackage\Contracts\LabelTemplate;
  
  class CustomLabelTemplate implements LabelTemplate
  {
      public function render(array $data): string
      {
          // Custom logic
          return 'Custom label content';
      }
  }
  

• Bind your template in a service provider:

  $this->app->bind(
      \BaksDev\WildberriesPackage\Contracts\LabelTemplate::class,
      App\Wildberries\CustomLabelTemplate::class
  );
  

Gotchas and Tips

Pitfalls

1. PHP Version Requirements

   • The package strictly requires PHP 8.4+. Ensure your server and CI/CD pipelines support this version.
   • Gotcha: Attempting to use it on PHP 8.3 or lower will fail with undefined class/method errors.

2. Database Schema Conflicts

   • If you already have Order or Shipment models, the package’s migrations might conflict.
   • Solution: Publish and customize migrations:

     php artisan vendor:publish --tag=wildberries-migrations
     

     Then merge changes manually.

3. Wildberries API Rate Limits

   • The package handles retries for API failures, but excessive calls may still trigger rate limits.
   • Tip: Configure retry logic in config/wildberries.php:

     'api' => [
         'retry_attempts' => 3,
         'retry_delay' => 1000, // ms
     ],
     

4. Asset Overwrites

   • Running baks:assets:install will overwrite existing files in resources/views/wildberries/ and public/wildberries/.
   • Tip: Back up your files before running the command or customize them post-installation.

5. Event Listener Conflicts

   • If you have existing listeners for OrderPackaged or similar events, the package’s events might conflict.
   • Solution: Use unique event names or namespace your listeners.

6. Barcode Generation Dependencies

   • The package may rely on external libraries (e.g., milbo/barcode) for barcode generation.
   • Gotcha: Ensure these dependencies are installed and compatible with your PHP version.

Debugging Tips

1. Enable Debug Mode Set debug to true in config/wildberries.php to get verbose logs:

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

2. Log API Responses Enable logging for API interactions:

   'api' => [
       'log_responses' => true,
   ],
   

   Check logs in storage/logs/wildberries.log.

3. Validate Order Data Ensure your order data matches the package’s expected structure:

   $validator = \Validator::make($order->toArray(), [
       'customer_name' => 'required|string',
       'items' => 'required|array',
       'shipping_address' => 'required|array',
   ]);
   

4. Check for Deprecated Methods If upgrading from an older version, scan for @deprecated tags in the package’s code and update your usage.

Extension Points

1. Custom Packaging Logic Extend the PackagingService to add custom rules:

   namespace App\Services;
   
   use BaksDev\WildberriesPackage\Services\PackagingService as BasePackagingService;
   
   class CustomPackagingService extends BasePackagingService
   {
       public function getCustomPackagingRules()
       {
           return [
               'rule1' => function ($item) {
                   return $item['weight'] > 1000; // Custom rule
               },
           ];