Download the PHP package esign/laravel-shopify without Composer

Laravel Shopify

A modern Laravel package for building embedded Shopify apps using session tokens and Shopify Managed Installation. Built on top of the official shopify/shopify-app-php library.

Features

• Session Token Authentication - Modern token exchange flow (no OAuth callbacks needed)
• Shopify Managed Installation - Scopes managed entirely by Shopify CLI via shopify.app.toml
• Shop Model - Encrypted tokens, soft deletes, reinstallation support
• GraphQL Client - Type-safe queries/mutations with automatic token refresh, rate-limit (throttle) handling, and logging
• Webhook System - HMAC verification, job dispatch with queue routing, built-in GDPR handlers
• 8 Middleware Types - Embedded app, webhooks, App Proxy, UI extensions, Flow actions
• Configurable Routes - Move or disable any package route to avoid conflicts with your app
• Multi-Shop Ready - Single database, per-shop authentication

Requirements

• PHP 8.1+
• Laravel 11, 12, or 13
• Shopify CLI 3.x+ (for deployment)

Installation

1. Install via Composer

2. Publish Configuration & Migrations

This publishes:

• config/shopify.php - Main configuration
• database/migrations/ - Shops table
• resources/views/vendor/shopify/ - Blade templates (app.blade.php, auth-error.blade.php)

3. Configure Environment

Add to your .env:

Important: Do NOT set SHOPIFY_SCOPES in your .env file. Scopes are managed by Shopify CLI via your shopify.app.toml file.

When rotating your client secret, set the previous secret as SHOPIFY_OLD_API_SECRET — requests signed with either secret are accepted until the rotation completes, after which you can remove it.

4. Configure Shopify CLI (shopify.web.toml)

The Shopify CLI needs a shopify.web.toml next to your shopify.app.toml so shopify app dev knows how to serve your Laravel app:

• roles = ["frontend", "backend"] is required for embedded apps — without it the CLI won't proxy your app correctly.
• The CLI provides PORT and SERVER_PORT environment variables; Laravel's php artisan serve picks up SERVER_PORT automatically, so no port flag is needed.
• webhooks_path should match the package's webhook route (/webhooks/{topic}, see the Routes section if you changed the prefix).

How It Works

Shopify Managed Installation

This package uses Shopify Managed Installation, which means:

1. No OAuth Flow - Shopify handles the entire installation process
2. No Callback Routes - Your app doesn't need /auth/install or /auth/callback endpoints
3. Scopes in TOML - All scopes are defined in shopify.app.toml, not in your Laravel code
4. Session Tokens - App Bridge sends session tokens with every request
5. Token Exchange - Session tokens are exchanged for access tokens via Shopify's API

Authentication Flow

Routes

The package automatically registers these routes:

• GET /shopify/auth/token-refresh - Session token refresh bounce page (shopify.auth.token-refresh)
• GET /shopify/auth/error - Error handling (shopify.auth.error)
• GET / - Embedded app home, requires session token authentication (shopify.app.home)
• POST /webhooks/{topic} - Webhook handling (shopify.webhooks.handle)

There are no OAuth routes (/auth/install, /auth/callback) because Shopify manages installation automatically.

Overriding or disabling package routes

Every route can be relocated or disabled via the routes block in config/shopify.php — useful when your application already uses / for something else:

If you disable routes and register your own, point them at the package controllers and keep the route names intact — the token refresh redirect resolves route('shopify.auth.token-refresh') internally:

Scope Management

Important: Scopes Are Managed by Shopify CLI

This package does not manage scopes in Laravel. All scopes are defined in your shopify.app.toml file and managed by Shopify CLI.

How to Configure Scopes

1. Edit your shopify.app.toml file:

2. Deploy via Shopify CLI:

3. Updating Scopes:

When you change scopes in shopify.app.toml, merchants will be prompted to reapprove your app on their next visit. Shopify handles this automatically.

Common Scopes

Why No SHOPIFY_SCOPES Environment Variable?

In traditional OAuth flows, you'd set scopes in .env:

With Shopify Managed Installation:

• Scopes are only defined in shopify.app.toml
• Shopify CLI reads the TOML file during deployment
• Your Laravel app never needs to know what scopes are configured
• This prevents scope drift between your TOML and your code

Quick Start

A query/mutation is a small class implementing a contract with three methods: query() (the GraphQL string), variables() (the variables array), and mapFromResponse() (turn the response into whatever you want to return). mapFromResponse() receives a Shopify\App\Types\GQLResult; read the parsed payload from $response->data.

Creating a Query

Executing Queries

Creating a Mutation

userErrors (validation failures returned by Shopify) are detected automatically and thrown as a GraphQLUserErrorException.

Paginated Queries

A PaginatedQuery fetches every page for you. Track the cursor on the object: hasNextPage() reads the next cursor, and variables() sends it back on the next request.

Automatic retries

The client handles two failure modes for you:

• Expired access token - refreshed automatically, then the request is retried.
• Rate limiting - Shopify throttles GraphQL by query cost. In queue/console contexts the client waits for the cost bucket to refill and retries (tunable via shopify.rate_limiting); in a web request it throws GraphQLThrottledException immediately (carrying the throttle status) so a worker is never blocked.

DTOs and Input Objects

Typed Data Transfer Objects (DTOs), Input objects, and Enums for Shopify entities live in the optional companion package esign/shopify-data, built on Spatie Laravel Data. Its releases track Shopify Admin API versions (e.g. 2026.07.x for API 2026-07), so you can pin the release line matching the api_version your app uses:

Example: Using Input Objects in Mutations

Example: Mapping a query response to a DTO

All objects use camelCase naming, follow Shopify's GraphQL schema exactly (e.g., MailingAddress not Address, MoneyBag not Money), and can be extended in your app for store-specific needs. See the esign/shopify-data README for the full catalogue.

Webhooks

Webhooks are registered in your shopify.app.toml file and handled by Laravel jobs. The package includes built-in handlers for app lifecycle and GDPR compliance webhooks.

Built-in Webhook Handlers

These webhook jobs are included and pre-configured:

• app/uninstalled → AppUninstalledJob - Soft-deletes shop when app is uninstalled
• customers/data_request → CustomersDataRequestJob - GDPR data request (30-day response)
• customers/redact → CustomersRedactJob - GDPR data deletion (customer erasure)
• shop/redact → ShopRedactJob - Complete shop data deletion (48 hours after uninstall)

These handlers log events and provide placeholder methods for you to customize.

1. Register Webhooks in shopify.app.toml

Add webhooks to your shopify.app.toml file:

Important:

• Set api_version to match your app's API version (e.g., "2025-01")
• Deploy changes via shopify app deploy to register webhooks with Shopify
• URIs are relative to your app's root URL
• Learn more: https://shopify.dev/docs/api/webhooks

2. Map Webhooks to Laravel Jobs

The built-in GDPR and app lifecycle webhooks are already configured in config/shopify.php. The package will automatically dispatch these webhooks to their respective job classes.

3. Add Custom Webhook Handlers

Generate Webhook Job

Use the Artisan command to scaffold a new webhook job:

This creates app/Jobs/Shopify/OrdersCreateJob.php with boilerplate code.

Important: After generating the job, you must:

1. Register the webhook in your shopify.app.toml file
2. Add the job mapping to config/shopify.php

Register Webhook in Config

Add your custom webhook handlers to config/shopify.php:

4. Create Custom Webhook Job (Manual)

Events

The package dispatches Laravel events during the app lifecycle that you can listen to:

All events contain the Shop model and are dispatched synchronously (after the database operation succeeds).

Example: Listening to Events

GDPR Compliance

The three mandatory GDPR webhooks (customers/data_request, customers/redact, shop/redact) are pre-registered in config/shopify.php. The built-in jobs only log the request — the package cannot know what customer data your app stores, so you must implement the actual collection/deletion.

To do so, write your own job (see Add Custom Webhook Handlers) and point the config at it instead of the built-in one:

Your job receives public string $shopDomain and public array $webhookData in its constructor. For customers/data_request you have 30 days to return the data; for customers/redact delete the customer's PII.

For shop/redact (sent ~48h after uninstall) the built-in ShopRedactJob already permanently deletes the soft-deleted shop record, so you only need your own handler if you store additional shop data to erase.

Middleware

The package includes 8 middleware types for different Shopify surfaces:

All middleware automatically:

• Verify signatures (session tokens or HMAC) using the official shopify/shopify-app-php package
• Authenticate shops
• Load shop model into Auth::user()

Security Features:

• Webhook Verification: Validates HMAC signatures on webhook requests
• App Proxy Security: Validates HMAC signatures AND enforces 90-second timestamp windows to prevent replay attacks

Architecture

Design Principles

1. Shopify Managed Installation: Installation and scope management delegated to Shopify CLI
2. Session Token Authentication: Modern token exchange (no OAuth callbacks)
3. Offline Tokens by Default: Uses offline access tokens (never expire) for background operations
4. Soft Deletes: Shops are soft-deleted on uninstall for GDPR compliance and reinstallation support
5. Facade Pattern: All access via Shopify::query() - no direct client instantiation
6. Type Safety: GraphQL queries/mutations are typed via contracts
7. Queue Routing: Webhooks route to specific queues (e.g., GDPR on separate queue)

Advanced Usage

Shop Model

Logging

Control what gets logged in config/shopify.php:

Each toggle also has an env override (e.g. SHOPIFY_LOG_GRAPHQL_QUERIES=false).

Testing

Run the test suite:

Format the code with Pint:

License

This package is open-sourced software licensed under the MIT license.

Credits

• Built by Dynamate
• Powered by shopify/shopify-app-php