Getting Started

Minimal Steps

Verify Akeneo API Readiness Ensure your Akeneo 5.0 instance API is functional (test via GET /api/rest/v1/products). Debug Apache misconfigurations if headers are stripped (see Akeneo API Troubleshooting).

Install the Bundle

composer require eikona-media/akeneo5-0-tessa-connector

Register Routes Append to config/routes/routes.yml:

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

Configure TESSA Connection Set TESSA API credentials in config/packages/eikona_tessa_connector.yaml:

eikona_tessa_connector:
    api:
        endpoint: "https://your-tessa-instance.com/api"
        username: "your_username"
        password: "your_password"

First Use Case: Sync a Product’s Media Use the CLI command to push a product’s media to TESSA:
```
php bin/console eikona:tessa:push-product-media <product-sku>
```

Implementation Patterns

Workflows

Media Synchronization
- Pull from TESSA: Fetch assets from TESSA and attach them to Akeneo products via:
```
php bin/console eikona:tessa:pull-media <product-sku>
```
- Push to TESSA: Upload Akeneo product media to TESSA:
```
php bin/console eikona:tessa:push-product-media <product-sku>
```
- Batch Processing: Use --batch flag for bulk operations (e.g., php bin/console eikona:tessa:push-product-media --batch).

Event-Driven Integration Subscribe to Akeneo events (e.g., product.save) to auto-sync media:

// config/services.yaml
services:
    App\EventListener\TessaMediaSyncListener:
        tags:
            - { name: kernel.event_listener, event: product.save, method: onProductSave }

// src/EventListener/TessaMediaSyncListener.php
use Eikona\TessaConnectorBundle\Service\TessaMediaService;

class TessaMediaSyncListener {
    public function __construct(private TessaMediaService $tessaMediaService) {}

    public function onProductSave(ProductInterface $product) {
        $this->tessaMediaService->pushProductMedia($product->getCode());
    }
}

Custom Field Mapping Override default field mappings (e.g., for custom TESSA metadata) in config/packages/eikona_tessa_connector.yaml:
```
eikona_tessa_connector:
    field_mapping:
        tessa_custom_field: "custom_attribute_code"
```

Integration Tips

Akeneo API Client: Use the bundled AkeneoApiClient for custom API calls:

$client = $this->container->get('eikona_tessa_connector.akeneo_api_client');
$products = $client->getProducts(['limit' => 10]);

Logging: Enable debug mode for sync operations:

# config/packages/monolog.yaml
handlers:
    tessa:
        type: stream
        path: "%kernel.logs_dir%/tessa.log"
        level: debug

Queue Jobs: Offload heavy syncs to Laravel queues (requires symfony/messenger):
```
$this->tessaMediaService->pushProductMediaAsync($productSku);
```

Gotchas and Tips

Pitfalls

API Authentication Failures
- Symptom: 401 Unauthorized errors when syncing.
- Fix: Verify TESSA credentials in config/packages/eikona_tessa_connector.yaml and check Akeneo API headers (ensure Authorization is not stripped by Apache).
- Debug: Enable debug mode in TESSA and check logs for rejected requests.
Media File Size Limits
- Symptom: Large files fail to upload with 413 Payload Too Large.
- Fix: Adjust client_max_body_size in Apache/Nginx or TESSA’s upload limits.
Field Mapping Conflicts
- Symptom: Media sync skips fields or throws InvalidArgumentException.
- Fix: Validate field mappings in config/packages/eikona_tessa_connector.yaml against Akeneo’s product attributes and TESSA’s schema.
Duplicate Media Handling
- Symptom: Existing media in TESSA is overwritten or duplicated.
- Fix: Use unique_identifier in config to deduplicate:
```
eikona_tessa_connector:
    unique_identifier: "tessa_media_id"
```

Debugging

CLI Verbosity: Add -v or -vvv to commands for detailed logs:

php bin/console eikona:tessa:push-product-media SKU -vvv

Dry Runs: Test mappings without syncing:

php bin/console eikona:tessa:validate-mapping <product-sku>

Database Dumps: Export Akeneo’s pim_catalog_product table to verify media associations:
```
SELECT * FROM pim_catalog_product WHERE code = 'SKU';
```

Extension Points

Custom Sync Logic Extend the TessaMediaService to add pre/post-sync hooks:

// src/Service/CustomTessaMediaService.php
use Eikona\TessaConnectorBundle\Service\TessaMediaService;

class CustomTessaMediaService extends TessaMediaService {
    public function pushProductMedia(string $sku): void {
        // Custom logic before sync
        parent::pushProductMedia($sku);
        // Custom logic after sync
    }
}

services:
    Eikona\TessaConnectorBundle\Service\TessaMediaService:
        alias: App\Service\CustomTessaMediaService

Custom TESSA API Endpoints Override the TessaApiClient to support non-standard endpoints:

// src/Client/CustomTessaApiClient.php
use Eikona\TessaConnectorBundle\Client\TessaApiClient;

class CustomTessaApiClient extends TessaApiClient {
    protected function getBaseUri(): string {
        return 'https://custom-tessa-endpoint.com/api';
    }
}

Bind the service in config/services.yaml:

services:
    Eikona\TessaConnectorBundle\Client\TessaApiClient:
        class: App\Client\CustomTessaApiClient

Webhook Integration Listen for TESSA webhooks to trigger Akeneo updates:

// src/Controller/TessaWebhookController.php
use Symfony\Component\HttpFoundation\Request;
use Eikona\TessaConnectorBundle\Service\TessaWebhookService;

class TessaWebhookController {
    public function __construct(private TessaWebhookService $webhookService) {}

    public function handle(Request $request) {
        $this->webhookService->processWebhook($request->getContent());
        return new Response('OK');
    }
}

Route the webhook in config/routes.yaml:

tessa_webhook:
    path: /tessa/webhook
    controller: App\Controller\TessaWebhookController::handle
    methods: [POST]

Akeneo5 0 Tessa Connector Laravel Package