App Php Sdk Laravel Package

Technical Evaluation

Architecture fit

• shopware/app-php-sdk is a framework-agnostic toolkit for building the server side of a Shopware 6 app: signature verification, app registration/confirmation handshake, lifecycle event handling, webhook dispatch, Admin API client (OAuth client-credentials token handling), and payment/checkout endpoint contracts. In a Laravel context it is not a Laravel package — it is a domain library you host inside a Laravel application that acts as the app backend Shopware calls out to.
• Fit is strongest where we need to expose a public HTTPS surface to Shopware (registration, webhooks, custom endpoints, payment callbacks) rather than extend the storefront/administration directly. If requirements are purely storefront/plugin-side, this SDK is the wrong tool — a Shopware plugin (PHP/Symfony inside the platform) is the correct vehicle.
• It deliberately does not own persistence, routing, DI, or HTTP transport. That is a feature for us: we implement ShopRepositoryInterface on Eloquent, and route/middleware on Laravel primitives. It is also the main cost — every integration is glue code we own.

Integration feasibility

• Feasible on Laravel 10/11 with PHP 8.1+. The friction point is the PSR boundary: the SDK consumes Psr\Http\Message\ServerRequestInterface and returns ResponseInterface, while Laravel uses Symfony HttpFoundation. Plan for symfony/psr-http-message-bridge + a PSR-17 factory (e.g., nyholm/psr7) at the edge of a dedicated route group.
• Required build items: an Eloquent-backed shop repository (shop ID, shop URL, app secret, active/terminated state), a service provider binding the SDK's service interfaces, signed-request middleware keyed on the shopware-shop-signature header (HMAC-SHA256 of the raw body with the shop secret), and controllers for registration/confirmation, webhooks, and any payment/checkout verbs.
• No official Laravel adapter and no service provider ship with the SDK. Treat that as ~3–5 engineer-days of integration scaffolding before any business logic, and keep the glue in one thin Shopware/ module rather than scattered across controllers.
• Verify the release/version matrix early. The stated last-release date (2026-09-21) is anomalous relative to today and should be treated as unverified metadata until confirmed against Packagist/GitHub tags.

Technical risk

• Ecosystem coupling (high): the SDK is only useful if Shopware 6 is a committed sales/distribution channel. It is a one-way door into Shopware's app lifecycle semantics (registration replay, shop secrets, lifecycle events, shopware-app-signature rules).
• Maturity (medium-high): 16 stars implies a very small external user base. The de facto supported path in the ecosystem is the Symfony shopware/app-bundle; the framework-agnostic SDK is the lower-traffic sibling. Public examples, Stack Overflow answers, and community bug reports for Laravel wiring will be scarce.
• API churn (medium): Shopware 6 minor releases periodically change header/signature expectations, lifecycle payloads, and Admin API behavior. Pin the SDK version and track the Shopware 6.5 → 6.6 → 6.7 support matrix explicitly.
• Security surface (medium): the app holds per-shop secrets and Admin API credentials, and must verify every inbound request. Misconfigured middleware is a direct privilege-escalation path into merchant stores — this needs a security review, not just code review.
• Data quality (unknown): repository URL is missing and the star/score/release signals are weak. Do not baseline a roadmap on this score; validate the actual repository activity before committing.

Key questions

• Which Shopware versions must we support (6.4 EOL, 6.5, 6.6, 6.7), and is the target self-hosted, cloud, or both?
• Do we need payment/checkout endpoints (highest compliance and reliability bar) or only lifecycle + webhooks + Admin API reads/writes?
• Who owns the public registration URL and TLS endpoint, and does our hosting satisfy Shopware's reachability and latency expectations?
• Where do per-shop secrets live — database, KMS, or secret manager — and what is the rotation story?
• Is there an appetite for maintaining custom Laravel glue long-term, or should we instead consider the Symfony bundle in a separate service to stay on the supported path?
• What is the fallback if the SDK stalls — vendor a fork, or reimplement signature/registration/webhook handling directly against the documented HTTP contract (a few hundred lines)?

Integration Approach

Stack fit

• Laravel 10/11 + PHP 8.1/8.2, MySQL/Postgres for shop persistence, Redis for token and rate-limit caches, Horizon/queues for webhook and outbound API work.
• Mount the SDK behind a single Route::prefix('shopware') group excluded from session/CSRF, with one middleware doing signature verification and shop resolution, and one thin controller layer translating PSR-7 ↔ Laravel responses.
• Bind SDK interfaces (ShopRepositoryInterface, HTTP client factories, context resolver) in a dedicated ShopwareServiceProvider. Nothing else in the app should import SDK namespaces, keeping blast radius small on upgrades.

Migration path

• Greenfield app: scaffold the module first, wire a fake shop fixture, and prove signature verification + registration in a local harness before touching business features.
• Existing Laravel product: introduce as an additive module with its own route group, tables (shopware_shops, shopware_webhook_events), and queue connection. No changes to existing auth, session, or tenancy models — Shopware shops are a separate principal type and must not be conflated with our users.
• If we already run a Symfony service for Shopware, prefer consolidating on shopware/app-bundle there rather than running two integration styles.

Compatibility

• Pin exact SDK, nyholm/psr7, and bridge versions in composer.json; add a CI job that runs the signature and registration contract tests against a recorded fixture set.
• Confirm PSR-7/17/18 interface versions do not conflict with Laravel's Symfony HTTP stack; run composer why-not checks before any framework upgrade.
• Maintain a support matrix table (Shopware version × SDK version × PHP version) in the repo README; revisit at every Shopware minor release.

Sequencing

1. Spike (3–5 days): install SDK, implement in-memory shop repository, verify signature middleware against a captured request, prove a PSR-7 round trip in Laravel.
2. Registration lifecycle: manifest, registration/confirmation endpoint, secret persistence, activate/deactivate/delete handling, re-registration idempotency.
3. Admin API client: token acquisition/caching per shop, retry/backoff, 401 re-auth path.
4. Webhooks: verify, persist raw payload, enqueue, process idempotently, expose a replay tool.
5. Business endpoints (custom endpoints, then payment/checkout if in scope) with contract tests per Shopware version.
6. Hardening: observability, per-shop rate limiting, secret rotation runbook, load test on webhook burst.

Operational Impact

Maintenance

• Ongoing cost is dominated by our glue, not the SDK: middleware, repository, token cache, queue consumers. Budget roughly 10–15% of one engineer per quarter for Shopware-version tracking plus incident follow-up; more if payment endpoints are in scope.
• SDK upgrades are small but non-zero; treat them as routine dependency bumps gated by the contract test suite. Watch for breaking changes around signature headers and lifecycle payload shapes across Shopware minors.

Support

• MIT license, no commercial SLA, small community. Support channels are Shopware docs, GitHub issues, and Shopware Community Slack. Internal ownership must be explicit — a named engineer accountable for the Shopware surface.
• Mitigation for bus factor: keep the integration thin and documented such that reimplementation against Shopware's published HTTP contract is a viable 1–2 week fallback.

Scaling

• Inbound surface is stateless HTTP; scale horizontally behind the load balancer with no sticky sessions. The real constraints are outbound: Shopware Admin API rate limits and per-shop token issuance.
• Cache OAuth tokens per shop in Redis with expiry-minus-skew; single-flight token refresh to avoid stampedes when many webhooks arrive for the same shop concurrently.
• Webhook bursts (bulk product/order events) should be absorbed by the queue, not processed inline. Size workers against peak event rate, and apply per-shop concurrency caps so one large merchant cannot starve others.
• Persist raw webhook payloads before processing — storage is cheap, and it is the only reliable way to replay after a consumer bug.

Failure modes

• Signature mismatch: wrong/rotated app secret, proxy rewriting the body (ngrok, some WAFs, gzip middleware), or body parsed before HMAC. Verify against the raw request body and add an alert on mismatch rate.
• Registration replay / duplicate shops: non-idempotent handlers create duplicate shop records and orphaned secrets. Enforce a unique constraint on shop ID and make lifecycle handlers idempotent.
• Token expiry storms: concurrent 401s triggering parallel re-auth. Single-flight refresh plus bounded retries.
• Shopware API 429/5xx: exponential backoff with jitter and a dead-letter queue; never block an inbound webhook on an outbound call.
• Webhook loss: Shopware retries are finite. Without our own replay tooling and idempotency keys, events are silently lost.
• Secret leakage: per-shop secrets in logs or error trackers is a merchant-impacting breach. Redact at the SDK boundary and audit log sinks.
• Local/dev divergence: signature verification disabled "temporarily" in non-prod and never re-enabled. Gate it behind config with a startup assertion.

Ramp-up

• A mid-level Laravel engineer unfamiliar with Shopware needs roughly 1–2 sprints to be productive: ~2 days on Shopware 6 app concepts (manifest, registration, lifecycle, signing), ~3 days on the SDK's interfaces, ~3–5 days building the first end-to-end registration + webhook slice.
• Add ~3 days for Admin API and token handling, and a full sprint if payment/checkout endpoints are in scope given the compliance and reliability bar.
• Requisite reading: Shopware app manifest and signing docs, the SDK's RegistrationService/WebhookHandler/SignatureService sources, and the Symfony bundle's implementation as a reference architecture (even though we are not using it).
• Recommend one engineer owns the module end-to-end through the first production merchant, then hand off with a written runbook covering rotation, replay, and version upgrades.

Recommendation: proceed only if Shopware 6 is a confirmed distribution channel and we accept owning Laravel glue indefinitely. Start with the 3–5 day spike in step 1 and gate further investment on a clean signature + registration round trip against a real Shopware instance. If the spike exposes friction or the repository activity cannot be verified, the fallback — implementing Shopware's documented signing/registration/webhook contract directly, without the SDK — is small enough that lock-in risk is manageable.