Shopware Connector Laravel Package

Getting Started

Minimal Setup

1. Installation

   • Add the bundle to AppKernel.php:

     new \Basecom\Bundle\ShopwareConnectorBundle\BasecomShopwareConnectorBundle(),
     

   • Configure akeneo_storage_utils in config.yml:

     akeneo_storage_utils:
         mapping_overrides:
             - { original: Pim\Bundle\CatalogBundle\Entity\Category, override: Basecom\Bundle\ShopwareConnectorBundle\Entity\Category }
             - { original: Pim\Bundle\CatalogBundle\Entity\Family, override: Basecom\Bundle\ShopwareConnectorBundle\Entity\Family }
             - { original: Akeneo\Component\FileStorage\Model\FileInfo, override: Basecom\Bundle\ShopwareConnectorBundle\Entity\FileInfo }
             - { original: Pim\Component\Catalog\Model\Product, override: Basecom\Bundle\ShopwareConnectorBundle\Entity\Product }
     

   • Run:

     php app/console cache:clear --env=prod
     php app/console doctrine:schema:update --force
     

2. Shopware Extension

   • Install the Shopware extension to enable custom attribute and shop imports into Akeneo.

3. First Export Job

   • Configure API credentials in Akeneo under Export Job (found in Shopware’s user management).
   • Map Akeneo attributes to Shopware fields manually (e.g., name → name, sku → article_number).

4. Run Initial Sync

   • Execute the export job once to populate Shopware with Akeneo data.

First Use Case: Product Sync

1. Create a Product in Akeneo
   • Add a product with attributes (e.g., name, sku, price, images).
2. Trigger Export
   • Run the Akeneo export job (php app/console akeneo:export:product).
3. Verify in Shopware
   • Check if the product appears in Shopware with mapped attributes.

Implementation Patterns

Workflow: Daily Sync

1. Attribute Mapping

   • Use the dropdowns in the Akeneo UI to map Akeneo attributes to Shopware fields (e.g., pim_catalog_identifier → article_number).
   • Example mapping for a price attribute:

     # config/akeneo_shopware.yml
     attributes:
         price:
             shopware_field: price
             type: decimal
     

2. Job Configuration

   • Configure the export job in Akeneo:

     php app/console akeneo:export:product --job-name="shopware_export" --api-key="your_shopware_api_key"
     

   • Schedule via cron (e.g., nightly):

     0 3 * * * php /path/to/akeneo/app/console akeneo:export:product --job-name="shopware_export"
     

3. Handling Associations

   • Enable association support (e.g., linked products, categories):

     associations:
         - { type: "CATEGORY", attribute: "categories" }
         - { type: "PRODUCT", attribute: "related_products" }
     

4. Media Handling

   • Use the MediaWriter to sync images/videos:

     // In a custom exporter service
     $mediaWriter = $this->container->get('basecom_shopware_connector.media_writer');
     $mediaWriter->write($fileInfo, $productId);
     

Integration Tips

1. Custom Exporters

   • Extend the base exporter for custom logic:

     namespace AppBundle\Exporter;
     
     use Basecom\Bundle\ShopwareConnectorBundle\Exporter\AbstractExporter;
     
     class CustomProductExporter extends AbstractExporter
     {
         protected function transformProduct($product)
         {
             // Custom transformations
             $data = parent::transformProduct($product);
             $data['custom_field'] = $product->getCustomAttribute();
             return $data;
         }
     }
     

   • Register in services.yml:

     app.custom_product_exporter:
         class: AppBundle\Exporter\CustomProductExporter
         tags:
             - { name: akeneo_shopware.exporter, type: product }
     

2. Webhooks for Real-Time Sync

   • Use Shopware’s webhooks to trigger Akeneo exports on product updates:

     // Shopware hook (e.g., afterSaveProduct)
     $client = new \GuzzleHttp\Client();
     $client->post('http://akeneo/api/export', [
         'json' => ['product_id' => $productId]
     ]);
     

3. Error Handling

   • Log export failures to a custom table:

     $logger = $this->container->get('logger');
     $logger->error('Export failed for product ' . $product->getId(), [
         'error' => $e->getMessage(),
         'product' => $product->getIdentifier()
     ]);
     

Gotchas and Tips

Pitfalls

1. API Key Mismatch

   • Issue: Export fails with 401 Unauthorized.
   • Fix: Verify the API key in Akeneo matches Shopware’s user management.
   • Debug: Check Shopware logs (/var/log/shopware.log) for API errors.

2. Attribute Mapping Errors

   • Issue: Custom attributes don’t sync.
   • Fix:
     • Ensure the Shopware extension is installed.
     • Manually map attributes in Akeneo’s export job UI.
   • Debug: Use bin/console debug:akeneo:shopware:attributes to list unmapped attributes.

3. Media Sync Failures

   • Issue: Images/videos don’t appear in Shopware.
   • Fix:
     • Verify file paths in Akeneo (/app/storage/files/).
     • Check Shopware’s media import settings.
   • Debug: Enable debug mode in config.yml:

     basecom_shopware_connector:
         debug: true
     

4. Association Loops

   • Issue: Circular references in associations (e.g., Product → Category → Product).
   • Fix: Limit association depth in config:

     associations:
         max_depth: 2
     

Debugging Tips

1. Enable Verbose Logging

   • Add to config.yml:

     monolog:
         handlers:
             main:
                 level: debug
     

   • Check logs at var/log/dev.log.

2. Validate API Responses

   • Use Postman to test Shopware’s API endpoint directly:

     POST /api/_action/akeneo_import
     Headers: { Authorization: Bearer YOUR_API_KEY }
     Body: { "data": [...] }
     

3. Database Schema Issues

   • If doctrine:schema:update fails:

     php app/console doctrine:schema:update --dump-sql
     

   • Manually run SQL if needed (backup first!).

Extension Points

1. Custom Field Transformers

   • Override attribute transformations:

     namespace AppBundle\Transformer;
     
     use Basecom\Bundle\ShopwareConnectorBundle\Transformer\AbstractTransformer;
     
     class CustomPriceTransformer extends AbstractTransformer
     {
         public function transform($value, $attribute)
         {
             return $value * 1.1; // Add 10% tax
         }
     }
     

   • Register in services.yml:

     app.custom_price_transformer:
         class: AppBundle\Transformer\CustomPriceTransformer
         tags:
             - { name: akeneo_shopware.transformer, attribute: price }
     

2. Pre/Post Export Hooks

   • Add logic before/after export:

     namespace AppBundle\EventListener;
     
     use Basecom\Bundle\ShopwareConnectorBundle\Event\ExportEvent;
     
     class ExportListener
     {
         public function onExport(ExportEvent $event)
         {
             if ($event->getType() === 'product') {
                 $event->getProduct()->setCustomField('pre_export_value');
             }
         }
     }
     

   • Register in services.yml:

     app.export_listener:
         class: AppBundle\EventListener\ExportListener
         tags:
             - { name: kernel.event_listener, event: akeneo_shopware.export, method: onExport }
     

3. Shop-Specific Configs

   • Use environment variables for multi-shop setups:

     # config/parameters.yml
     parameters:
         shopware_api_key: "%env(SHOPWARE_API_KEY)%"
         shopware_base_url: "%env(SHOPWARE_URL)%"
     

   • Load per-shop mappings:

     $shop = $event->getShop();
     $mappings = $this->container->get('akeneo_shopware.mapping_loader