Download the PHP package shopgpt/shopify-integration without Composer

On this page you can find all versions of the php package shopgpt/shopify-integration. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package shopify-integration

Shopify Integration for Laravel

Multi-tenant Shopify authentication for Laravel apps — embedded and standalone.

Design rule: the package authenticates Shopify. It never touches your users, guards or sessions. It stores the store and its tokens, fires an event, and gets out of the way.


Contents


Build status

Built — OAuth install and callback (HMAC, state), expiring offline tokens with refresh, the storage contracts and the shipped Eloquent repository, session token verification and token exchange for embedded apps, webhook receipt with dedupe and the six shipped topics, the Admin API client (GraphQL and REST), and the events, exceptions and facade around all of it.

Planned — webhook registration with Shopify (webhooks:sync), Artisan commands, $api->paginate() and REST call-limit headers, ShopifyIntegration::fake() and model factories.

154 tests, 355 assertions, green on Laravel 10.50, 11.56 and 12.68.


Requirements

Package PHP Laravel
0.6.x ^8.1 10.x, 11.x, 12.x

Requires a cache store (OAuth state) and a queue worker (webhook handling). Any driver works.


Installation

The service provider is auto-discovered. Config lands at config/shopifyIntegration.php.

No migration runs on its own. The package owns no table. If your app has nowhere to put a store yet, publish the starter one:

Its columns are exactly the defaults the package assumes, so an app that runs it needs no configuration beyond credentials. If you already store integrations, skip it and map your columns instead — see Storage.

In your Partner dashboard set the App URL to https://your-app.com/shopify/auth/begin and the redirect URL to https://your-app.com/shopify/auth/callback.


Configuration

Every key in config/shopifyIntegration.php. Nine of them read from the environment; the rest are edited in the config file.

Key Env var Default What it does
client_id SHOPIFY_CLIENT_ID — Your app's API key
client_secret SHOPIFY_CLIENT_SECRET — Signs and verifies everything
api_version SHOPIFY_API_VERSION 2025-07 Admin API version used for every call
scopes SHOPIFY_SCOPES write_products Comma-separated. Changing this forces re-auth
debug SHOPIFY_DEBUG false Skips HMAC verification on the OAuth routes. Local only
embedded.enabled SHOPIFY_EMBEDDED false Runs inside the Shopify Admin iframe
store.repository — EloquentStoreRepository::class Every read and write. Override to own the INSERT
store.model — Integration::class The Eloquent model the default repository uses
store.table SHOPIFY_STORE_TABLE integrations Only used by the shipped default model
store.columns — [] Logical field => your column name. See Storage
store.platform — shopify Written to, and scoped by, the platform column when mapped
store.encrypt_tokens SHOPIFY_ENCRYPT_TOKENS false Encrypt tokens at rest. Off: your model may already
store.pii — 4 fields Logical fields a shop/redact clears
oauth.state_ttl — 300 Seconds a pending install stays valid
oauth.hmac_ttl — 300 Seconds a signed Shopify request stays acceptable. 0 checks the signature only
oauth.listing_url SHOPIFY_LISTING_URL null Where to send someone who hits the install URL with no shop
routes.prefix — shopify URL prefix for the package's routes
routes.middleware — ['web'] Applied to the OAuth routes
routes.webhook_middleware — ['api'] Applied to the webhook route
webhooks.topics — 6 topics Topic => job class. See Webhooks
webhooks.queue SHOPIFY_WEBHOOK_QUEUE default Queue webhook jobs are pushed to
webhooks.log_channel SHOPIFY_WEBHOOK_LOG null Log channel for webhook activity
redirects.after_install — / Route name, URL, or closure. Ignored when embedded
redirects.after_reinstall — / Same, for a store that had uninstalled
redirects.on_failure — / Same, when OAuth fails

Everything without an env var is edited in config/shopifyIntegration.php directly. Add your own env keys there if you want them environment-driven:


Storage: the table is yours

The package registers no migration, prescribes no columns, and never assumes what a store row looks like beyond six facts it cannot work without. Everything it reads or writes goes through two interfaces.

There is a starter table if you want one — vendor:publish --tag=shopifyIntegration-migrations — but it is published into your app, not loaded from the package, and nothing below depends on it.

ShopifyStore — one connected store, as the package needs to read it:

ShopifyStoreRepository — every read and write, including the INSERT.

The short version

Add the trait to the model you already have, and tell the package what your columns are called:

Anything you omit defaults to its own name. Map a field to null and the package stops writing it — the value still reaches your listeners on the events, it just is not persisted. Only store_domain and access_token are genuinely required.

Your migration, your column names, your indexes, your encryption.

When the INSERT needs something the package cannot know

A store table often has a column Shopify has no opinion about — an owning user, a tenant, a plan — and it is often NOT NULL. The package fires StoreInstalled after the row is written, which is too late to fill one.

The repository is the seam. Extend the shipped one and override a single method:

newStore() runs before anything is saved, with the full shop.json in hand, so a required column stays required. Nothing else about the package changes: token refresh, the API client, the middleware and the webhook handlers all keep working, because they talk to the interfaces rather than to columns.

For total control — a different ORM, a remote service, an existing service layer — implement ShopifyStoreRepository yourself and bind it.

Fields the package will use if you give it a column

platform, external_id, store_domain, access_token, refresh_token, token_expires_at, scopes, installed_at, uninstalled_at — and, for the profile promoted out of shop.json: domain, name, email, shop_owner, phone, currency, country_code, country_name, primary_locale, plan_name, weight_unit, password_enabled, shop_data, shop_data_synced_at.

Two are worth knowing about:

Token encryption

Off by default, because storage is your business and a model that already casts its token column would otherwise be encrypted twice. Turn it on only when nothing else is:


Quick start — embedded app

1. Set SHOPIFY_EMBEDDED=true. A completed install then hands the browser back to Shopify (admin.shopify.com/store/…/apps/…), which loads the App URL from your Partner dashboard inside the admin frame — set that App URL to the route in step 3.

2. Load App Bridge first in your host view:

3. Protect your routes:

4. Send the session token from the front end:

5. Call the API as that store:


Quick start — standalone app

1. Leave SHOPIFY_EMBEDDED=false and set your redirects:

2. Send merchants to the install URL:

3. Create or log in your user from the install event:

The user itself is resolved in your repository, not here — the row is already written by the time this event fires, so a NOT NULL user_id has to be filled before it:

4. Guard your routes:


Routes

Registered under routes.prefix (default shopify), always. Change the prefix and the middleware; the paths themselves are fixed, because the redirect URI the package hands Shopify is built from them.

Method URI Name
GET /shopify/auth/begin shopifyIntegration.auth.begin
GET /shopify/auth/callback shopifyIntegration.auth.callback
POST /shopify/webhooks shopifyIntegration.webhooks

begin verifies a signature when there is one. Shopify signs the requests it sends, and those are checked — wrong signature, or one older than oauth.hmac_ttl, is a 401. A merchant arriving from a "connect your store" button on your own site carries no signature and cannot invent one, so an unsigned request is admitted: this route only redirects to Shopify's own authorize page, where the merchant still has to log in and approve.

callback always requires one. That is where the install is actually granted, and the signature, the single-use state and the code exchange all have to line up.


Middleware

Alias Use on
shopifyIntegration.embedded Page loads inside the admin iframe
shopifyIntegration.session API requests carrying a session token
shopifyIntegration.installed Standalone routes needing a working store
shopifyIntegration.hmac Your own routes Shopify signs

All three store-resolving middleware resolve the store into ShopifyIntegration::currentStore(), which is how your route reads it without a second lookup. None of them touch Auth::user() — stack your own after them if you want a Laravel user resolved:

The package ships no user() relation — it does not know your User model, and the store model is yours anyway. Put the relation where it belongs:

Filling user_id on a new install is the repository's job, not the model's — see Storage.

What shopifyIntegration.session answers with

Status Body What the client should do
401 {"error": "session_token_missing"} Attach a token
401 {"error": "session_token_invalid"} Mint a fresh token, retry once
403 {"error": "reauthorization_required", "url": "…"} Break out of the frame to url

Session tokens live about a minute, so a 401 is routine. A 403 means the app has no usable install behind the token and retrying will not help.

shopifyIntegration.embedded sets Content-Security-Policy: frame-ancestors for the merchant's admin and clears X-Frame-Options, so a global X-Frame-Options elsewhere in your stack will not blank the app.


The facade

Method Returns Notes
currentStore() ?ShopifyStore The store the middleware resolved for this request
stores() ShopifyStoreRepository Every read and write
forDomain(string) ?ShopifyStore Look a store up by acme.myshopify.com
api(ShopifyStore) ApiClient Token guaranteed fresh. Works without the trait
ensureFreshToken(ShopifyStore) ShopifyStore Refreshes if near expiry
refreshToken(ShopifyStore) ShopifyStore Forces a refresh
verifySessionToken(?string) ?array Claims, or null if invalid
storeFromClaims(?array) ?string The shop domain a claims array names
exchangeToken(string, string) ?ShopifyStore Session token → stored access token
installUrl(string) string For a "connect your store" button
redirectUri() string The callback URL, for your Partner dashboard
sessionTokenHeaders(…) array Test support
webhookHeaders(…) array Test support

The store model

Lookups and writes go through the repository, not through a model static — the model is yours, and the package cannot put methods on it.

Method Returns
$stores->findByDomain($domain) ?ShopifyStore
$stores->findByExternalId($id) ?ShopifyStore
$stores->findByKey($key) ?ShopifyStore
$stores->persistInstall($existing, $shop, $token, $shopData) ShopifyStore The INSERT seam
$stores->updateTokens($store, $token) ShopifyStore
$stores->updateProfile($store, $shopData) array{changed, previous}
$stores->updateScopes($store, $scopes) ShopifyStore
$stores->markUninstalled($store) void Drops the credentials too
$stores->redact($store) void Clears the mapped PII fields

State questions work on any ShopifyStore, wherever it is stored:

A model using InteractsWithShopifyStore gets those as methods, plus an installed() query scope and $store->api() with the token guaranteed fresh:

Read the six facts through the contract when you want to be storage-agnostic — in a listener that any app might wire up, say:

Everything else — $store->plan_name, your relations, your accessors — is your model's own business, exactly as it was before.


Calling the Admin API

$store->api() returns a client bound to that store, with the token refreshed first. You never pass a token or a domain.

All five return an Illuminate\Http\Client\Response.

GraphQL cost is read from extensions.cost.throttleStatus after each response; when the bucket drops below 20% the client waits for it to refill, capped at 5 seconds.


Errors

Status Exception Store flagged uninstalled
401 StoreUninstalledException Yes — also fires StoreUninstalled
402 StoreUnavailableException (isFrozen()) No — unpaid, comes back
423 StoreUnavailableException (isLocked()) No — locked by Shopify
429 RateLimitedException ($e->retryAfter) No
other ShopifyApiException No

Every one of them carries $e->store. ShopifyApiException and its subclasses also carry $e->body.

TokenRefreshException is thrown when a refresh fails and the stored token has already expired. A failed refresh on a still-valid token is not fatal.


Events

The extension point. Everything your app does beyond Shopify itself hangs off these.

Event Fired when Carries
OAuthStarted An install begins $shop
OAuthFailed HMAC, state or exchange failed $shop, $reason, $exception
StoreInstalled A store the app had never seen authorised $store, $context
StoreReinstalled A previously uninstalled store came back $store, $context
StoreTokenExchanged An access token came from a session token $store
StoreTokenRefreshed A token was refreshed $store
TokenRefreshFailed A refresh failed $store, $reason, $fatal
StoreScopesUpdated app/scopes_update arrived $store, $previous, $current
StoreProfileUpdated shop/update refreshed the profile $store, $changed, $previousPlan, $currentPlan
StoreRenamed The myshopify domain changed $store, $previousDomain, $currentDomain
StoreUninstalled The webhook or a 401 said so $store

Three of them carry a helper worth knowing about:

$context is an InstallContext:

isDevelopmentStore() matters for billing — a dev store cannot be charged live. Anything else from shop.json is in $context->shopData and profile().


Webhooks

The endpoint is POST /shopify/webhooks. Point Shopify at it, then map topics to jobs in config:

Those six ship with the package. The three GDPR topics are mandatory for public apps and the shipped handlers are enough to pass review.

app/scopes_update matters more than it looks. Under Shopify managed installation the merchant approves a scope change inside the admin and your app is never called, so without this webhook the stored scopes go stale: hasRequiredScopes() keeps reporting a shortfall the merchant has already fixed, and you send them back through an authorisation they do not need.

Upgrading from 0.2? webhooks.topics lives in the config you published, so this topic will not appear there on its own. Add the line by hand, and subscribe to the topic in shopify.app.toml.

Writing a handler

Extend WebhookJob:

The job carries the whole payload by default. Trim it for high-volume topics:

A busy store can repeat a large resource payload every few seconds, so a job that re-fetches the resource anyway should carry only the id. The GDPR topics need the full payload, which is why keeping it is the default.

handle() is called through the container, so type-hint anything you need — including ShopifyStoreRepository when the handler has to write to the store.

Webhook registration with Shopify is not built yet — declare your topics in shopify.app.toml:


What you can change

Everything here is meant to be overridden from your app.

To change Do this
Where a merchant lands after install redirects.after_install — route name, URL, or closure receiving the InstallContext
What happens on install Listen for StoreInstalled / StoreReinstalled
Use your own store table store.columns + store.model — see Storage
Fill a required column on install Override newStore() on EloquentStoreRepository
Replace storage entirely Implement ShopifyStoreRepository and bind it
Handle a new webhook topic Add topic => YourJob::class to webhooks.topics
Replace a shipped webhook handler Point that topic at your own job class
What travels the queue for a topic Override payloadForQueue() on your job
Change the URL prefix routes.prefix
Add middleware to the OAuth routes routes.middleware
Where an unknown visitor goes oauth.listing_url

The package deliberately has no opinion about users, guards, sessions, billing, onboarding — or your schema. If you need one of those, listen for an event or implement the repository.


Testing

The package mints valid session tokens and webhook signatures so you never hand-roll a JWT or an HMAC:

Override claims to test your own edge cases:

For webhooks:

Both are checked against the package's own verification in its test suite.

Fake Shopify itself with Http::fake() against https://{shop}/admin/api/*. ShopifyIntegration::fake() and model factories are planned.


Security


Versioning

Semver. 0.x while the API settles — require it as ^0.6.

0.6.0

A starter table, for an app that has none. 0.5.0 removed the migration because the package was dictating a schema to apps that already had one. That was right, but it left a new app with nothing to install into and a config block to fill in before its first OAuth callback would work.

So the table is back, on different terms: published, never loaded. It is not registered with the migrator, so it cannot collide with a table you already run — you opt in, the file becomes yours, and you edit it like any other migration.

Added

Removed

Public surface with no caller in the package and no test covering it, plus options that only had one correct value. Most were unused, so nothing that works today stops working — but they were API, so they are listed:

Fixed

Unchanged

Nothing about the storage contracts moved. ShopifyStore, ShopifyStoreRepository, ColumnMap and store.columns work exactly as they did in 0.5.0 — an app that mapped its own table keeps working and should not publish this.

0.5.0

The package no longer owns a table. It shipped a migration and a fixed set of integration_-prefixed columns; both are gone. Storage is now defined by two interfaces, and the shipped Eloquent repository is a default you can replace.

This is the change that lets an app keep a NOT NULL owning column — a user_id, a tenant — on its store table. The package writes the row through your repository, so newStore() runs before the INSERT with the whole shop.json in hand.

Breaking

Added

0.4.0

Six fixes in the OAuth path, three of which change behaviour you may be relying on.

Breaking

Fixed

Added

Security

0.3.0

Added the app/scopes_update topic and four events. Nothing breaks, but a config you published earlier will not have the new topic — add it by hand, and subscribe to it in shopify.app.toml.

0.2.0

Renamed oauth.skip_hmac_in_debug to a plain top-level debug key. If you published the config before then, move the value across; the old key is no longer read.

Repo: github.com/ghazniali95/shopify-integration · Composer: shopgpt/shopify-integration (the vendor prefix does not have to match the GitHub account; Packagist reads the name from composer.json).


All versions of shopify-integration with dependencies

PHP Build Version
Package Version
Requires php Version ^8.1
illuminate/support Version ^10.0|^11.0|^12.0
illuminate/database Version ^10.0|^11.0|^12.0
illuminate/http Version ^10.0|^11.0|^12.0
guzzlehttp/guzzle Version ^7.5
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package shopgpt/shopify-integration contains the following files

Loading the files please wait ...