Download the PHP package amadulhaque/shopify-bridge without Composer

Amadulhaque Laravel Shopify

A framework-style Shopify integration for Laravel. It owns Shopify protocol work—OAuth, Admin GraphQL, webhook subscriptions, and HMAC verification—while the host application owns shops, users, tokens, persistence, tenancy, and authorization.

It has no models, migrations, database access, sessions, queues, cache stores, Redis dependency, authentication guards, or storage implementation.

Contents

• Install
• Configure
• Bind application contracts
• OAuth install flow
• GraphQL usage
• Middleware
• Webhooks
• Events
• Testing

Install

Install the package from Packagist:

Laravel discovers ShopifyServiceProvider automatically. Publish the configuration only when you need to customize it:

For this repository's local development package, Composer already uses packages/Shopify as a path repository, so no additional install command is needed.

Configure

Set these values in the host application's .env:

Add the same complete callback URL to your Shopify app's allowed redirection URLs. The published config/shopify.php configures API version, scopes, retries, timeout, and a replaceable HTTP client. It does not configure storage.

OAuth state data

Pass optional state data as third redirect() or authorizationUrl() argument. Package sends only an opaque random state token to Shopify, stores your data through OAuthStateRepository, then returns it as $result->state after valid callback. Do not JSON-encode or URL-encode state yourself.

Bind application contracts

OAuth state uses package cache repository by default. Set SHOPIFY_STATE_CACHE_STORE=redis or file (or omit it to use Laravel CACHE_STORE). Bind your own OAuthStateRepository only when custom state storage is needed. Bind your own implementations for tokens, shop resolution, webhook definitions, and application authorization.

OAuthStateRepository::put() receives optional state data. pull() must return it and consume state once. TokenRepository::findFor(Shop $shop) must return AccessToken|null. The package never calls a save, create, or update method on a repository.

Optional application authorization

Bind AuthorizationResolver when your application needs to decide whether its current caller may access a resolved shop. It can use Laravel Auth, a JWT, an API key, or any custom tenant system. If it is not bound, shopify.auth only verifies that a shop and Shopify token resolve.

OAuth install flow

The package does not register routes because URL structure is an application decision. Define your own routes:

Example controller. ShopifyInstallationStore below is an application service; define it however your product stores installations.

exchange() returns an immutable OAuthResult with Shop and AccessToken; it never persists either value.

Providing and validating an existing access token

For an already-installed shop, pass its domain and token directly. The token is used only for that call chain and is never persisted by this package.

GraphQL usage

GraphQL resolves the access token from TokenRepository, so callers only provide a shop.

Mutations use the same fluent API:

When you have a token at call time, pass it as the second graph() argument instead of implementing TokenRepository:

GraphqlResponse preserves Shopify data and errors. Transport failures throw ShopifyHttpException. A GraphQL throttle response throws GraphqlThrottled; queue jobs should release using $exception->retryAfterSeconds rather than immediately retrying.

To replace Laravel's HTTP client, bind Amadulhaque\Shopify\Contracts\HttpClient to your adapter. This is where applications can add tracing, circuit breaking, distributed rate limiting, or custom retry behavior.

Middleware

The package provides three aliases:

• shopify.shop: resolves a Shop via ShopResolver and attaches it as shopify.shop.
• shopify.auth: resolves the shop, requires a token from TokenRepository, and optionally invokes AuthorizationResolver.
• shopify.webhook: verifies Shopify's HMAC and attaches a typed Webhook as shopify.webhook.

An authenticated Laravel route can combine normal application auth with Shopify authorization without coupling the package to a User model:

Webhooks

Provide the desired subscriptions from your application's WebhookRepository, then manage subscriptions through GraphQL:

All application-webhook operations can receive a direct access token as their final argument. all() retrieves every page; sync() uses it too, so it detects stale subscriptions beyond Shopify's first 250 results.

sync(..., true) is explicitly opt-in because deleting a remote subscription can affect another component that manages the same store.

Webhook handling stays thin:

Events

Listen in the host application for package events:

Available events: ShopInstalled, AccessTokenUpdated, WebhookReceived, WebhookVerified, and ShopUninstalled.

Testing

Bind in-memory implementations of the contracts and fake Shopify HTTP requests:

The package test suite covers OAuth exchange, token resolution, GraphQL requests, middleware aliases, HMAC rejection and verification, webhook events, the facade, and webhook registration. Run it with:

Public API