Shopware App System Bundle Laravel Package

Getting Started

First Steps

1. Installation Add the bundle via Composer in your Laravel project:

   composer require bitbag/shopware-app-system-bundle
   

   Register the bundle in config/app.php under providers:

   BitBag\ShopwareAppSystemBundle\ShopwareAppSystemBundle::class,
   

2. Configuration Publish the bundle’s config file:

   php artisan vendor:publish --provider="BitBag\ShopwareAppSystemBundle\ShopwareAppSystemBundle" --tag="config"
   

   Update config/shopware-app-system.php with your Shopware 6 API credentials (client ID, secret, base URL).

3. First Use Case: Fetching Shopware Data Use the bundle’s service container to interact with Shopware’s API:

   use BitBag\ShopwareAppSystemBundle\Service\ShopwareService;
   
   class MyController extends Controller
   {
       public function __construct(private ShopwareService $shopwareService) {}
   
       public function getProducts()
       {
           $products = $this->shopwareService->get('/product');
           return response()->json($products);
       }
   }
   

Implementation Patterns

Common Workflows

1. API Integration

   • Fetching Data: Use ShopwareService to retrieve entities (e.g., products, categories, orders):

     $products = $shopwareService->get('/product', ['limit' => 10]);
     

   • Creating/Updating Data: Pass payloads as arrays:

     $newProduct = [
         'name' => 'Test Product',
         'price' => ['gross' => 1000, 'net' => 800],
     ];
     $createdProduct = $shopwareService->post('/product', $newProduct);
     

2. Authentication

   • The bundle auto-handles OAuth2 token refresh via ShopwareService. Configure scopes in config/shopware-app-system.php:

     'scopes' => ['read_products', 'write_products'],
     

3. Event-Driven Sync

   • Subscribe to Shopware webhooks (e.g., order.created) via Laravel’s events system:

     // In a service provider
     Event::listen('shopware.order.created', function ($event) {
         // Sync order to Laravel DB
     });
     

   • Use the bundle’s ShopwareWebhookService to register webhooks:

     $webhook = $shopwareWebhookService->createWebhook(
         url: route('shopware.webhook'),
         events: ['order.created']
     );
     

4. Data Transformation

   • Use Laravel’s Resource classes to shape Shopware responses:

     use Illuminate\Http\Resources\Json\JsonResource;
     
     class ProductResource extends JsonResource
     {
         public function toArray($request)
         {
             return [
                 'id' => $this->id,
                 'name' => $this->name,
                 'price' => $this->price['net'],
             ];
         }
     }
     

Gotchas and Tips

Pitfalls

1. Token Expiry

   • The bundle silently retries failed requests due to expired tokens. Log errors explicitly:

     try {
         $shopwareService->get('/product');
     } catch (\BitBag\ShopwareAppSystemBundle\Exception\ShopwareException $e) {
         Log::error('Shopware API error: ' . $e->getMessage());
     }
     

2. Rate Limiting

   • Shopware’s API enforces rate limits. Implement exponential backoff in custom services:

     use Symfony\Component\HttpClient\RetryableHttpClient;
     
     $client = new RetryableHttpClient(
         $baseClient,
         [
             'max_retries' => 3,
             'delay' => 1000,
         ]
     );
     

3. Data Mismatches

   • Shopware’s API uses snake_case for nested fields (e.g., price.gross), while Laravel often uses camelCase. Normalize responses:

     $normalized = collect($response)->map(function ($item) {
         return (array) json_decode(json_encode($item), true);
     });
     

Debugging Tips

• Enable API Logging: Add to config/shopware-app-system.php:

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

• Inspect Raw Responses: Use ShopwareService::getRawResponse() to debug:

  $response = $shopwareService->get('/product', [], true);
  dd($response->getContent());
  

Extension Points

1. Custom API Clients Extend ShopwareService to add middleware:

   namespace App\Services;
   
   use BitBag\ShopwareAppSystemBundle\Service\ShopwareService;
   
   class CustomShopwareService extends ShopwareService
   {
       public function __construct()
       {
           $this->addMiddleware(function ($request) {
               $request->headers->set('X-Custom-Header', 'value');
           });
       }
   }
   

2. Webhook Handlers Create custom event listeners for Shopware webhooks:

   namespace App\Listeners;
   
   use BitBag\ShopwareAppSystemBundle\Event\ShopwareWebhookEvent;
   
   class HandleOrderCreated
   {
       public function handle(ShopwareWebhookEvent $event)
       {
           if ($event->getEventName() === 'order.created') {
               // Process order
           }
       }
   }
   

3. GraphQL Support The bundle primarily uses REST. For GraphQL, integrate webonyx/graphql-php and wrap calls:

   $query = '
       query {
           products(first: 10) {
               edges {
                   node {
                       name
                   }
               }
           }
       }
   ';
   $client = new \Webonyx\GraphQL\Client();
   $client->setUrl('https://your-shopware-store.com/api/graphql');
   $client->setHeaders(['Authorization' => 'Bearer ' . $token]);
   $result = $client->query($query);