PrestaShop Integration¶

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

Class¶

Namespace: App\Integrations\PrestaShop\PrestaShopIntegration Extends: App\Services\AbstractIntegration

Connectivity Verification¶

PrestaShopIntegration implements performVerification(SystemConnection $connection): VerificationResult, which is called by the sealed AbstractIntegration::verify() method. 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 AbstractIntegration::verify() catches and converts to a failed VerificationResult.
5. On success, resolves the first shop ID from the response (shops.0.id) as the external user identifier; falls back to the literal string 'unknown' if the field is missing or non-scalar.

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

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.

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 ISO-8601 string; when set, the integration parses it into a Carbon threshold and, for every fetched page, discards any record whose date_upd is not strictly after that threshold — via a private wasModifiedAfter(array $item, Carbon $threshold, ?string $shopTimezone): bool helper (Carbon::parse($dateUpd, $shopTimezone)->greaterThan($threshold)) — before mapping the page to CustomerData and handing it to $onBatch. When modifiedAfter is null (a first full sync), no filtering is applied, every fetched record is forwarded, and the shop timezone is never resolved — see Shop timezone resolution below.

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.

Shop timezone resolution¶

PrestaShop's webservice returns date_upd in shop-local time with no UTC offset (e.g. 2024-06-01 03:00:00), while 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.

A private fetchShopTimezone(string $baseUrl, string $apiKey): ?string helper 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 is called only when modifiedAfter is set — a full export never issues this request — and, like the other lookups, once per bulk-export call on the sequential path or once per page-range job on the parallel path (see Per-job lookup prefetch above). Resolution failures — a failed response, a missing value, or a value that isn't a valid PHP timezone identifier — are non-fatal: fetchShopTimezone() returns null, and wasModifiedAfter() falls back to Carbon::parse($dateUpd, null), i.e. the app timezone (UTC) — the previous, timezone-naive behaviour.

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.

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, Carbon $threshold, ?string $shopTimezone): bool helper used for customers — including the same fetchShopTimezone() resolution described in Shop timezone resolution above — it checks the raw 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, Carbon $threshold, ?string $shopTimezone): bool helper used for customers and products — including the same fetchShopTimezone() resolution described in Shop timezone resolution above — it checks the raw 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:

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

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

Field mapping for PrestaShopTransformer::mapCustomer() (including gender variants and date-of-birth 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, and all shared DTOs
• Integration Contract design — reasoning behind the verification and error-handling design
• 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