Piivo Connector Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require akeneo/piivo-connector:1.1.*
   

   Enable the bundle in AppKernel.php:

   new Piivo\Bundle\ConnectorBundle\PiivoConnectorBundle(),
   new Pim\Bundle\ExtendedAttributeTypeBundle\PimExtendedAttributeTypeBundle(),
   

2. Routing: Add to app/config/routing.yml:

   piivo_api:
       resource: "@PiivoConnectorBundle/Resources/config/routing.yml"
       prefix: /api
   

3. Elasticsearch Configuration: Update app/config/pim_parameters.yml to include:

   elasticsearch_index_configuration_files:
       - '%kernel.root_dir%/../vendor/akeneo/extended-attribute-type/src/Resources/config/elasticsearch/index_configuration.yml'
   

4. Clear Cache & Rebuild Indexes (if upgrading):

   php bin/console cache:clear --no-warmup --env=prod
   php bin/console akeneo:elasticsearch:reset-indexes --env=prod
   php bin/console pim:product:index --all --env=prod
   

First Use Case

Sync a Product with PiiVO DAM: Use the API to push product images/metadata to PiiVO:

curl -X POST -H "Content-Type: application/json" \
  http://your-pim/api/piivo/sync \
  -d '{"productId": "PRODUCT_SKU", "piivoAssetId": "ASSET_ID"}'

Implementation Patterns

Workflows

1. Product Asset Sync:

   • Trigger sync via API (/api/piivo/sync) with productId and piivoAssetId.
   • Use PiiVOConnectorBundle services to validate and process assets.

2. Extended Attributes:

   • Leverage ExtendedAttributeTypeBundle to map custom fields (e.g., piivo_asset_reference) to PiiVO DAM.
   • Example in a product form:

     {{ form_row(product.form.piivo_asset_reference) }}
     

3. Event Listeners:

   • Hook into Akeneo’s product lifecycle (e.g., ProductUpdateEvent) to auto-sync assets:

     // src/Akeneo/Pim/EventListener/PiiVOListener.php
     public function onProductUpdate(ProductUpdateEvent $event) {
         $product = $event->getProduct();
         if ($product->getPiivoAssetId()) {
             $this->piivoService->sync($product);
         }
     }
     

4. Batch Processing:

   • Use Akeneo’s job queue (pim:job:execute) to sync assets for multiple products:

     php bin/console pim:job:execute piivo-sync-job
     

Integration Tips

• API Authentication: Secure endpoints with Akeneo’s built-in auth (e.g., api_login token).
• Error Handling: Log PiiVO API failures to monolog:

  $logger->error('PiiVO sync failed', ['product' => $product->getId(), 'error' => $e->getMessage()]);
  

• Testing: Mock PiiVO API responses in PHPUnit:

  $this->get('piivo.client')->method('post')->willReturn(['success' => true]);
  

Gotchas and Tips

Pitfalls

1. Deprecated Dependencies:

   • Package is unmaintained (last release: 2018). Test thoroughly with Akeneo v2.x (or downgrade to v1.7).
   • Workaround: Fork the repo and update dependencies (e.g., akeneo/extended-attribute-type).

2. Elasticsearch Index Conflicts:

   • If reset-indexes fails, manually delete indices in Elasticsearch:

     curl -XDELETE 'http://localhost:9200/pim_product*'
     

   • Tip: Use --env=dev for testing before production.

3. API Rate Limits:

   • PiiVO may throttle requests. Implement retries with exponential backoff:

     use Symfony\Component\HttpClient\RetryStrategy;
     $client = HttpClient::create([
         'retry_strategy' => new RetryStrategy(3, 1000, true),
     ]);
     

4. Missing Documentation:

   • API specs are vague. Use bin/console debug:router | grep piivo to discover endpoints.
   • Tip: Inspect PiivoConnectorBundle/Resources/config/routing.yml for undocumented routes.

Debugging

• Enable API Debugging: Add to config.yml:

  piivo_connector:
      debug: true
  

  Logs will appear in var/log/dev.log.

• Common Issues:

  • 404 Errors: Verify routing.yml prefix (/api) and bundle enablement.
  • 500 Errors: Check var/log/prod.log for Piivo\Exception\* exceptions.
  • Asset Not Found: Validate piivoAssetId exists in PiiVO DAM before sync.

Extension Points

1. Custom Sync Logic: Extend PiivoSyncService:

   class CustomPiiVOService extends PiivoSyncService {
       protected function preSync(Product $product) {
           // Add pre-processing (e.g., transform images)
       }
   }
   

   Override in services.yml:

   piivo.sync_service: '@custom_piivo_service'
   

2. New API Endpoints: Create a custom controller extending PiivoBaseController:

   class CustomPiiVOController extends PiivoBaseController {
       public function customAction() {
           // Extend existing API
       }
   }
   

   Register in routing.yml:

   custom_piivo:
       path: /api/piivo/custom
       defaults: { _controller: PiivoConnectorBundle:CustomPiiVO:custom }
   

3. Webhook Integration: Use Akeneo’s WebhookBundle to trigger PiiVO syncs on product events:

   # config/webhooks.yml
   piivo_sync_webhook:
       name: "PiiVO Sync"
       url: "http://your-pim/api/piivo/sync"
       events: ["product_update"]