Sylius Setup Guide

Architecture

The plugin is a Symfony bundle that hooks into Sylius via resource events (sylius.product.post_update, sylius.product_variant.post_update, etc.), Doctrine lifecycle events for page entities, and the Sylius checkout workflow (Symfony Workflow on 2.x, Winzou state machine on 1.x) for conversion tracking.

Webhook events use deferred delivery: event subscribers queue payloads in an in-memory WebhookEventQueue with deduplication, and the queue flushes to Emporiqa on kernel.terminate after the HTTP response is sent. Saving a product or completing checkout never blocks on the outbound HTTP call.

All translations and channels for a single product or page consolidate into one webhook event. Variant changes cascade to the parent: editing a variant triggers a parent re-sync so search always sees the full catalog state. Every service that formats, resolves, looks up, or transports data ships behind an interface so you can decorate any part of the pipeline without patching plugin code.

Requirements

Configuration Reference

Configuration lives in config/packages/emporiqa.yaml. Only store_id, webhook_url, and webhook_secret are required. Everything else has sensible defaults.

Settings

Full configuration example

# config/packages/emporiqa.yaml
emporiqa:
    store_id: '%env(EMPORIQA_STORE_ID)%'
    webhook_url: '%env(EMPORIQA_WEBHOOK_URL)%'
    webhook_secret: '%env(EMPORIQA_WEBHOOK_SECRET)%'
    base_url: 'https://myshop.com'
    media_base_path: '/media/image/'
    brand_attribute_code: 'brand'
    enabled_languages: ['en_US', 'de_DE']
    sync:
        products: true
        pages: true
    page_entity_classes:
        - App\Entity\StaticPage
        - App\Entity\BlogPost
    order_tracking:
        enabled: true
    cart:
        enabled: true

Channels

The plugin uses the Sylius channel code directly as the Emporiqa channel identifier — no mapping configuration needed. Each channel's pricing, availability, and translations are consolidated into the same webhook event.

Features

Webhook Payload

Webhook requests are POSTed to the configured webhook_url with an X-Webhook-Signature header containing the HMAC-SHA256 signature of the raw body. Each request carries a batch of events.

Batch envelope

{
  "events": [
    {"type": "product.updated", "data": {...}},
    {"type": "product.updated", "data": {...}}
  ]
}

Event types

Product event

{
  "type": "product.updated",
  "data": {
    "identification_number": "product-123",
    "sku": "PROD-123",
    "channels": ["", "b2b"],
    "names":        {"": {"en_US": "Product Name", "de_DE": "Produktname"}, "b2b": {"en_US": "Product Name"}},
    "descriptions": {"": {"en_US": "Description...", "de_DE": "Beschreibung..."}},
    "links":        {"": {"en_US": "https://store.com/en_US/products/product-name", "de_DE": "https://store.com/de_DE/products/produktname"}},
    "categories":   {"": {"en_US": ["Electronics"], "de_DE": ["Elektronik"]}, "b2b": {"en_US": ["Electronics"]}},
    "attributes":   {"": {"en_US": {"Color": "Blue"}, "de_DE": {"Farbe": "Blau"}}},
    "brands":       {"": "Brand Name", "b2b": "Brand Name"},
    "prices":       {"": [{"currency": "EUR", "current_price": 79.99, "regular_price": 99.99}], "b2b": [{"currency": "USD", "current_price": 69.99, "regular_price": 89.99}]},
    "images":       {"": ["https://store.com/media/image/product.jpg"]},
    "availability_statuses": {"": "available", "b2b": "available"},
    "stock_quantities":      {"": 25, "b2b": 25},
    "parent_sku": null,
    "is_parent": false,
    "variation_attributes": {}
  }
}

Field structure

For variable products, the parent ships with is_parent: true and variation_attributes containing translated option names. Each variant ships separately with parent_sku set and variation_attributes: {}. Delete events contain only identification_number.

Customization

Every behavior customization goes through standard Symfony mechanisms: service decoration for replacing pipeline components, and event listeners for reacting to the sync lifecycle. No plugin code gets patched.

Service interfaces you can decorate

Symfony events you can listen to

Example: decorate the order provider

namespace App\Service;

use Emporiqa\SyliusPlugin\Service\OrderProviderInterface;

class CustomOrderProvider implements OrderProviderInterface
{
    public function __construct(
        private OrderProviderInterface $inner,
    ) {}

    public function findOrder(string $identifier, ?string $userId, array $verificationFields): ?array
    {
        $order = $this->inner->findOrder($identifier, $userId, $verificationFields);

        if ($order !== null) {
            $order['loyalty_points'] = $this->pointsFor($identifier);
        }

        return $order;
    }
}

# config/services.yaml
services:
    App\Service\CustomOrderProvider:
        decorates: Emporiqa\SyliusPlugin\Service\OrderProviderInterface

Example: mutate product data before send

namespace App\EventListener;

use Emporiqa\SyliusPlugin\Event\PostFormatEvent;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;

#[AsEventListener(event: PostFormatEvent::NAME)]
class ExtraProductFieldsListener
{
    public function __invoke(PostFormatEvent $event): void
    {
        $events = $event->getFormattedEvents();

        foreach ($events as &$webhookEvent) {
            $webhookEvent['data']['sustainability_score'] = 'A+';
        }

        $event->setFormattedEvents($events);
    }
}

Page sync setup

Implement Emporiqa\SyliusPlugin\Model\PageInterface on your page entity (the translations must expose getTitle(), getContent(), getSlug(), getLocale()), list its FQCN under page_entity_classes, and decorate PageUrlResolverInterface to emit real URLs. Without the decorator, the default resolver returns an empty string.

Console Commands

All commands use memory-efficient batching and can run in reconciliation sessions — items not seen during the session can be marked deleted on the Emporiqa side.

Shared flags

# Full reconciliation
bin/console emporiqa:sync:all

# Products only, small batches, no session markers
bin/console emporiqa:sync:products --batch-size=25 --no-session

# Validate payload without sending
bin/console emporiqa:sync:products --dry-run

# End-to-end connection test
bin/console emporiqa:test-connection -v

Order Tracking

Emporiqa can look up order status on behalf of customers during chat conversations. The plugin mounts a signed endpoint that Sylius responds to when a customer asks about their order.

Endpoint

Flow

1. Customer asks "Where is my order #000001234?" in the chat.
2. Emporiqa POSTs a signed payload (HMAC-SHA256, via X-Emporiqa-Signature) to the endpoint.
3. The OrderProvider looks up the order through Sylius's OrderRepositoryInterface, verifies any verification_fields (e.g. billing email), and maps payment/shipping state into a normalized status.
4. The salesperson presents the order information to the customer.

Setup

The endpoint is active as soon as the plugin is installed (unless order_tracking.enabled is false). To let Emporiqa call it, set the Order Tracking API URL in your dashboard (Store Settings → Integration) to:

Status mapping

Troubleshooting