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 error 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
• Multi-Shop Ready - Single database, per-shop authentication

Requirements

• PHP 8.1+
• Laravel 11+ or 12+
• 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, token-refresh.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.

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
• GET /shopify/auth/error - Error handling
• GET / - Embedded app home (requires session token authentication)

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

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

Creating a Query

Executing Queries

Creating a Mutation

Paginated Queries

DTOs and Input Objects

This package provides a comprehensive set of Data Transfer Objects (DTOs) and Input objects for working with Shopify entities. All classes are built using Spatie Laravel Data for type safety, validation, and extensibility.

Available Objects

The package includes DTOs and Input objects for common Shopify entities:

Main DTOs - Represent core Shopify resources like Orders, Customers, Products, Metafields, Metaobjects, and Fulfillments. These include all relevant fields and nested objects.

Supporting DTOs - Represent commonly used nested objects such as MailingAddress, MoneyBag, MoneyV2, Weight, LineItem, ShippingLine, TaxLine, DiscountAllocation, and ProductVariant.

Input Objects - Used in GraphQL mutations to create or update Shopify resources. Includes Input objects for Orders, Customers, Products, Metafields, Metaobjects, Fulfillments, and their supporting types.

All objects follow Shopify's GraphQL schema naming conventions exactly (e.g., MailingAddress not Address, MoneyBag not Money) and use camelCase for properties.

Extensibility

All DTOs and Input objects are designed to be extended and overwritten in your Shopify apps. This allows you to:

• Add custom properties for store-specific needs
• Override methods for custom transformations
• Maintain compatibility with the base package while adding app-specific logic

Example: Extending OrderDto

Example: Using Input Objects in Mutations

All objects use camelCase naming and follow Shopify's GraphQL schema exactly (e.g., MailingAddress not Address, MoneyBag not Money).

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

Schedule cleanup of uninstalled shops:

Or run manually:

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:

Testing

Run the test suite:

Run code style checks:

License

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

Credits

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