Wildberries Products Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require baks-dev/wildberries-products
   

2. Publish assets and configure:

   php artisan baks:assets:install
   

3. Run migrations:

   php artisan doctrine:migrations:migrate
   

4. Test basic functionality:

   php artisan --group=wildberries-orders
   

First Use Case: Syncing a Single Product

use BaksDev\WildberriesProducts\Facades\Wildberries;

// Fetch a product by Wildberries' internal ID
$product = Wildberries::product()->find(123456789);

// Sync to your database
$syncResult = $product->sync();

Where to Look First

• Configuration: config/wildberries.php (auto-published by baks:assets:install).
• Console Commands: app/Console/Commands/Wildberries* for bulk operations.
• Models: app/Models/WildberriesProduct.php (core entity).
• Tests: tests/Feature/Wildberries* for integration examples.

Implementation Patterns

Core Workflow: Product Sync

1. Fetch from Wildberries:

   $products = Wildberries::product()->search(['query' => 'smartphone']);
   

2. Process and Store:

   foreach ($products as $wbProduct) {
       $wbProduct->sync(); // Maps to your DB schema
   }
   

3. Handle Events (if using Laravel Events):

   event(new ProductSynced($wbProduct));
   

Integration with Existing Systems

• Inventory Management:

  // Trigger after sync
  event(new InventoryUpdated($wbProduct->sku, $wbProduct->stock));
  

• Price Monitoring:

  $historicalPrices = Wildberries::price()->history($wbProduct->id);
  

• Webhooks (if Wildberries supports them):

  // Listen for Wildberries API webhook events
  Route::post('/wildberries/webhook', [WildberriesWebhookHandler::class, 'handle']);
  

Batch Processing

Use Laravel Queues for large syncs:

// Dispatch a job to sync all products
SyncWildberriesProducts::dispatch();

// In the job:
public function handle() {
    $products = Wildberries::product()->all();
    foreach ($products as $product) {
        $product->sync();
    }
}

Custom Attribute Mapping

Extend the base model to handle Wildberries-specific fields:

use BaksDev\WildberriesProducts\Models\WildberriesProduct as BaseProduct;

class ExtendedWildberriesProduct extends BaseProduct
{
    protected $casts = [
        'wildberries_seller_id' => 'integer',
        'wildberries_category_id' => 'integer',
    ];

    public function getCustomAttribute($key) {
        return $this->attributes["wb_{$key}"] ?? null;
    }
}

Gotchas and Tips

Pitfalls

1. Schema Conflicts:

   • Wildberries uses article for SKUs, but your system might use sku. Override the getSkuAttribute() method in the model:

     public function getSkuAttribute() {
         return $this->article ?? $this->wb_sku;
     }
     

   • Fix: Run php artisan doctrine:migrations:diff before migrating to preview changes.

2. API Rate Limits:

   • Wildberries throttles requests. Use Laravel Queues with delays:

     SyncWildberriesProducts::dispatch()->delay(now()->addMinutes(1));
     

   • Tip: Cache responses for 5 minutes to avoid redundant calls.

3. Localization Issues:

   • Wildberries uses Russian-specific fields (e.g., nm_gtin for GTIN). Ensure your DB supports UTF-8 and collations like utf8mb4_unicode_ci.

4. Console Command Dependencies:

   • Commands like baks:assets:install may fail if the public/ directory lacks permissions. Run:

     chmod -R 755 storage bootstrap/cache public
     

Debugging Tips

• Enable Debug Mode:

  Wildberries::setDebug(true); // Logs API requests/responses
  

• Check Raw API Responses:

  $response = Wildberries::client()->get('/products/123456789');
  dd($response->getBody());
  

• Test with Sandbox: Use Wildberries’ API sandbox to mock responses during development.

Configuration Quirks

1. API Key Management:

   • Store keys in .env:

     WILDBERRIES_API_KEY=your_key_here
     WILDBERRIES_API_SECRET=your_secret
     

   • Security: Use Laravel’s Vault or AWS Secrets Manager for production.

2. Timeouts:

   • Increase default timeout in config/wildberries.php:

     'timeout' => 30, // seconds
     

3. Fallback for Missing Fields:

   • Wildberries may omit optional fields. Handle them in the model:

     public function getPriceAttribute() {
         return $this->price ?? 0;
     }
     

Extension Points

1. Custom Sync Logic:

   • Override the sync() method in your model:

     public function sync() {
         $this->updateFromWildberries();
         $this->triggerCustomLogic();
         return $this;
     }
     

2. Add New Endpoints:

   • Extend the Wildberries facade:

     // app/Providers/WildberriesServiceProvider.php
     public function register() {
         $this->app->extend('wildberries', function ($app) {
             return new ExtendedWildberriesManager($app['wildberries.client']);
         });
     }
     

3. Webhook Support:

   • Implement a listener for Wildberries webhooks:

     use BaksDev\WildberriesProducts\Events\WebhookReceived;
     
     event(new WebhookReceived($payload));
     

Performance Optimizations

• Bulk Syncs:

  $products = Wildberries::product()->batch(100)->fetch();
  

• Database Indexes: Add indexes for frequently queried fields (e.g., wb_article, category_id):

  Schema::table('wildberries_products', function (Blueprint $table) {
      $table->index('wb_article');
  });
  

Testing Strategies

• Unit Tests: Mock the API client:

  $client = Mockery::mock(WildberriesClient::class);
  $client->shouldReceive('get')->andReturn(new Response(200, [], json_encode(['id' => 123])));
  

• Integration Tests: Use the provided test group:

  php artisan test --group=wildberries-orders
  

• Contract Tests: Verify the package adheres to your expected schema:

  $this->assertDatabaseHas('wildberries_products', [
      'wb_article' => '123456789',
      'name' => 'Test Product',
  ]);