PrestaShop Integration¶

Reference for App\Integrations\PrestaShop\PrestaShopIntegration. Covers the connectivity verification contract, the customer, product, and order bulk-export implementations, inbound consent-webhook handling, the HTTP endpoints they target, and the test coverage for each.

Class¶

Namespace: App\Integrations\PrestaShop\PrestaShopIntegration Extends: App\Services\AbstractIntegration Implements: CanExportInBulk, CanHandleWebhooks, CanPullConsent, CanVerifyConnections, HasConnectionConfiguration, HasDeletionLog (use ExportsInBulk, FetchesDeletionLog, HandlesWebhooks, PullsConsent, VerifiesConnections)

PrestaShopIntegration and UserPlatformIntegration are the two registered integrations implementing CanHandleWebhooks and CanPullConsent — see Registered Integrations.

Connectivity Verification¶

PrestaShopIntegration implements performVerification(SystemConnection $connection): VerificationResult, which is called by the sealed VerifiesConnections::verify(). Any uncaught Throwable from performVerification() is caught by verify() and converted into a failed VerificationResult, so callers never handle exceptions from the verification path.

What it does¶

1. Reads api_key from the connection's encrypted credentials array.
2. GETs {base_url}/api/shops?output_format=JSON using HTTP Basic Auth — the API key as the username, an empty password (the PrestaShop legacy Webservice API convention).
3. TLS certificate verification is disabled when running locally (app()->isLocal()), to allow self-signed certificates in local PrestaShop containers.
4. $response->throw() raises on any non-2xx status, which VerifiesConnections::verify() catches and converts to a failed VerificationResult.
5. If this is a finalizing plugin-initiated connection (see Widget token push below), pushes a widget token to the module.
6. On success, uses the connection's base_url as the external user identifier — not the shop's internal id (shops.0.id). Nearly all PrestaShop installs are single-shop and report shops.0.id === 1, which would collide with the (tenant_id, system_id, external_user_id) unique index across unrelated shops; the base URL is unique per shop and matches the pattern WooCommerceIntegration uses.

Endpoint¶

GET {base_url}/api/shops?output_format=JSON

Authenticated via HTTP Basic Auth: credentials.api_key as username, empty password.

Outcomes¶

VerificationResult shape¶

Namespace: App\Data\VerificationResult

Widget token push¶

A private pushWidgetTokenIfFinalizingPluginInitiated(SystemConnection $connection): void helper, called from performVerification() right after the API-key check succeeds, pushes a widget access token to the PrestaShop module — mirroring the equivalent push WooCommerceIntegration performs for its own plugin.

When it fires. Only when the connection is persisted ($connection->exists) and has no tenant yet (tenant_id === null). That combination identifies one specific moment in the plugin-initiated handshake: the already-connected caller's POST /connect finalization step, where a pending, tenant-less SystemConnection created earlier by the plugin's own POST /register call is re-verified before being handed a tenant. The helper is a no-op in the two other cases performVerification() can run under:

• Transient connections — the plugin's own POST /register call verifies an unsaved, in-memory SystemConnection ($connection->exists is false).
• Tenant-initiated (Flow B) connections — by the time verification runs, tenant_id is already set to the caller's tenant.

What it does. Issues an access token via $this->connectionTokenIssuerService->issueAccessToken($connection, 'plugin-widget') (see Connection Widget for the plugin-widget token name) and POSTs it as { "widget_token": "..." } to:

POST {module_url}/connectivitycheck

module_url credential. A PrestaShop module's front-controller directory (e.g. https://shop.example.com/module/rapidmail) is install-specific — it depends on the module's technical name, which branded builds rename and which is not assumed to be conflux or any other fixed value (CFX-152/CFX-230). The plugin therefore supplies its own front-controller base as a plain-text module_url credential at registration time, alongside api_key; a private moduleUrl(SystemConnection $connection): string helper reads it from credentials.module_url, defaulting to an empty string if missing or non-string. SystemSeeder declares it as a non-secret auth_fields entry (store_url, api_key, module_url, brand_name, in that order) for the prestashop system.

brand_name credential. A second, separately-reported non-secret credential — this build's brand identifier, the same value baked into module_url's /module/{name} segment, exposed as its own field. Not read anywhere in PrestaShopIntegration (module_url already covers URL building); it exists purely so Conflux has one generic "which brand is this store paired to" field with the same key name across integrations — conflux-connector (WooCommerce) reports the same brand_name key for its own branded routes, see WooCommerce Integration reference.

Failure handling. Best-effort in the sense that the response is never inspected and ->throw() is never called on it, so an HTTP error status from the module (e.g. a 404 because module_url points at the wrong path) does not fail verification. A connection-level failure (DNS, timeout, refused connection) is a different story: Http::post() raises a ConnectionException for those regardless of ->throw(), which propagates out of performVerification() and is caught by VerifiesConnections::verify() like any other exception — converted into a failed VerificationResult, even though the shop's own API credentials were valid.

Source locale resolution¶

performVerification() calls the public resolveSourceLocale(SystemConnection $connection): ?string right after resolveSourceTimezone() and before the widget token push, and only for a connection that already has a row (RemembersSourceLocale::shouldResolveSourceLocale() — see WooCommerce Integration — source locale resolution for why a transient one is not asked). Two requests, chained:

GET {base_url}/api/configurations?output_format=JSON&filter[name]=PS_LANG_DEFAULT&display=[value]   → the default language's numeric id
GET {base_url}/api/languages/{id}?output_format=JSON                                                  → that language's locale field

The second response is read as language.locale (PrestaShop 1.7 and later — an IETF tag such as de-DE) falling back to language.language_code where locale is absent or empty (PrestaShop 1.6, and a 1.7 shop upgraded from it whose locale was never backfilled — PrestaShop renders an empty element as "" or [], never as null, so a fallback keyed on null alone would skip exactly those shops). Either way the result is remembered on system_connections.source_locale by the shared App\Services\Concerns\RemembersSourceLocale trait — the same trait WooCommerceIntegration uses (see WooCommerce Integration — source locale resolution): a value that looks like a locale is stored, anything else leaves the previously stored value standing, and a transient (not yet persisted) connection is never written to even though the resolved value is still returned — which is exactly why verification does not ask such a connection in the first place.

Both requests are authenticated the same way as every other Webservice API call — credentials.api_key as the Basic Auth username, empty password — via the same client() helper, capped at PrestaShopIntegration::LOOKUP_TIMEOUT_SECONDS (10 seconds) each: they run inside a synchronous registration call, and two requests on Laravel's 30-second default would hold one up for a minute against a shop that is slow rather than dead. Either request failing (a non-2xx response) or throwing a ConnectionException returns the connection's already-stored source_locale unchanged; the language id being missing, empty or non-scalar does the same, and the second request is then not sent at all — an empty id would address /api/languages/, the collection endpoint. Nothing here calls ->throw().

Locale vs. timezone: load-bearing vs. fallback¶

Both are shop-published settings resolved during performVerification(), one right after the other, but they are not the same kind of thing:

Bulk Export¶

PrestaShopIntegration implements fetchBulkExportBatches(), performProbeBulkExport(), performFetchBulkExportPageRange(), and provideTransformerClass(). Both the sequential and the parallel path dispatch on $request->capability via a match with no default arm — all three SystemCapability cases are handled explicitly in each:

The sequential helpers run a full pagination loop internally and are exercised whenever a caller drives requestBulkExport()/streamBulkExport() directly, as the unit tests below do. In production, BulkSyncJob instead calls probeBulkExport() first and fans out parallel FetchBulkPageRangeJobs via fetchBulkExportPageRange() — see Parallel bulk export below.

Parallel bulk export (page-range fan-out)¶

Unlike WooCommerce's REST API, PrestaShop's Webservice API exposes no total-count or total-pages response header. performProbeBulkExport() works around this by listing all record ids for the resource in a single unpaginated request — display=[id], no limit parameter at all — and deriving the page count from the number of ids returned:

GET {base_url}/api/{customers|products|orders}?output_format=JSON&display=[id]

$totalPages = (int) ceil(count($ids) / PrestaShopIntegration::PER_PAGE); // PER_PAGE = 50

If the resource has no records at all, totalPages is 0. Otherwise BulkSyncJob fans out FetchBulkPageRangeJob batches of up to 5 pages each (BulkSyncJob::PAGES_PER_JOB) — the same mechanism WooCommerceIntegration uses, just fed by an id count instead of a response header.

performFetchBulkExportPageRange() dispatches on capability the same way fetchBulkExportBatches() does, delegating to a private page-range counterpart (see table above). Each counterpart loops $startPage to $endPage and issues one limit=<offset>,<count> request per page — the same offset-based pagination the sequential loop uses, just bounded to the assigned range instead of running until a short page.

Per-job lookup prefetch¶

Products and Orders both depend on lookups resolved from other PrestaShop resources (category names, the default currency, order state names, currency codes, country names). In the sequential path these are resolved once for the whole export, before the pagination loop starts. The parallel path has no single "whole export" scope — each FetchBulkPageRangeJob runs independently — so each page-range job resolves its own copy of these lookups once per job, before looping over its assigned pages:

This is a deliberate trade-off for job independence, not a bug: a full parallel export re-fetches these lookup resources once per page-range job rather than once per capability. A large product catalogue split across several jobs issues one /api/categories fetch and one /api/configurations+/api/currencies/{id} round-trip per job, not once overall.

Credentials¶

Verification and all three bulk-export paths authenticate via HTTP Basic Auth using credentials.api_key as the username and an empty password. The extraction is shared by a private apiKey(SystemConnection $connection): string helper.

credentials.module_url is a second, non-secret credential, extracted by the private moduleUrl(SystemConnection $connection): string helper and used by the widget token push above and the deletion log endpoint below — bulk export and the shops check never read it. credentials.brand_name is a third, non-secret credential reported alongside it but not read by PrestaShopIntegration at all — see the widget token push section above for why it exists.

Customers¶

Endpoint¶

GET {base_url}/api/customers

The response body is wrapped under a customers key — {"customers": [...]} — not a flat array. The integration reads it via $response->json('customers') ?? []. When the requested offset is beyond the total record count, the real Webservice API returns a bare [] with no customers key at all; the ?? [] fallback covers that case, and the empty result ends the pagination loop.

Pagination¶

The integration instead tracks an $offset (starting at 0, incremented by PrestaShopIntegration::PER_PAGE, i.e. 50, after each request) and sends it via PrestaShop's native limit=<offset>,<count> syntax — limit=0,50 for the first page, limit=50,50 for the next, and so on. There is no total-count or total-pages header to read; the loop condition is unchanged: it continues until a page returns fewer than PER_PAGE (50) items (count($items) === $perPage).

The parallel counterpart, fetchCustomerPageRange(), uses the identical limit=<offset>,<count> request per page, but bounded to the job's assigned $startPage..$endPage range instead of looping until a short page — see Parallel bulk export above.

Delta sync via modifiedAfter¶

The integration filters client-side instead. ExportRequest::$modifiedAfter is an optional CarbonImmutable, so it is already the threshold and nothing in this integration parses it. For every fetched page, a private wasModifiedAfter(array $item, CarbonImmutable $threshold, SourceDateTimes $source): bool helper then discards any record whose date_upd is not strictly after that threshold, before the page is mapped to CustomerData and handed to $onBatch. date_upd itself is read through SourceDateTimes::instantForComparison(), in DATETIME_FORMAT and the resolved shop zone, and a record whose date_upd cannot be placed on the timeline is kept rather than dropped; see Source timezone resolution below. When modifiedAfter is null (a first full sync), no filtering is applied and every fetched record is forwarded. The shop timezone is still resolved, because the values that get mapped need it whether or not anything is filtered.

Because the filtering happens after the full page has already been fetched, a delta sync still retrieves the entire customer list from PrestaShop page by page — there is no bandwidth saving on the outbound HTTP calls. The only effect of modifiedAfter is a reduction in what gets mapped, forwarded downstream, and ultimately persisted. This is not a "real" delta sync from the API's perspective; readers relying on this integration for large PrestaShop stores should budget for a full customer scan on every sync regardless of modifiedAfter.

Source timezone resolution¶

PrestaShop's webservice returns date_add and date_upd in shop-local time with no UTC offset (e.g. 2024-06-01 03:00:00). Every value it sends therefore needs the shop's zone before it can become an instant, and the delta filter needs it too, because modifiedAfter is always a UTC instant. Comparing the two naively in the app timezone (UTC) made delta syncs unreliable: shops ahead of UTC re-exported unchanged records on every run, and shops behind UTC could miss changes entirely.

resolveSourceTimezone(SystemConnection $connection): ?string resolves the shop's configured timezone via the PS_TIMEZONE configuration, using the same lookup pattern fetchDefaultCurrency() uses for PS_CURRENCY_DEFAULT (see Default currency resolution above), and validates the value against PHP's timezone_identifiers_list():

GET {base_url}/api/configurations?filter[name]=PS_TIMEZONE&display=[value]

It runs on every run, not only when modifiedAfter is set. The full sync is the run that writes the historical values for the first time, and it used to be the one run that resolved nothing. The cost is one request per resource per run, measured against that run's page count. Unlike the other lookups (see Per-job lookup prefetch above) it is not resolved once per page-range job: the sequential path resolves once per bulk-export call, and the parallel path resolves once per run, in performProbeBulkExport(), after which the page-range jobs it fans out read the stored value instead of each asking again. A fan-out of N jobs therefore costs the same single request the sequential run costs, rather than N of them. Which of the two a fetch method does is stated by the parse context it builds: sourceDateTimesForSequentialRun() resolves the zone, sourceDateTimesForPageRangeJob() reads what the run already stored. Naming the two paths is what keeps a new fetch method from picking silently, and PrestaShopTimezoneResolutionTest pins the pairing on both paths for all three capabilities. performVerification() resolves it as well, so a first sync already finds a value rather than parsing its whole first batch against none — for a connection that has a row, which is the same condition the locale lookup applies.

A resolved value is remembered on the connection in system_connections.source_timezone, so a later run that cannot reach the configuration endpoint still has a zone. The column is not fillable: the integration writes it directly, never by mass assignment — and by key rather than through save(), the same single-column write RemembersSourceLocale makes. A save() here would commit system_id, base_url and credentials, which the registration flows deliberately leave in memory until verification has succeeded; with credentials committed by a failed attempt, the finalizing endpoint refuses every later one while the token is still unconsumed. The lookup itself is capped at LOOKUP_TIMEOUT_SECONDS like the locale's. The write-back is skipped for a connection that does not exist yet — the transient connection the plugin-initiated registration flow verifies before it decides whether to insert a row at all — and because nothing would keep the answer, verification does not call the resolver for such a connection at all. A direct call still returns the resolved value; a run against the persisted row resolves it again regardless.

A failed lookup, a missing value, or a value that is not a valid PHP timezone identifier falls back to whatever is already stored on the connection, not to the app timezone. That old fallback was a fair trade while the zone fed nothing but a comparison filter, but for a stored instant it is the assumption ADR-0018 forbids, because a wrong zone produces a plausible-looking wrong instant. Where nothing is stored either, the zone is unestablished, sourceDateTimes() receives null, and every instant parsed against it is a recorded parse failure rather than a guess.

The modifiedAfter filter assumes nothing either. wasModifiedAfter() reads date_upd through SourceDateTimes::instantForComparison(), which parses in DATETIME_FORMAT and returns null where the zone was never established or the value does not match the format, and the filter then keeps the record instead of dropping it. The two mistakes are not symmetrical: a record wrongly kept is mapped and then reported as unchanged, whereas a record wrongly dropped is invisible, so a shop whose zone cannot be resolved shows up as a shop full of unreadable timestamps in the log rather than as an empty shop. The failure itself is reported once, by the mapper reading the same field of the same record moments later; the filter's entry point records nothing, because it is handed no field, domain or source id to report against.

Datetime fields¶

The table covers every datetime the integration reads, bulk export and deletion log alike, so no field is discarded by accident. DATETIME_FORMAT is 'Y-m-d H:i:s' and DATE_FORMAT is 'Y-m-d', both declared as constants on the integration. See ADR-0018 for the rule this table applies.

The contrast with WooCommerce is worth naming: an unmapped WooCommerce field travels on as a raw string in customAttributes, whereas an unmapped PrestaShop field is simply gone. Adding a datetime here therefore means mapping it, never relying on pass-through.

Error handling¶

Any response for which $response->failed() is true (any non-2xx status, including 401) causes fetchCustomerBatches() to throw IntegrationRequestException with the HTTP status code. There is no token-refresh-retry logic: PrestaShop authenticates with a static api_key rather than an OAuth token, so there is no refresh-token concept to retry against — a 401 is treated like any other HTTP error, and the request is not retried.

Mapping: PrestaShop customer → CustomerData¶

Field mapping lives on PrestaShopTransformer::mapCustomer() (public static), called directly by PrestaShopIntegration from fetchCustomerBatches() — it is not invoked through the TransformerContract::transform() interface.

addressBilling and addressShipping are not mapped — always null. The real PrestaShop Legacy Webservice API exposes addresses as a separate /api/addresses resource, not inline on the customer record; inline address mapping is deferred to a future ticket. tags is not populated either — it defaults to an empty array as defined by CustomerData.

Consent mapping (ConsentData)¶

PrestaShopTransformer::mapConsents() (private), called from mapCustomerRecords(), maps the bulk-export newsletter field into a ConsentData that follows its customer in the emitted records. PrestaShop has a single newsletter flag and no per-channel breakdown, so a customer yields at most one consent, always on the email channel:

Emits no consent — not an "unsubscribed" one — when newsletter is missing from the response or not a scalar value, or when date_upd is unreadable. A channel the source did not mention is left untouched by ConsentRecorder::write(), so "PrestaShop said nothing" is never persisted as a withdrawal. AbstractTransformer::store() routes the ConsentData to ConsentRecorder::write() (see Internal Consent Recorder), which moves the consent's own change signal only when a value changes.

Products¶

Endpoint¶

GET {base_url}/api/products

The response body is wrapped under a products key — {"products": [...]} — read the same way as customers, via $response->json('products') ?? [].

Category name resolution¶

Product category IDs (associations.categories[].id) need to be resolved to localized names, but PrestaShop does not inline category names on the product resource. Rather than issuing a /api/categories/{id} lookup per product (an N+1 pattern — categories are shared across many products), a private fetchCategoryNames(string $baseUrl, string $apiKey): array helper fetches all categories once per bulk-export call, before the product pagination loop starts:

GET {base_url}/api/categories?output_format=JSON&display=[id,name]&limit={offset},{perPage}

This is paginated the same way as products/customers (offset-based limit, loop until a short page). Each category's name field — like a product's name — is PrestaShop's translatable-field shape (see below) and is resolved via PrestaShopTransformer::mapLocalizedValue(). The result is an array<int, string> lookup keyed by category ID, passed into PrestaShopTransformer::mapProduct() for every product on every page.

Default currency resolution¶

PrestaShopTransformer::mapProduct() takes a fourth parameter, ?string $currency, alongside $data, $categoryNames, and $baseUrl. Like $categoryNames, the currency is resolved once per bulk-export call, before the product pagination loop starts, by a private fetchDefaultCurrency(string $baseUrl, string $apiKey): ?string helper — not per product.

Resolution is a two-step lookup:

GET {base_url}/api/configurations?filter[name]=PS_CURRENCY_DEFAULT   → the default currency's numeric id
GET {base_url}/api/currencies/{id}                                    → that currency's iso_code, e.g. "EUR"

Unlike category resolution — where a failure throws IntegrationRequestException and aborts the whole export — a failure at either step of currency resolution is non-fatal: fetchDefaultCurrency() returns null, every product in the export gets currency: null, and the product sync proceeds normally. This is deliberate: currency is enrichment metadata, not core to any acceptance criterion, so a currency-resolution outage should not block product syncing the way a category-resolution outage does.

Pagination¶

Identical strategy to customers: an $offset starting at 0, incremented by PrestaShopIntegration::PER_PAGE (50) after each request, sent via limit=<offset>,<count>. The loop continues until a page returns fewer than PER_PAGE items. The categories fetch (above) uses the same pagination loop independently, before the products loop begins.

The parallel counterpart, fetchProductPageRange(), resolves $categoryNames and $currency once per job (see Per-job lookup prefetch above), then loops only the job's assigned $startPage..$endPage range using the same limit=<offset>,<count> request per page.

Delta sync via modifiedAfter¶

The integration filters client-side, reusing the same private wasModifiedAfter(array $item, CarbonImmutable $threshold, SourceDateTimes $source): bool helper used for customers — including the same resolveSourceTimezone() resolution described in Source timezone resolution above — it checks the date_upd field on each fetched product before mapping. As with customers, a delta sync still retrieves the entire product catalogue from PrestaShop page by page; modifiedAfter only reduces what gets mapped and forwarded, not what gets fetched.

Error handling¶

Any response for which $response->failed() is true (any non-2xx status) causes fetchProductBatches() — or fetchCategoryNames(), if the categories request itself fails — to throw IntegrationRequestException with the HTTP status code. A failure while fetching categories aborts before any request is made to /api/products.

Mapping: PrestaShop product → ProductData¶

Field mapping lives on PrestaShopTransformer::mapProduct(array $data, array $categoryNames, string $baseUrl, ?string $currency): ProductData (public static), called directly by PrestaShopIntegration from fetchProductBatches() with the pre-resolved $categoryNames lookup, the connection's $baseUrl, and the pre-resolved $currency (see Default currency resolution above) — it is not invoked through the TransformerContract::transform() interface.

originalPrice, targetGroup, and orderCount are not mapped — always null. tags is not populated either — it defaults to an empty array as defined by ProductData. See Fields deliberately excluded below for why.

url: non-rewritten link, not PrestaShop's friendly URL¶

PrestaShop supports "friendly URLs" via the link_rewrite field (e.g. /12-hummingbird-printed-t-shirt.html), but mapUrl() deliberately does not use it. Friendly-URL resolution depends on shop-specific rewrite configuration — whether it's enabled at all, whether categories are included in the path, the active URL-rewrite ruleset — none of which is reliably reproducible from the API response alone. The non-rewritten index.php?controller=product&id_product={id} format always resolves correctly regardless of shop configuration; this was verified against a live PrestaShop test store.

Fields deliberately excluded¶

These fields were investigated against a live PrestaShop test store's Webservice API and deliberately excluded, to save a future reader from re-investigating the same ground:

mapLocalizedValue(): PrestaShop's translatable-field shape¶

PrestaShop returns translatable fields — a product's name, a category's name — as an array of per-language entries, not a plain string: [{"id": 1, "value": "Hummingbird printed t-shirt"}, {"id": 2, "value": "T-shirt imprimé colibri"}, ...], one entry per shop language. PrestaShopTransformer::mapLocalizedValue(mixed $raw): string (public static) picks the entry with the lowest language id — the shop's default language — and returns its value. Used for product names, product descriptions, and category names. Returns an empty string if $raw is not an array or is empty.

Orders¶

Endpoint¶

GET {base_url}/api/orders

The response body is wrapped under an orders key — {"orders": [...]} — read the same way as customers and products, via $response->json('orders') ?? [].

One-time lookups resolved before the pagination loop¶

Order fields reference several other PrestaShop resources by numeric ID rather than inlining the resolved value. Following the same "resolve once, not per record" pattern used for product category names and the default currency (see Category name resolution above), three private helpers each run once per bulk-export call (or, on the parallel path, once per page-range job — see Per-job lookup prefetch above), before the order pagination loop starts:

Unlike currency resolution for products (each order carries its own id_currency, so orders can't share a single pre-resolved default the way products do), fetchCurrencies() builds a full id → ISO-code lookup covering every currency the shop has, resolved per order from that lookup.

Addresses are not in this one-time list — see Targeted address loading below.

Targeted address loading¶

Unlike Customers — where address mapping is explicitly deferred because addresses are a separate /api/addresses resource not inlined on the customer record — Orders does resolve real address data, since address resolution is in scope for this capability. It does so without a full scan of /api/addresses: for every fetched page of orders, a private collectAddressIds() helper collects the distinct id_address_invoice and id_address_delivery ids referenced by that page's orders (skipping missing or <= 0 ids), and a private fetchAddressesByIds() helper loads only those addresses:

GET {base_url}/api/addresses?output_format=JSON&display=full&filter[id]=[3|5|9]

filter[id] uses PrestaShop's OR filter syntax — a |-separated list of ids inside brackets. The id list is chunked at PrestaShopIntegration::PER_PAGE (50) ids per request via array_chunk(), so a page referencing more than 50 distinct addresses issues multiple /api/addresses requests. If no order on the page references any address, fetchAddressesByIds() is called with an empty id list and sends no request at all.

This replaced an earlier implementation that fetched the shop's entire /api/addresses collection once per export via fetchAddresses(), regardless of how many (if any) of those addresses were actually referenced by the exported orders.

Both the sequential path (fetchOrderBatches()) and the parallel page-range path (fetchOrderPageRange()) funnel through the same private emitOrderBatch() helper, which performs this per-page collect-then-fetch sequence before mapping the page to OrderData. Addresses are therefore fetched once per fetched page, not once per bulk-export call or once per job.

Pagination¶

Identical strategy to customers and products: an $offset starting at 0, incremented by PrestaShopIntegration::PER_PAGE (50) after each request, sent via limit=<offset>,<count>. The loop continues until a page returns fewer than PER_PAGE items. Each of the three one-time lookups above (order states, currencies, countries) uses the same pagination loop independently, before the orders loop begins. The address lookup is not part of this — it runs once per fetched page instead (see Targeted address loading above).

The parallel counterpart, fetchOrderPageRange(), resolves the three one-time lookups once per job, then loops only the job's assigned $startPage..$endPage range, performing the same per-page targeted address lookup for each page in that range.

Delta sync via modifiedAfter¶

The integration filters client-side, reusing the same private wasModifiedAfter(array $item, CarbonImmutable $threshold, SourceDateTimes $source): bool helper used for customers and products — including the same resolveSourceTimezone() resolution described in Source timezone resolution above — it checks the date_upd field on each fetched order before mapping. As with customers and products, a delta sync still retrieves the entire order list from PrestaShop page by page; modifiedAfter only reduces what gets mapped and forwarded, not what gets fetched.

Error handling¶

Any response for which $response->failed() is true (any non-2xx status) causes fetchOrderBatches() — or any of fetchOrderStateNames(), fetchCurrencies(), fetchCountryNames(), fetchAddressesByIds(), if that lookup's own request fails — to throw IntegrationRequestException with the HTTP status code. None of the order lookups are non-fatal (unlike default-currency resolution for products): a failure in any one of the three one-time lookups aborts before any request is made to /api/orders, and a failure in the per-page fetchAddressesByIds() call aborts the export after that page's /api/orders request has already succeeded, since addresses are resolved after the orders page is fetched, not before.

Mapping: PrestaShop order → OrderData¶

Field mapping lives on PrestaShopTransformer::mapOrder(array $data, array $orderStateNames, array $currencies, array $addresses): OrderData (public static), called directly by PrestaShopIntegration from fetchOrderBatches() with the four pre-resolved lookups — it is not invoked through the TransformerContract::transform() interface.

customerId (the Conflux-internal customer UUID) is never set — always null; only customerSourceId (the PrestaShop id) is populated. It is resolved later during persistence, the same way products resolve line items' productId — this is existing AbstractTransformer behaviour, not new for this capability. tags and customAttributes default to empty, same as the other entity DTOs.

Fields deliberately excluded¶

Line item mapping¶

PrestaShopTransformer::mapLineItem(array $row): LineItemData maps each entry of associations.order_rows[]:

total is computed, not read from a PrestaShop field: associations.order_rows[] has no per-row total field (total_price_tax_incl does not exist on this association — confirmed against a live PrestaShop store, see the verification note above). unit_price_tax_incl * product_quantity reproduces the row's tax-inclusive total.

productId and currency on the line item are never mapped — always null. Product-id resolution happens later, in AbstractTransformer::storeOrder(), by looking up the Product model via productSourceId — this is existing behaviour shared with other integrations, not new for this capability.

Address mapping: PrestaShopTransformer::mapAddress()¶

PrestaShopTransformer::mapAddress(array $data, array $countryNames): AddressData maps a raw PrestaShop address record to AddressData. It's used both by the one-time fetchAddresses() lookup and, transitively, for addressBilling/addressShipping on every mapped order.

region and email are deliberately excluded:

Consent (inbound webhook + pull)¶

PrestaShopIntegration implements both CanHandleWebhooks/HandlesWebhooks (processWebhook()) and CanPullConsent/PullsConsent (performPullConsent()) for consent. The webhook is only a trigger — it does not carry the consent state itself. On receipt, the integration re-fetches the customer's current state directly from PrestaShop's REST API via pullConsent(), then writes it through ConsentRecorder. This keeps the webhook payload contract minimal (just a customer id) and guarantees the webhook and the bulk-sync path always agree, since both go through the same newsletter mapping.

performPullConsent()¶

protected function performPullConsent(SystemConnection $connection, string $customerSourceId): ?ConsentData

GET {base_url}/api/customers/{customerSourceId} with output_format=JSON and the same display field list as bulk export (CUSTOMER_FIELDS, including newsletter). An explicit field list makes PrestaShop answer in the list endpoint's shape — {"customers": [{...}]} — even on the single-resource endpoint; the singular {"customer": {...}} key is read as a defensive fallback. The response is passed straight into PrestaShopTransformer::mapCustomer() and only the first ConsentData of the emitted records is returned — reusing the exact same mapping as the bulk-sync consent mapping above, so there is a single source of truth for interpreting PrestaShop's newsletter field.

The parse context comes from sourceDateTimesForSingleRecord(), which reads the zone the connection already stored rather than resolving PS_TIMEZONE again: a consent pull reads one customer and is usually driven by a webhook, so resolving would double the request count of every consent change a shop reports. A connection with no stored zone still resolves once.

• HTTP 404 → throws ConsentTargetNotFoundException (the contract's documented signal that the target system has no matching contact; see CanPullConsent). It carries ProvesIntegrationReachable, so it does not count towards opening the circuit breaker.
• Other failure statuses → throws IntegrationRequestException.
• No newsletter field, or no readable date_upd → returns null (same as the bulk-sync mapping: consentUpdatedAt is required, and a consent without one is omitted rather than written with a guess).

processWebhook()¶

Backs CanHandleWebhooks/HandlesWebhooks (see Webhook Receiver for the endpoint, signature validation, and dispatch pipeline that calls it). Handles a consent-change webhook sent by the separately maintained Positive Group PrestaShop module when a customer's newsletter opt-in changes.

{"customer_id": "<PrestaShop customer id>"}

What it does:

1. Validates the payload: throws IntegrationRequestException if customer_id is missing or not a scalar.
2. Looks up the Customer model scoped to system_connection_id + source_id (matching customer_id). If no matching customer exists, logs Discarding PrestaShop consent webhook: customer not yet known to Conflux. via Log::warning() (with system_connection_id and customer_source_id context) and returns — this is not an error: the webhook is simply not retried or escalated.
3. Calls $this->pullConsent($connection, $sourceId). If PrestaShop no longer has that customer (ConsentTargetNotFoundException), logs Discarding PrestaShop consent webhook: customer no longer exists in PrestaShop. (same context) and returns.
4. If a ConsentData came back, writes it via $this->consentRecorder->write($connection, $consent) (see Internal Consent Recorder), into the receiving connection's own mirror. The write moves the consent's content_changed_at when a value changed, so a change that arrives only by webhook is now delivered; before, it was stored but moved no signal. If pullConsent() returned null, nothing is written.

PrestaShopIntegration injects its own ConsentRecorder in its constructor rather than reading one off AbstractIntegration: it is the rare integration that persists a record outside a bulk import, so the base class stays free of a dependency the others never use.

Outbound path: writing consent back¶

PrestaShopOutboundWriter is the shop's registered outbound writer, registered for SystemDriver::PrestaShop in AppServiceProvider::registerOutboundWriters(). It carries customer_consents and nothing else: a consent rule into a PrestaShop connection delivers through it, onto the shop customer its anchor names (ADR-0042). The direction matrix lists customer_consents for PrestaShop as pull_in, push_in and push_out.

The write is a PATCH naming only the consent fields, because a PUT that omits a field sets it to NULL and a PUT that sends the resource back is refused over its read-only fields. It needs PrestaShop 8.0.1 or newer. On a withdrawal the shop keeps newsletter_date_add and ip_registration_newsletter, which document the original opt-in. PrestaShop stores subscribed or not, so a confirmed and an unconfirmed subscription both become 1.

accepts() comes from the AcceptsConsentChannels trait. It is true only for a customer_consents projection on a channel in supportedConsentChannels() (email) with a known subscribed. Anything else is recorded suppressed by the delivery layer, with no request and no budget token (see accepts()). performUpdate() keeps the same check as a second line, and refuses a projection of any other domain with OutboundWriteException.

Unit coverage is in tests/Unit/Integrations/PrestaShop/PrestaShopOutboundWriterTest.php: the PATCH body, the opt-in timestamp in the shop's zone and its omission where the zone cannot be established, the IP filter, a withdrawal leaving the opt-in record alone, the no-op and accepts() refusals for an SMS consent or an unknown subscription, a gone customer, and the circuit breaker.

Deletion Log¶

PrestaShopIntegration implements App\Contracts\HasDeletionLog and implements performFetchDeletionLog(SystemConnection $connection, SystemCapability $capability, ?string $since): Collection, the hook of the FetchesDeletionLog trait behind the sealed fetchDeletionLog(). See Integration Contract — Deletion log endpoint contract for the query parameters and response shape shared by every integration, and Deletion Log Sync for why this exists and how FetchDeletionLogJob consumes the returned entries.

The endpoint is provided by the conflux PrestaShop module (CFX-210, a separate plugin repo), which records deletions via actionObjectProductDeleteAfter/actionObjectOrderDeleteAfter/actionObjectCustomerDeleteAfter hooks into its own conflux_deletion_log table, and served through the module's own front controller rather than the Webservice REST API (CFX-230).

Endpoint¶

GET {module_url}/deletion-log

{module_url} comes from the same credentials.module_url value the widget token push uses, via the same private moduleUrl() helper. Authenticated the same way as the other webservice calls: HTTP Basic Auth using credentials.api_key — the module compares it against its own provisioned webservice key, not against PrestaShop's Webservice API permission system.

Response shape¶

deleted_at carries an explicit Z suffix (UTC) — the module formats it that way rather than PrestaShop's usual space-separated, offset-less datetime shape used elsewhere in the Webservice API.

Error handling¶

The module itself only returns a non-2xx status for a malformed entity_type/since (400) or a missing/invalid webservice key (401); neither should occur in practice, since PrestaShopIntegration always sends a valid entity_type, a well-formed ISO-8601 since, and the connection's own api_key.

Retention¶

The module prunes rows older than 90 days, throttled to at most once per day, piggybacked onto this endpoint's own requests (there's no PrestaShop-native scheduler). This is invisible to PrestaShopIntegration — it only affects how far back since = null (a first sync) can see.

PHPStan note¶

base_url is declared as string|null on SystemConnection. Before passing it to rtrim(), the integration casts it explicitly: (string) $connection->base_url. This satisfies PHPStan level 10 (the same pattern WooCommerceIntegration uses, per CFX-80).

Test coverage¶

Tests live in tests/Unit/Integrations/PrestaShop/PrestaShopIntegrationTest.php. All tests use Http::fake() to stub the HTTP layer — no database or network access.

verify tests

Source locale resolution tests (tests/Integration/Integrations/SourceLocaleResolutionTest.php, database-backed and shared with WooCommerceIntegration — see WooCommerce Integration — source locale resolution)

The one thing no mocked test can establish is whether a real shop's /api/languages/{id} resource actually carries locale or language_code — tests/Live/SourceLocaleResolutionLiveTest.php checks that against a running shop, alongside the same question for WooCommerce. Skipped unless configured and never run in CI; see Run the Live Tests Against a Real Shop.

Widget token push tests (tests/Integration/Integrations/PrestaShop/PrestaShopIntegrationTest.php — this tier because SystemConnection::factory()->create() persists to the database, unlike every other test in this file)

pullConsent tests (tests/Unit/Integrations/PrestaShop/PrestaShopIntegrationTest.php — Http::fake() only, no database)

handleWebhook (consent) tests (tests/Integration/Integrations/PrestaShop/PrestaShopIntegrationTest.php — this tier because assertions inspect persisted customer_consents rows)

fetchBulkExport (Customers) tests (exercised via requestBulkExport(), which drives fetchBulkExportBatches() → fetchCustomerBatches())

fetchBulkExport (Products) tests (exercised via requestBulkExport(), which drives fetchBulkExportBatches() → fetchProductBatches())

currency resolution failure is non-fatal tests (nested describe() within fetchBulkExport (Products))

fetchBulkExport (Orders) tests (exercised via requestBulkExport(), which drives fetchBulkExportBatches() → fetchOrderBatches())

probeBulkExport tests

fetchBulkExportPageRange tests

shop timezone handling tests

delta filter datetimes tests

source timezone resolution tests (tests/Integration/Integrations/PrestaShop/PrestaShopTimezoneResolutionTest.php, database-backed because the resolved zone is persisted)

fetchDeletionLog tests

source zone on the sequential path / source zone on the fan-out path tests (same file), the mirror-image pair that pins which parse context each of the six fetch methods builds

Field mapping for PrestaShopTransformer::mapCustomer() (including gender variants, date-of-birth edge cases, and the consent mapping newsletter: '1'/'0'/missing edge cases), PrestaShopTransformer::mapProduct() (including localized-name and localized-description resolution, status, sku, price, categories, image-URL, url, brandName, and currency edge cases), PrestaShopTransformer::mapOrder() (including status/currency lookup fallbacks, total/totalTax/totalShipping edge cases, address resolution, and line item mapping), and PrestaShopTransformer::mapAddress() (including country-lookup resolution and missing-field defaults) is covered separately in tests/Unit/Integrations/PrestaShop/PrestaShopTransformerTest.php.

Source files¶

See also¶

• Integration Contract reference — AbstractIntegration, VerificationResult, IntegrationContract, CanHandleWebhooks, ConsentRecorder, and all shared DTOs
• Integration Contract design — reasoning behind the verification and error-handling design
• Webhook Receiver reference — the inbound webhook endpoint, signature validation, and dispatch pipeline that calls processWebhook()
• Connection Flow — the plugin-initiated and tenant-initiated handshakes the widget token push distinguishes between
• Connection Widget — what the plugin-widget token is used for once the module receives it
• Implement a System Integration — step-by-step guide for adding a new integration
• Transformer Contract reference — AbstractTransformer, TransformerRegistry, and the unified Eloquent models
• Transformer Pipeline design — reasoning behind the transformation and storage design
• WooCommerce Integration reference — the other registered integration, including its own customer bulk-export implementation and its deletion log endpoint
• Deletion Log Sync — reasoning behind fetchDeletionLog()
• ADR-0018: the rule every source datetime follows, and why an unestablished zone is a failure rather than a fallback