Akeneo3 2 Tessa Connector Laravel Package

Getting Started

Minimal Steps to Begin

1. Verify Akeneo API Readiness Ensure Akeneo 3.2 API is functional (test via GET /api/rest/v1/products). Debug Apache if authentication headers are stripped (see Akeneo Troubleshooting).

2. Install the Bundle

   composer require eikona-media/akeneo3-2-tessa-connector
   

3. Register Routing Append to app/config/routing.yml:

   tessa_media:
       resource: "@EikonaTessaConnectorBundle/Resources/config/routing.yml"
   

4. Configure TESSA Connection Set TESSA API credentials in app/config/parameters.yml:

   parameters:
       tessa.connector.api_url: "https://your-tessa-instance/api"
       tessa.connector.api_key: "your-api-key"
   

5. First Use Case: Sync a Product Image Use the CLI command to push an Akeneo product image to TESSA:

   php bin/console tessa:media:sync --product="PRODUCT_SKU" --media-file="image.jpg"
   

Implementation Patterns

Core Workflows

1. Media Synchronization

   • Push Media: Sync product media (images, videos) from Akeneo to TESSA via:

     php bin/console tessa:media:push --product="SKU" --media-code="IMAGE_CODE"
     

   • Pull Metadata: Fetch TESSA metadata (e.g., alt text, tags) back to Akeneo:

     php bin/console tessa:metadata:pull --product="SKU"
     

2. Event-Driven Integration

   • Subscribe to Akeneo events (e.g., product.save) to auto-trigger syncs:

     // In a custom event subscriber
     public function onProductSave(ProductUpdateEvent $event) {
         $this->tessaSyncService->syncProduct($event->getProduct());
     }
     

3. Batch Processing

   • Use the tessa:media:batch command to sync media for multiple products:

     php bin/console tessa:media:batch --products="SKU1,SKU2"
     

Integration Tips

• Custom Fields: Map Akeneo custom fields to TESSA metadata using YAML config:

  # app/config/tessa_connector.yml
  field_mapping:
      tessa_alt_text: "akeneo_custom_field.alt_text"
  

• Webhooks: Configure TESSA webhooks to notify Akeneo of updates (requires custom endpoint in Akeneo).
• Caching: Cache TESSA API responses to reduce load (use Symfony’s Cache component).

Gotchas and Tips

Pitfalls

1. API Rate Limits

   • TESSA may throttle requests. Implement exponential backoff in custom sync logic:

     try {
         $response = $tessaClient->upload($media);
     } catch (RateLimitException $e) {
         sleep($e->getRetryAfter());
         retry();
     }
     

2. Media File Paths

   • Hardcoded paths in the bundle may break if Akeneo’s file storage is misconfigured. Override paths in tessa_connector.yml:

     media_root_dir: "%kernel.project_dir%/var/media"
     

3. Authentication Headers

   • If TESSA rejects requests, verify Authorization headers are included. Extend the HTTP client:

     $client = new Client([
         'headers' => [
             'Authorization' => 'Bearer ' . $this->apiKey,
         ],
     ]);
     

Debugging

• Enable Verbose Logging Set TESSA_CONNECTOR_DEBUG=1 in .env to log raw API requests/responses.
• Check Event Dispatching Use bin/console debug:event-dispatcher to verify Akeneo events are firing.
• Validate Media Codes Ensure Akeneo media codes (e.g., image_1) match TESSA’s expected format.

Extension Points

1. Custom Sync Logic Extend the TessaSyncService to add pre/post-sync hooks:

   // src/Eikona/TessaConnectorBundle/Service/TessaSyncService.php
   public function syncProduct(Product $product) {
       $this->preSync($product);
       // Default sync logic
       $this->postSync($product);
   }
   

2. New Media Types Add support for non-standard file types (e.g., 3D models) by extending the MediaHandler interface:

   class CustomMediaHandler implements MediaHandlerInterface {
       public function handle(MediaInterface $media) {
           // Custom logic for .gltf files
       }
   }
   

3. Webhook Endpoint Create a custom controller to handle TESSA webhook payloads:

   // src/Controller/TessaWebhookController.php
   class TessaWebhookController extends Controller {
       public function handleWebhook(Request $request) {
           $payload = json_decode($request->getContent(), true);
           $this->tessaSyncService->processWebhook($payload);
       }
   }