Shopware Sdk Laravel Package

Technical Evaluation

Architecture fit

• The package is a framework-agnostic PHP SDK, not a Laravel package. It ships no service provider, config file, facade, container bindings, queue integration, or publishable assets. Any Laravel integration is code we write ourselves (or adopt via the third-party Shape-and-Shift/shopware-laravel-sdk adapter, which is scoped to Laravel 8 — an EOL version). Plan for a thin internal wrapper package.
• It is a mirror of Shopware 6's DAL, not an opinionated abstraction. Developers must already understand Shopware concepts — Criteria, filters, associations, entity definitions, Context — to be productive. The value is typed entity/collection classes and OAuth handling, not simplification of the domain.
• Scope covered: Admin API (CRUD, search, sync, notification, user config, admin search), webhook registration/authentication, and PSR-7 action-button responses. Not covered: Storefront/Store API, Store-API sales channel auth, plugin-side (PHP plugin) work, and anything flagged TODO.
• The Context object is the unit of tenancy: one shop URL + token per context. Multi-shop means managing a context/token registry ourselves — there is no pool, tenant resolver, or connection manager.

Integration feasibility

• Low-friction install (composer require vin-sw/shopware-sdk, MIT, ext-curl, PHP ≥7.4). Guzzle-based, and the changelog references injecting "the same http client as the repository," so middleware/retry hooks are feasible — but we must wire them.
• Version/schema mapping is explicit and is the single most important compatibility lever: 2.x → Shopware ≥6.5 (with 2.2.0 adding 6.6.10.0 compatibility), 1.x → 6.4. 6.4 is effectively out of support; treat 1.x as a dead branch.
• Token lifecycle is our problem, not the SDK's. AdminAuthenticator::fetchAccessToken() returns a token; the README explicitly tells you to persist it yourself. There is no refresh scheduler, no expiry-aware caching, no lock to prevent thundering-herd re-auth across workers. This is a required piece of our build.
• Webhook authentication (WebhookAuthenticator::authenticatePostRequest($shopSecret)) is security-critical and lives in a 119-star, single-maintainer package. We should review that code path directly before trusting it in production.

Technical risk

• Supply chain / bus factor of one. 119 stars, 0 Packagist dependents, single maintainer with a personal email as the security contact. No org backing, no security policy beyond "email me," no evidence of a CVE process. This is the dominant risk, not code quality.
• Generated-code drift. Entity/collection classes track Shopware's DAL schema. Shopware ships frequently; a lagging SDK means missing properties, unhydrated extensions/custom fields, or silent partial data (cf. fixes for "Extensions not loaded into ProductEntity," "Missing associated entities," "custom definition not found"). Every Shopware upgrade becomes an SDK-upgrade dependency.
• Breaking-change cadence. 2.0.0 is a bare "Release 2.0.0" with no migration notes; 2.2.0 bundles behavior changes plus bug fixes. Minor bumps are not guaranteed to be drop-in.
• Historical defect signals worth noting: memory exhaustion on large result sets (#78, fixed 2.2.0), syncDeleted using the wrong HTTP client, version-delete broken, searchIds not throwing on error responses. These suggest edge-case coverage is thin — assume we are the QA for anything unusual.
• Package identity confusion: repo name, Packagist name (vin-sw/shopware-sdk), README badge (vin-sw/shopware-php-sdk), and namespace (Vin\ShopwareSdk) all differ. Trivial, but a signal of maturing-not-mature stewardship.

Key questions

1. Which Shopware versions are in scope today and over the next 18 months, and who owns the upgrade when Shopware ships a minor?
2. Do we need writes (sync, versioning, bulk mutations) or read-only search? Write paths carry most of the SDK's defect history.
3. What is our fallback if the maintainer stops publishing — fork and vendor under our namespace, or fall back to hand-rolled Guzzle calls against Admin API?
4. Is the Laravel 8 adapter acceptable, or do we build and own the service-provider wrapper?
5. Where does the shop secret and API credentials live — secrets manager, encrypted DB column, per-tenant?
6. Are we exposing webhook endpoints to the public internet, and what is the required 2xx latency and idempotency guarantee?

Integration Approach

Stack fit

• Fits a PHP 8.1+/Laravel stack cleanly at the language level. It does not fit idiomatically: no config/shopware.php, no Shopware facade, no Http:: client, no queued jobs, no events.
• Recommended shape: a first-party package of our own (e.g. acme/shopware) that (a) binds Context construction to a tenant registry, (b) owns a token cache with expiry and a distributed lock, (c) injects a Guzzle client configured with retry/backoff and structured logging, (d) exposes typed methods to the rest of the app so the SDK's classes never leak into controllers.
• Use Laravel's scheduler for token pre-warm, queue for anything that touches the network in a request cycle, and Http/Guzzle middleware for observability.

Migration path

• Start greenfield: pin ^2.4 (or the latest 2.x) with a committed composer.lock; do not float.
• If any legacy 6.4 shop exists, isolate it behind a separate 1.x-bound service — do not attempt to run both branches in one process.
• If we already have bespoke Admin API calls, migrate read paths first (they are lower-risk and easy to A/B against existing responses), then writes. Keep the bespoke client behind the same internal interface so cutover is a binding swap, not a rewrite.

Compatibility

• Hard prerequisites: PHP ≥7.4 (target 8.1+ anyway), ext-curl, Shopware ≥6.5.
• Validate the exact Shopware patch version in staging before each release; the SDK's compatibility claims are version-table-level, not per-patch guarantees.
• Confirm custom entities and app-provided extensions hydrate correctly in our schema — this is the most common failure surface in the changelog.

Sequencing

1. Spike: auth (client-credentials grant), InfoService call, one search on ProductDefinition — proves connectivity and token handling in under a day.
2. Build the internal wrapper: tenant registry, token cache + lock, retry middleware, error mapping.
3. Ship read-only search integration (pagination, Criteria builder helpers, response DTOs) behind a feature flag.
4. Add write paths (create/update/sync) with per-record error inspection — SyncService returns per-entity errors rather than throwing; we must parse and dead-letter.
5. Add webhook receiver last: signature verification, idempotency keys, enqueue-and-200 pattern.
6. Establish an upgrade runbook before go-live; assign an owner for Shopware-version tracking.

Operational Impact

Maintenance

• Two maintenance surfaces: the SDK itself and our wrapper. Budget roughly a sprint-day per Shopware minor release for regression testing plus SDK bump, and assume one breaking change per SDK major.
• Generated entity classes are not ours to patch — bug fixes require either upstream PRs or a vendored fork. Decide the fork policy up front; a fork also means we absorb schema regeneration.
• Single-maintainer risk is real: monitor releases, watch issues, and keep the wrapper thin enough that a fork-and-own decision costs days, not months.

Support

• No vendor SLA, no commercial support, community issues only. Our support burden is entirely internal: on-call must understand OAuth token expiry, Shopware 401 semantics, and sync error payloads.
• Security contact is a personal email — no coordinated disclosure path. We should treat authentication code as first-party-reviewed code.

Scaling

• Horizontal scaling is fine (stateless HTTP), but token contention is the first bottleneck: N workers each re-authenticating on cold cache will hammer the token endpoint. Mitigate with a shared cache and a mutex.
• Large result sets are a known hazard (#78 memory exhaustion). Enforce limit/pagination discipline in the wrapper; never pass an unbounded Criteria through.
• Multi-shop scale is linear in contexts — no connection pooling, no batching across shops. Bulk imports should go through SyncService batches with explicit chunk sizes, and throughput is bounded by the shop's own API capacity, not ours.

Failure modes to design for

• Token expired/revoked → 401 mid-job; needs refresh-and-retry-once, not a hard failure.
• ShopUnreachableException on network/DNS/timeouts → retry with backoff, then dead-letter; never block a user request on it.
• HTTP 200 with a per-entity error body (sync, and historically searchIds) → must be parsed and surfaced; silent success is the dangerous case.
• Partial schema mismatch after a Shopware upgrade → missing properties/custom fields appear as nulls, not errors; add contract tests asserting expected fields on key entities.
• Webhook storms and replay → enforce signature check, idempotency store, and fast 2xx with async processing.

Ramp-up

• Expect ~1–2 days for a PHP developer to be productive with the SDK's mechanics, but 1–2 weeks to be effective because fluency in Shopware's DAL (Criteria, filters, associations, inheritance, versioning) is the real prerequisite, and the SDK deliberately exposes it rather than hiding it.
• Mitigate by writing examples into our own docs (the upstream examples folder is the actual documentation) and by keeping a shared Criteria builder so engineers rarely touch raw DAL constructs.
• Net read: viable as an accelerator for a Laravel↔Shopware 6.5/6.6 integration, provided we budget for a first-party wrapper and accept single-maintainer supply-chain risk with an explicit fork fallback.