WooCommerce Integration¶

Reference for App\Integrations\WooCommerce\WooCommerceIntegration. Covers the connectivity verification contract, the HTTP endpoint it targets, the three possible outcomes, and the test coverage for each.

Class¶

Namespace: App\Integrations\WooCommerce\WooCommerceIntegration Extends: App\Services\AbstractIntegration

Connectivity Verification¶

WooCommerceIntegration 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 connection_token from the connection's encrypted credentials array.
2. Strips any trailing /wp-json/… path from base_url to derive $storeBase.
3. POSTs to {storeBase}/wp-json/{brandName}-connector/v1/connectivity-check with connection_token and connection_id in the request body.
4. Returns a VerificationResult based on the HTTP response status.

Endpoint¶

POST {storeBase}/wp-json/{brandName}-connector/v1/connectivity-check

brand_name credential (CFX-230). conflux-connector ships as branded builds — the same plugin renamed per brand (conflux, rapidmail, user-platform, …), each registering its REST routes under its own namespace (see CONFLUX_BRAND_SLUG in brands/*.php and RestApi::NAMESPACE/AUTH_NAMESPACE) so differently-branded installs never collide on the same route. The plugin reports its slug as a plain-text brand_name credential at registration time (ConfluxApi::connect()); a private brandName(SystemConnection $connection): string helper reads credentials.brand_name and falls back to 'conflux' when it's missing or non-string — so connections paired before the plugin reported this credential keep working unchanged. The same brand_name key is used by the conflux PrestaShop module for its own branded routes — see PrestaShop Integration reference.

Request body

Outcomes¶

VerificationResult shape¶

Namespace: App\Data\VerificationResult

Source locale resolution¶

performVerification() calls the public resolveSourceLocale(SystemConnection $connection): ?string right after the connectivity check succeeds — but only for a connection that already has a row (RemembersSourceLocale::shouldResolveSourceLocale()). WooCommerce publishes no locale of its own — the setting belongs to WordPress, and the one place the WooCommerce REST API exposes it is the system status report:

GET {storeBase}/wp-json/wc/v3/system_status

Authenticated with the store's own consumer_key/consumer_secret, the same credentials Bulk Export uses. The resolved value is environment.language (e.g. de_DE), remembered on system_connections.source_locale by the shared App\Services\Concerns\RemembersSourceLocale trait: a value that looks like a locale (a language tag, optionally with region and further subtags — de, de_DE, fr-FR) is stored; anything else — an empty string, a non-string, a body mistaken for one — leaves the previously stored value standing rather than clearing it, and the trait returns whichever value ends up in force. A transient (not yet persisted) connection is never written to: the value is set on the model and returned, so a caller reading the attribute sees it, but nothing persists it, which is why verification skips the lookup for one entirely. Registration verifies such a connection before deciding whether to insert a row and then saves a different instance, so the answer would be discarded — and this is the store's slowest endpoint, paid inside a synchronous API request on every registration attempt and retry. The locale is established on the finalizing verification instead, which runs against the persisted row long before anything delivers to it.

This is also the single most expensive read WooCommerce's REST API offers — it collects the plugin inventory and runs environment checks, and takes seconds on a large store — which is why it is capped at WooCommerceIntegration::SYSTEM_STATUS_TIMEOUT_SECONDS (10 seconds) and asked once per verification rather than once per sync run. Nothing in a bulk-export run reads the locale; it exists purely as the last fallback UserPlatformOutboundWriter uses to normalise a customer's phone number to E.164, after the customer's own billing and shipping addresses. A shop changes its language about as rarely as it changes its address, so resolving it at verification time rather than per run costs nothing a delivery would notice.

Best effort in every direction, because the locale is a fallback for one field of one writer, not something a sync depends on:

• A network error (ConnectionException, including a timeout past the 10-second cap) or a failed HTTP response leaves the connection's stored source_locale untouched and returns it unchanged.
• A value that is not a locale is also left alone, per the trait's rule above.
• None of this can fail verification: resolveSourceLocale() never throws in a way performVerification() propagates, and VerificationResult::success() is returned regardless of what the locale lookup did.

Bulk Export¶

WooCommerceIntegration implements fetchBulkExportBatches(), the ExportsInBulk hook behind the sealed requestBulkExport()/streamBulkExport(). Supported capabilities: SystemCapability::Customers, SystemCapability::Orders, and SystemCapability::Products. The endpointAndMapper() method is exhaustive — all three capabilities are handled and there is no fall-through branch.

Capability dispatch¶

The private endpointAndMapper() helper maps a capability to its WC REST endpoint and item mapper:

Credentials¶

Bulk export authenticates via HTTP Basic Auth using WooCommerce REST API keys read from the connection's encrypted credentials array:

credentials.brand_name is a third, non-secret credential — this build's brand identifier (falls back to 'conflux' if absent) — extracted by a private brandName(SystemConnection $connection): string helper and used to derive the branded REST namespaces for the connectivity-check and deletion log endpoints. Bulk export never reads it — /wp-json/wc/v3/… is WooCommerce's own unbranded namespace.

Delta sync (modified_after)¶

When ExportRequest::$modifiedAfter is set, the integration appends two query parameters to every request made by performProbeBulkExport, fetchBulkExportBatches and performFetchBulkExportPageRange: modified_after and dates_are_gmt=true. The cursor arrives as a CarbonImmutable and deltaFilterParams() renders it with toIso8601String(), which is the only place it becomes a string, so a UTC cursor goes out as 2024-06-01T07:08:09+00:00. The WooCommerce REST API filters results server-side so that only records modified later than the supplied timestamp are returned. When modifiedAfter is null both parameters are omitted and all records are returned (full sync).

Both come from the private deltaFilterParams() helper, which is the only place either is built. The three call sites differ only in page and per_page and spread the helper's result, so a site cannot send the cursor without the flag.

Why dates_are_gmt is sent¶

dates_are_gmt decides which database column WooCommerce compares the cursor against. WC_REST_CRUD_Controller::prepare_objects_query() turns modified_after into a date_query whose column is post_modified when the flag is absent and post_modified_gmt when it is set, and the parameter is registered with 'default' => false. So the flag is not a formatting hint: it selects the column.

The cursor is SyncBatch::started_at, one of Conflux's own UTC instants. Without the flag WooCommerce resolves that instant against the shop-local column, which on a shop five hours behind UTC means asking for records modified after a moment five hours later than intended. Every change inside that window is skipped, the cursor advances past it anyway, and the records reappear only when a full sync runs.

Nothing surfaces that. The response is a valid, smaller page rather than an error, so removing the flag breaks no test that does not assert on it and produces no failure in production. The tests in delta filter params assert the flag on all three call sites, and that a full run carries no date parameter at all.

The value is the literal string 'true', one of the four values WordPress's rest_is_boolean() accepts over the wire, so the query string reads dates_are_gmt=true rather than depending on a PHP boolean rendering as 1.

The cursor is supplied by BulkSyncJob — the integration never reads or writes it directly. See Delta Sync for the cursor derivation rules.

Pagination¶

All three endpoints share the same pagination contract. The integration passes page (integer, starts at 1) and per_page (50) as query parameters, reads the X-WP-TotalPages response header to determine the total number of pages, and iterates until all pages are fetched. If the header is absent or empty it defaults to 1 page.

Error handling¶

Any non-2xx response causes fetchBulkExportBatches()/performProbeBulkExport()/performFetchBulkExportPageRange() to throw IntegrationRequestException with the HTTP status code. AbstractIntegration's sealed wrapper methods pass this through unchanged; any other Throwable is wrapped in InvalidIntegrationResponseException.

Datetime fields¶

WooCommerce sends a _gmt variant of every datetime field alongside a shop-local one. The integration reads the _gmt variant throughout, which is why WooCommerceIntegration::SOURCE_TIMEZONE is the constant 'UTC': that is the zone of the strings Conflux reads, not the zone the shop is in, so no per-connection lookup is needed. DATETIME_FORMAT is 'Y-m-d\TH:i:s', because WooCommerce writes a literal T separator and no offset. The table covers every datetime the integration reads, across the bulk export and the deletion log, so no field is discarded by accident. See ADR-0018 for the rule this table applies.

All six read and unread fields appear in the resource's *_MAPPED_KEYS list, so none of them falls into customAttributes. The two dropped keys are excluded by DROPPED_ORDER_KEYS as well, which is what makes the drop a stated decision rather than the silent by-product of a mapper that never reads them.

Order and product meta_data is not passed through: it is excluded from ORDER_MAPPED_KEYS' output as a mapped key, and on products it is a non-scalar value that the attribute loop skips. Only mapCustomer() walks meta_data entries.

Mapping: WooCommerce order → OrderData¶

WooCommerceTransformer::mapOrder() is a public static method (callable via first-class callable syntax as the mapper closure).

Unmapped scalar top-level fields (e.g. discount_total, payment_method) are captured as customAttributes. Fields in ORDER_MAPPED_KEYS, the two keys in DROPPED_ORDER_KEYS, and non-scalar values are excluded.

Mapping: WooCommerce line item → LineItemData¶

Each entry in the line_items array is mapped by the private mapLineItem() method and collected into OrderData::lineItems.

Mapping: WooCommerce customer → CustomerData¶

Field mapping lives on WooCommerceTransformer::mapCustomer() (public static), called directly by WooCommerceIntegration from each of the three fetch hooks above — it is not invoked through the TransformerContract::transform() interface.

Unmapped scalar top-level fields and meta_data entries with scalar values are captured as customAttributes. meta_data entries whose values are arrays or objects are silently skipped. The consent key is the one exception: it is mapped to a ConsentData and deliberately excluded from customAttributes, so it does not also land in the customer's external_data.

Mapping: WooCommerce product → ProductData¶

Status mapping¶

Unmapped scalar top-level fields (e.g. weight, stock_quantity, featured) are captured as customAttributes. Fields in PRODUCT_MAPPED_KEYS and non-scalar values are excluded.

Deletion Log¶

WooCommerceIntegration 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.

Endpoint¶

GET {storeBase}/wp-json/wc-{brandName}/v1/deletion-log

Namespaced wc-{brandName}/v1 — not {brandName}-connector/v1 like the connectivity-check endpoint — deliberately, so the route falls under WooCommerce's own REST Basic Auth recognition (routes namespaced wc-* get authenticated with a WooCommerce API key pair automatically; see WC_REST_Authentication::is_request_to_rest_api()). {brandName} is resolved the same way as the connectivity-check endpoint's, via the same private brandName() helper reading credentials.brand_name (CFX-230) — an earlier implementation hit a hardcoded wc-conflux/v1, which would have 404'd once conflux-connector actually branded its namespaces per install. Authenticated the same way as bulk export: HTTP Basic Auth using credentials.consumer_key/consumer_secret.

Consent¶

WooCommerce has no native consent field. The only consent a store can express is the newsletter opt-in the conflux-connector plugin records as WordPress user meta, exposed on the WC REST customer object's meta_data. That key is the contract between plugin and platform — the reasoning, and what changing it would cost, is recorded in ADR-0026.

Expected shape on any customer payload:

{
  "id": 42,
  "date_modified_gmt": "2024-06-01T12:00:00",
  "meta_data": [
    { "id": 10, "key": "conflux_newsletter", "value": "1" }
  ]
}

Mapping: newsletter meta → ConsentData¶

WooCommerceTransformer::mapConsent() (public static) is the single interpreter of the field, used by both inbound paths below.

Return values:

Inbound paths¶

WooCommerceIntegration implements CanPullConsent via PullsConsent, so pullConsent() runs through the circuit breaker like every other outbound call. Its outcomes:

Persisting is not the integration's job: mapCustomerRecords() emits [CustomerData, ConsentData] and AbstractTransformer::store() hands the ConsentData to ConsentRecorder::write(), which owns the upsert on (system_connection_id, source_id). The consent moves its own change signal, and only when a value changes: every customer edit re-reads the meta and moves date_modified_gmt, which moves consentUpdatedAt and nothing else. There is no ordering across writers any more; the WooCommerce mirror has one writer, its own connection (ADR-0041).

Outbound path: writing consent back¶

WooCommerceOutboundWriter is the store's registered outbound writer, registered for SystemDriver::WooCommerce in AppServiceProvider::registerOutboundWriters(). It carries customer_consents and nothing else: a consent rule into a WooCommerce connection (for example the return rule that brings a Positive User withdrawal back to the shop) delivers through it, onto the store customer its anchor names (ADR-0042). The direction matrix lists customer_consents for WooCommerce as pull_in and push_out.

It extends AbstractOutboundWriter and writes the same meta key the read path interprets — so a write and the next pull cannot disagree about where consent lives. The connection is a per-call argument, not constructor state, so one writer instance serves every WooCommerce target.

It declares one verb. The other three are not refused at runtime, they are simply not on the class: a caller narrowing to CanCreateRemoteRecords, CanDeactivateRemoteRecords or CanDeleteRemoteRecords never reaches this writer at all — see Capability interfaces.

The verb is POST, not the PUT the WooCommerce REST docs show. WordPress dispatches POST, PUT and PATCH on an editable route to the same handler, so WooCommerce cannot tell them apart — but the layers in front of it can, and PUT and PATCH are the ones a hardened host, a WAF rule or a stock nginx rewrite drops. The local WooCommerce box is an example rather than an exception: its nginx rewrites /wp-json/ onto the directory index, where PUT and PATCH get a 405 from nginx and never reach PHP.

The request names one meta key and nothing else. WooCommerce merges meta_data entry by entry, so the store's own customer fields are left untouched — and a REST customer update advances date_modified_gmt, which is the timestamp the state comes back on as consentUpdatedAt, the one a two-way conflict between mirrors is settled by.

The flag is written as '1'/'0' rather than a JSON boolean: WordPress stores meta as a string either way, and those are the values mapConsent() parses back. WooCommerce 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()). An absent signal is not a withdrawal, in this direction either. performUpdate() keeps the same check as a second line, and refuses a projection of any other domain with OutboundWriteException.

Writing the meta moves date_modified_gmt. The next pull reads the same value back, so the mirror's change signal does not move and nothing is delivered again (ADR-0043).

Outcomes follow the outbound contract rather than the read path's exception types:

AbstractOutboundWriter::write() supplies the circuit breaker and the outbound span around the call, so the writer itself contains neither.

The delivery pipeline that calls it is described in Outbound Delivery.

Declared channels¶

public function supportedConsentChannels(): array
{
    return [ConsentChannel::Email];
}

One checkbox is one channel. A propagator pushing consent outward uses this to skip channels the store cannot represent — see HasConsentChannels.

PHPStan note¶

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

Test coverage¶

Tests live in tests/Unit/Integrations/WooCommerce/WooCommerceIntegrationTest.php and tests/Unit/Integrations/WooCommerce/WooCommerceTransformerTest.php. All unit tests use Http::fake() to stub the HTTP layer — no database or network access. The consent path additionally has database-backed coverage in tests/Integration/Integrations/WooCommerce/WooCommerceTransformerTest.php, which drives a real WC customer payload through mapCustomer() and transform() and asserts the resulting customer_consents row.

The outbound write has its own unit coverage in tests/Unit/Integrations/WooCommerce/WooCommerceOutboundWriterTest.php: the request shape (one meta key and nothing else), the '1'/'0' round trip through mapConsent()'s own parser, the no-op for a channel the store cannot express, accepts() for an email consent, an SMS consent, an unknown subscription and a foreign domain, the three verbs the class does not declare, a gone customer surfacing as RemoteRecordGoneException without counting against the breaker, and the breaker opening on repeated failures.

One thing no mocked test can establish is whether a real store exposes the conflux_newsletter meta on its customer payload in the first place — tests/Live/WooCommerceLiveConsentTest.php checks exactly that against a running store. tests/Live/WooCommerceLiveConsentWriteTest.php covers the write direction: that the store actually persists the key rather than dropping it as protected meta, that the update advances date_modified_gmt, and that the written flag is the one mapConsent() reads back. Both are skipped unless configured and never run in CI; see Live Smoke Tests.

performVerification tests

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

The one thing no mocked test can establish is whether a real store's system status report actually carries a value at environment.language — tests/Live/SourceLocaleResolutionLiveTest.php checks that against a running store, alongside the same question for PrestaShop. Skipped unless configured and never run in CI; see Run the Live Tests Against a Real Shop.

probeBulkExport tests

fetchBulkExport tests (exercised via requestBulkExport(), which drives fetchBulkExportBatches())

probeBulkExport — Products tests

fetchBulkExport — Products tests

probeBulkExport — Orders tests

fetchBulkExport — Orders tests

delta filter params tests

WooCommerceTransformer::mapOrder tests

WooCommerceTransformer::mapProduct tests

fetchDeletionLog tests

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
• PrestaShop Integration reference — the other registered integration, including its own customer bulk-export implementation
• Deletion Log Sync — reasoning behind fetchDeletionLog() and how FetchDeletionLogJob consumes it
• ADR-0018: the rule every source datetime follows, and why the _gmt variant is the one read