Laravel Shopify App

https://github.com/kyon147/laravel-shopify
Admin
A full-featured Laravel package that provides comprehensive tools and utilities for developing...
Tokens:90,495
Snippets:709
Trust Score:8.5
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### ShopifyController example

Source: https://github.com/kyon147/laravel-shopify/wiki/Usage

Example controller that retrieves the authenticated shop, gets its domain and API data, and logs the results.

```php
<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Log;

class ShopifyController extends Controller
{
    public function index() {
        $shop = Auth::user();
        $domain = $shop->getDomain()->toNative();
        $shopApi = $shop->api()->rest('GET', '/admin/shop.json')['body']['shop'];

        Log::info("Shop {$domain}'s object:" . json_encode($shop));
        Log::info("Shop {$domain}'s API objct:" . json_encode($shopApi));
        return;
    }
}

?>
```

--------------------------------

### Complete User model example

Source: https://github.com/kyon147/laravel-shopify/wiki/Installation

A complete example of the User model after adding the required imports, implementing IShopModel, and using the ShopModel trait.

```php
<?php

namespace App;

use Illuminate\Notifications\Notifiable;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Osiset\ShopifyApp\Contracts\ShopModel as IShopModel;
use Osiset\ShopifyApp\Traits\ShopModel;

class User extends Authenticatable implements IShopModel
{
    use Notifiable;
    use ShopModel;

    /**
     * The attributes that are mass assignable.
     *
     * @var array
     */
    protected $fillable = [
        'name', 'email', 'password',
    ];

    /**
     * The attributes that should be hidden for arrays.
     *
     * @var array
     */
    protected $hidden = [
        'password', 'remember_token',
    ];
}
```

--------------------------------

### REST and GraphQL API call example

Source: https://github.com/kyon147/laravel-shopify/wiki/Usage

Example of making a REST request to get shop info and a commented GraphQL alternative.

```php
$shop = Auth::user();
$request = $shop->api()->rest('GET', '/admin/shop.json');
// $request = $shop->api()->graph('{ shop { name } }');
echo $request['body']['shop']['name'];
```

--------------------------------

### Example: Create AfterAuthenticateJob

Source: https://github.com/kyon147/laravel-shopify/wiki/After-Authentication-Job

Example command to create a job named AfterAuthenticateJob.

```bash
php artisan make:job AfterAuthenticateJob
```

--------------------------------

### Install package with Composer

Source: https://github.com/kyon147/laravel-shopify/blob/master/README.md

Run this command to install the package via Composer. This is the first step in setting up the Laravel Shopify App package.

```bash
composer require kyon147/laravel-shopify
```

--------------------------------

### CSP frame-ancestors header example

Source: https://github.com/kyon147/laravel-shopify/wiki/Installation

Example response header for an embedded app when the shop 'shopify-dev.myshopify.com' installs it. The frame-ancestors directive must be different for every shop and must be present in any routes that render HTML content.

```bash
Content-Security-Policy: frame-ancestors https://shopify-dev.myshopify.com https://admin.shopify.com;
```

--------------------------------

### Remove old package and install kyon147/laravel-shopify

Source: https://github.com/kyon147/laravel-shopify/wiki/Installation

Remove the original package before installing the new one. Run these commands in order in your Laravel project root.

```bash
composer remove osiset/laravel-shopify
```

```bash
composer require kyon147/laravel-shopify
```

--------------------------------

### Accessing Shop's plan charge

Source: https://github.com/kyon147/laravel-shopify/wiki/Usage

Example of retrieving a shop's plan charge using the ChargeHelper service.

```php
use Osiset\ShopifyApp\Services\ChargeHelper;

$shop = Auth::user();
$chargeHelper = app()->make(ChargeHelper::class);
$charge = $chargeHelper->chargeForPlan($shop->plan->getId(), $shop);
$chargeApi = $chargeHelper->useCharge($charge->getReference())->retrieve($shop);
```

--------------------------------

### REST API call with parameters

Source: https://github.com/kyon147/laravel-shopify/wiki/Usage

Example of making a REST request with query parameters to search customers.

```php
$shop = Auth::user();
$request = $shop->api()->rest('GET', '/admin/api/customers/search.json', ['query' => "phone:{$phone}"]);
echo $request['body']['customers'];
```

--------------------------------

### Create a Listener for PlanActivatedEvent

Source: https://github.com/kyon147/laravel-shopify/wiki/Event-Listener-System

Example listener that sends an email to the store owner when a plan is activated.

```APIDOC
## Create a Listener for PlanActivatedEvent

### Description
This listener handles the PlanActivatedEvent and sends an email to the store owner with the plan details.

### Listener Class
```php
<?php

namespace App\Listeners;

use Illuminate\Bus\Queueable;
use App\Mail\PlanActivatedMail;
use Illuminate\Support\Facades\Mail;
use Illuminate\Contracts\Queue\ShouldQueue;
use Osiset\ShopifyApp\Messaging\Events\PlanActivatedEvent;

class SendPlanActivatedEmailListener implements ShouldQueue
{
    use Queueable;
    /**
     * Create the event listener.
     *
     * @return void
     */
    protected Shop $shop;

    public function __construct()
    {
        $this->onQueue('default');
    }

    /**
     * Handle the event.
     *
     * @param  object  $event
     * @return void
     */
    public function handle(PlanActivatedEvent $event)
    {
        Mail::to($event->shop->email)
            ->send(new PlanActivatedMail($event->plan, $event->chargeId));
    }
}
```

### Parameters
- **$event** (PlanActivatedEvent) - The event instance containing the shop, plan, and chargeId.

### Return Value
- void

### Usage
Register this listener in the event map as shown in the next snippet.
```

--------------------------------

### Install Laravel Boost guidelines with php artsian boost:update

Source: https://github.com/kyon147/laravel-shopify/wiki/Upgrading

Run this command to install the Laravel Boost guidelines in your project for the agent(s) of your choice. This is part of the upgrade from v26.0.0 to v26.1.0.

```bash
php artsian boost:update
```

--------------------------------

### Insert a recurring plan with usage charges

Source: https://github.com/kyon147/laravel-shopify/wiki/Creating-a-Billable-App

SQL to insert a recurring 'Demo' plan for $5.00 with 7 trial days, presented on install, and capable of issuing usage charges up to $10.00. The plan uses a 30-day interval and test mode is disabled.

```sql
# Create a recurring "Demo" plan for $5.00, with 7 trial days, which will be presented on install to the shop and have the ability to issue usage charges to a maximum of $10.00
INSERT INTO plans (`type`,`name`,`price`,`interval`,`capped_amount`,`terms`,`trial_days`,`test`,`on_install`,`created_at`,`updated_at`) VALUES
('RECURRING','Test Plan',5.00,'EVERY_30_DAYS',10.00,'Test terms',7,FALSE,1,NULL,NULL);
```

--------------------------------

### package.json for Shopify CLI

Source: https://github.com/kyon147/laravel-shopify/wiki/How-to-create-App-Extension

Defines the Node project and scripts for the Shopify CLI. Run npm install, then use npm run shopify, npm run info, npm run scaffold extension, and npm run deploy.

```json
{
  "name": "APP NAME HERE WITHOUT SPACE, REPLACE SPACE WITH hyphen ", // my-app
  "private": true,
  "license": "UNLICENSED",
  "scripts": {
    "shopify": "shopify",
    "build": "shopify app build",
    "dev": "shopify app dev",
    "info": "shopify app info",
    "scaffold": "shopify app scaffold",
    "deploy": "shopify app deploy"
  },
  "dependencies": {
    "@shopify/app": "^3",
    "@shopify/cli": "^3"
  }
}
```

--------------------------------

### Publish Shopify config file

Source: https://github.com/kyon147/laravel-shopify/blob/master/README.md

Run this Artisan command to publish the package's configuration file. This is required after installation to customize the package settings.

```bash
php artisan vendor:publish --tag=shopify-config
```

--------------------------------

### Example ShopRedactJob implementation

Source: https://github.com/kyon147/laravel-shopify/wiki/GDPR

Example Laravel job class for handling the shop/redact webhook. It receives the shop domain and webhook data, then deletes the corresponding user record. Errors are logged via Log::error.

```php
<?php namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Queue\SerializesModels;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use App\User;
use Osiset\ShopifyApp\Objects\Values\ShopDomain;

class ShopRedactJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    /**
     * Shop's myshopify domain
     *
     * @var ShopDomain
     */
    public $shopDomain;

    /**
     * The webhook data
     *
     * @var object
     */
    public $data;

    /**
     * Create a new job instance.
     *
     * @param ShopDomain $shopDomain The shop's myshopify domain
     * @param object     $webhook    The webhook data (JSON decoded)
     *
     * @return self
     */
    public function __construct(ShopDomain $shopDomain, object $data)
    {
        $this->shopDomain = $shopDomain;
        $this->data = $data;
    }

    /**
     * Execute the job.
     *
     * @return void
     */
    public function handle()
    {
        try {
            $shop = User::where('name', $this->shopDomain->toNative())->first();
            $shop->delete();
            return;
        } catch(\Exception $e) {
            Log::error($e->getMessage());
        }
    }
}
```

--------------------------------

### REST API POST with payload

Source: https://github.com/kyon147/laravel-shopify/wiki/Usage

Example of making a POST request with a payload to create a customer.

```php
$shop = Auth::user();
$request = $shop->api()->rest('POST', '/admin/api/customers/customer.json', ['customer' => "phone:{$phone}"]);
echo $request['body']['customers'];
```

--------------------------------

### Use HomeController trait

Source: https://github.com/kyon147/laravel-shopify/wiki/Upgrade-guide-v10.x-to--v11.x

Use the HomeController trait in your HomeController to get the default behavior.

```php
use Osiset\ShopifyApp\Traits\HomeController as HomeControllerTrait;

class HomeController extends Controller
{
    use HomeControllerTrait;

    ...

}
```

--------------------------------

### Set Shopify redirect_uri

Source: https://github.com/kyon147/laravel-shopify/wiki/Installation

Set this as the redirect_uri in your Shopify Partner dashboard. It must start with https, otherwise you will get the error: "Oauth error invalid_request: The redirect_uri is not whitelisted".

```bash
https://(your-domain).com/authenticate
```

--------------------------------

### Add billable middleware for v1.x.x to v2.0.0 upgrade

Source: https://github.com/kyon147/laravel-shopify/wiki/Upgrading

Add this line to the routeMiddleware array in app/Http/Kernel.php to enable the billing feature on existing installs when upgrading from v1.x.x to v2.0.0. Place it just under auth.shop, auth.proxy, auth.webhook, etc.

```php
'billable' => \OhMyBrew\ShopifyApp\Middleware\Billable::class,
```

--------------------------------

### Environment Variables for Shop-Specific API Credentials

Source: https://github.com/kyon147/laravel-shopify/wiki/Multiple-Custom-Apps-on-Same-Codebase

Example environment variables for a shop with domain 'charles-store.myshopify.com'. The keys are derived from the shop name normalized to uppercase and stripped of non-alphanumeric characters. These variables are used by the config_api_callback to provide shop-specific API credentials.

```plaintext
API_KEY_CHARLESSTORE="66d7f69b713b201e06805db4d6f9bcefa"
API_SECRET_CHARLESSTORE="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"
```

--------------------------------

### Set Shopify callback URL

Source: https://github.com/kyon147/laravel-shopify/wiki/Installation

Set this as the callback URL in your Shopify Partner dashboard. It must start with https.

```bash
https://(your-domain).com/
```

--------------------------------

### Extend Shopify AppBridge layout in welcome view

Source: https://github.com/kyon147/laravel-shopify/wiki/Installation

Replace the contents of resources/views/welcome.blade.php to extend the package's layout for Shopify AppBridge abilities. This example shows a title bar and buttons.

```blade
@extends('shopify-app::layouts.default')

@section('content')
    <!-- You are: (shop domain name) -->
    <p>You are: {{ $shopDomain ?? Auth::user()->name }}</p>

    <ui-title-bar title="Products">
    <button onclick="console.log('Secondary action')">Secondary action</button>
    <button variant="primary" onclick="console.log('Primary action')">
        Primary action
    </button>
    </ui-title-bar>
@endsection
```

--------------------------------

### Route with auth.proxy middleware to AppProxyController

Source: https://github.com/kyon147/laravel-shopify/wiki/App-Proxies

Add this GET route to app/routes/web.php to point /proxy to AppProxyController@index. The auth.proxy middleware validates the proxy signature before the request reaches the controller.

```php
Route::get('/proxy', 'AppProxyController@index')->middleware('auth.proxy');
```

--------------------------------

### Docker Compose Setup for Nginx and PHP-FPM

Source: https://github.com/kyon147/laravel-shopify/wiki/Developing-Locally

Docker Compose configuration that defines Nginx and PHP-FPM services, mounts the project and SSL certificates, and binds port 8000 to 443. Place in 'docker-compose.yml'.

```yaml
nginx:
    image: nginx:latest
    ports:
        - '8000:443'
    volumes:
        - $PWD/default.conf:/etc/nginx/conf.d/default.conf
        - $PWD:/var/www/html
        - $PWD/ssl:/etc/nginx/ssl
    links:
        - php
    restart: always
php:
    image: php:7-fpm
    volumes:
        - $PWD:/var/www/html
```

--------------------------------

### Register a webhook in config/shopify-app.php

Source: https://github.com/kyon147/laravel-shopify/wiki/Creating-Webhooks

Register a non-GDPR webhook in config/shopify-app.php. The topic must be in RESOURCE_EVENT format (e.g., ORDERS_CREATE) and the address must be publicly accessible. When a shop logs in, this entry is automatically installed and the corresponding job (App/Jobs/OrdersCreateJob) becomes ready.

```php
// ...
'webhooks' => [
    [
        'topic' => 'ORDERS_CREATE',
        'address' => 'https://some-app.com/webhook/orders-create'
    ],
],
// ...
```

--------------------------------

### Update shop lookup: ShopifyApp::shop() to Auth::user()

Source: https://github.com/kyon147/laravel-shopify/wiki/Upgrade-guide-v10.x-to--v11.x

Replace the deprecated ShopifyApp::shop() call with Auth::user() and update the database column reference from shopify_domain to name. The example shows the before and after for querying the shop by domain.

```php
Shop::where('shopify_domain', 'my_store');
=>
User::where('name', 'my_store');
```

--------------------------------

### Add required config values for Shopify API version and grant mode

Source: https://github.com/kyon147/laravel-shopify/wiki/Upgrading

Required configuration values for upgrading from 6.x.x to 7.0.0. The api_version uses the Shopify API version string (YYYY-MM or unstable) and api_grant_mode defaults to offline, with per-user available; install always uses offline mode.

```php
    /*
    |--------------------------------------------------------------------------
    | Shopify API Version
    |--------------------------------------------------------------------------
    |
    | This option is for the app's API version string.
    | Use "YYYY-MM" or "unstable". Refer to Shopify's documentation
    | on API versioning for the current stable version.
    |
    */

    'api_version' => env('SHOPIFY_API_VERSION', null),

    /*
    |--------------------------------------------------------------------------
    | Shopify API Grant Mode
    |--------------------------------------------------------------------------
    |
    | This option is for the grant mode when authenticating.
    | Default is "offline", "per-user" is available as well.
    | Note: Install will always be in offline mode.
    |
    */

    'api_grant_mode' => env('SHOPIFY_API_GRANT_MODE', 'offline'),
```

--------------------------------

### Publish and run migrations for v4.0.0 upgrade

Source: https://github.com/kyon147/laravel-shopify/wiki/Upgrading

Run these commands to publish and run the migrations that add plan_id and freemium to shops, plan_id to charges, and create a plans table.

```bash
php artisan vendor:publish --tag=migrations
```

```bash
php artisan migrate
```

--------------------------------

### Migration to add finished_setup column

Source: https://github.com/kyon147/laravel-shopify/wiki/Free-Access-Based-on-Shopify-Plan

Create a migration file database/migrations/AddFinishedSetupToShopsTable.php that adds a boolean 'finished_setup' column to the users table with a default of false, and drops it on rollback.

```php
<?php

use Illuminate\Support\Facades\Schema;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Database\Migrations\Migration;

class AddFinishedSetupToUsersTable extends Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        Schema::table('users', function (Blueprint $table) {
            $table->boolean('finished_setup')->default(false);
        });
    }

    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down()
    {
        Schema::table('users', function (Blueprint $table) {
            $table->dropColumn('finished_setup');
        });
    }
}
```

--------------------------------

### Run package migrations

Source: https://github.com/kyon147/laravel-shopify/wiki/Expiring-Offline-Access-Tokens

Run the package migrations to add the required columns for storing encrypted refresh tokens and expiration timestamps.

```bash
php artisan migrate
```

--------------------------------

### Import getShopifyConfig helper

Source: https://github.com/kyon147/laravel-shopify/wiki/Upgrading

Import the global helper function 'getShopifyConfig' to replace the removed ConfigAccessible trait and ConfigHelper service. Use this in your PHP files and update any '$this->getConfig' calls to 'getShopifyConfig'.

```php
use function Osiset\ShopifyApp\getShopifyConfig;
```

--------------------------------

### Modify AfterAuthenticateJob to use finished_setup flag

Source: https://github.com/kyon147/laravel-shopify/wiki/Free-Access-Based-on-Shopify-Plan

Modify the handle method in App\Jobs\AfterAuthenticateJob to check if finished_setup is true and return early. If not grandfathered and plan is 'affiliate' or 'staff_business', set both flags and save.

```php
    # Modify handle in App\Jobs\AfterAuthenticateJob
    public function handle()
    {
        if ($this->shop->finished_setup) {
            // Setup has finished, this should've ran by now, kill it
            return;
        }

        if (!$this->shop->isGrandfathered()) {
            $planName = $this->shop->api()->rest('GET', '/admin/shop.json')->body->shop->plan_name;
            if ($planName === 'affiliate' || $planName === 'staff_business') {
                 $this->shop->shopify_grandfathered = true;
                 $this->shop->finished_setup = true;
                 $this->shop->save();
            }
        }
    }
```

--------------------------------

### Link to billing screen with route helper and host parameter

Source: https://github.com/kyon147/laravel-shopify/wiki/Creating-a-Billable-App

Use this HTML anchor to direct the shop to the billing screen for a new plan when using a normal route. You must pass the 'host' parameter manually, retrieved from the request input, along with 'shop' and 'plan'.

```html
<p><a href="{{ route('billing', ['plan' => 2, 'shop' => Auth::user()->name, 'host' =>  app('request')->input('host') ]) }}">Upgrade</a></p>
```

--------------------------------

### Artisan command: migrate-expiring-offline-tokens with options

Source: https://github.com/kyon147/laravel-shopify/wiki/Expiring-Offline-Access-Tokens

Commands to run a dry-run, dispatch migration jobs, target a single shop, and specify queue/connection. The --dry-run flag previews qualifying shops, while --shop targets specific shops and --queue/--connection override queue settings for that run.

```bash
php artisan shopify-app:migrate-expiring-offline-tokens --dry-run
```

```bash
php artisan shopify-app:migrate-expiring-offline-tokens
```

```bash
php artisan shopify-app:migrate-expiring-offline-tokens --shop=example.myshopify.com
```

```bash
php artisan shopify-app:migrate-expiring-offline-tokens --queue=shopify-tokens
```

```bash
php artisan shopify-app:migrate-expiring-offline-tokens --queue=shopify-tokens --connection=redis
```

--------------------------------

### Define home route with verify.shopify middleware

Source: https://github.com/kyon147/laravel-shopify/wiki/Installation

Modify the default route in routes/web.php to use the verify.shopify middleware and name it 'home'. This is required for the package to work.

```php
Route::get('/', function () {
    return view('welcome');
})->middleware(['verify.shopify'])->name('home');
```

--------------------------------

### Simple app proxy route returning liquid content

Source: https://github.com/kyon147/laravel-shopify/wiki/App-Proxies

Add this route to routes/web.php to return a simple 'Hello, world!' response with the application/liquid content type. The auth.proxy middleware validates the proxy signature.

```php
Route::get('/proxy', function () {
   return response('Hello, world!')->withHeaders(['Content-Type' => 'application/liquid']);
})->middleware('auth.proxy');
```

--------------------------------

### MySQL: Update plans and charges type to uppercase

Source: https://github.com/kyon147/laravel-shopify/wiki/Upgrade-guide-v10.x-to--v11.x

Updates the type column in the plans and charges tables to uppercase. The example shows updating from type 1 to 'RECURRING'. Adjust the type values based on the ChargeType enum.

```mysql
UPDATE plans set type = 'RECURRING' where type = 1;
UPDATE charges set type = 'RECURRING' where type = 1;
```

--------------------------------

### Create a job with Artisan

Source: https://github.com/kyon147/laravel-shopify/wiki/After-Authentication-Job

Use the artisan make:job command to create a new job class. Replace {YourJobName} with the desired class name.

```bash
php artisan make:job {YourJobName}
```

--------------------------------

### Check shop creation date to prevent re-running

Source: https://github.com/kyon147/laravel-shopify/wiki/Free-Access-Based-on-Shopify-Plan

Modify the handle method in App\Jobs\AfterAuthenticateJob to check if the shop was created today. If not, return early. Otherwise, check if the shop is not grandfathered and if the plan is 'affiliate' or 'staff_business', then set the grandfathered flag and save.

```php
    # ...
    use Carbon\Carbon;
    # ...

    # Modify handle in App\Jobs\AfterAuthenticateJob
    public function handle()
    {
        if ($this->shop->created_at->diffInDays(Carbon::today()) !== 0) {
            // Shop is older than a day, we should've ran this by now, kill it
            return;
        }

        if (!$this->shop->isGrandfathered()) {
            $planName = $this->shop->api()->rest('GET', '/admin/shop.json')->body->shop->plan_name;
            if ($planName === 'affiliate' || $planName === 'staff_business') {
                 $this->shop->shopify_grandfathered = true;
                 $this->shop->save();
            }
        }
    }
```

--------------------------------

### Link to billing screen with tokenRoute for plan upgrade

Source: https://github.com/kyon147/laravel-shopify/wiki/Creating-a-Billable-App

Use this HTML anchor to direct the shop to the billing screen for a new plan. The tokenRoute method automatically passes the host parameter. The 'plan' parameter is the plan ID from the plans table, and 'shop' is the shop's name from Auth::user()->name.

```html
<a href="{{ URL::tokenRoute('new-page', ['plan' => 1, 'shop' => Auth::user()->name ]) }}">Move to plan 1</a>
```

--------------------------------

### Add session_token_refresh_interval config for v17.2.0

Source: https://github.com/kyon147/laravel-shopify/wiki/Upgrading

Add this configuration entry when upgrading from v17.0.x to v17.2.0. It sets the session token refresh interval in milliseconds used to verify JWT requests. The default is 2000 milliseconds; without it you will get an error in the console.

```php
    /*
    |--------------------------------------------------------------------------
    | Session Token Interval
    |--------------------------------------------------------------------------
    |
    | Set the session token interval in milliseconds that is used to verify 
    | the JWT requests.
    |
    */
    'session_token_refresh_interval' => env('SESSION_TOKEN_REFRESH_INTERVAL', 2000),
```

--------------------------------

### Accessing API for the current shop

Source: https://github.com/kyon147/laravel-shopify/wiki/Usage

Shows how to use the shop's api() method to make REST and GraphQL calls.

```php
// Underlying API package (osiset/basic-shopify-api)
$shop = Auth::user();
$shop->api()->rest(...);
$shop->api()->graph(...);
```

--------------------------------

### shopify.app.toml configuration

Source: https://github.com/kyon147/laravel-shopify/wiki/How-to-create-App-Extension

Configuration file for the Shopify app extension. Replace placeholders with your app's name, scopes, API key, secret, URL, host, and port.

```toml
NAME = "YOUR APP NAME HERE"
SCOPES = "YOUR SCOPES HERE"
SHOPIFY_API_KEY = "YOUR SHOPIFY APP API KEY HERE"
SHOPIFY_API_SECRET = "YOUR SHOPIFY APP SECRET HERE"
APP_URL = "YOUR APP URL"
HOST = "YOUR APP HOST"
PORT = "YOUR APP URL PORT"
```

--------------------------------

### Override render method to handle Shopify exceptions

Source: https://github.com/kyon147/laravel-shopify/wiki/Custom-Exception-Handling

Override the render method in app/Exceptions/Handler.php to handle Shopify app exceptions. The example checks for MissingShopDomainException and returns a custom error view with a 500 status. A commented-out block shows how to capture all exceptions by checking for BaseException.

```php
    public function render($request, Throwable $exception)
    {
        if ($exception instanceof \Osiset\ShopifyApp\Exceptions\MissingShopDomainException) {
            return response()->view('errors.custom', [], 500);
        }

        // If you would like to capture ALL errors from this page
        //
        // if ($exception instanceof \Osiset\ShopifyApp\Exceptions\BaseException) {
        //    return response()->view('errors.custom', [], 500);
        // }

        return parent::render($request, $exception);
    }
```

--------------------------------

### Artisan command to preview and dispatch renewals

Source: https://github.com/kyon147/laravel-shopify/wiki/Expiring-Offline-Access-Tokens

Use these commands to preview or dispatch renewal jobs for shops with expiring offline tokens. The --dry-run flag previews without dispatching, --shop targets a single shop, --days overrides the renewal window, and --queue/--connection target a dedicated worker.

```bash
# Preview shops that would be renewed
php artisan shopify-app:refresh-expiring-offline-tokens --dry-run

# Dispatch renewal jobs for all shops within the renewal window
php artisan shopify-app:refresh-expiring-offline-tokens

# Target a single shop or override the window
php artisan shopify-app:refresh-expiring-offline-tokens --shop=example.myshopify.com
php artisan shopify-app:refresh-expiring-offline-tokens --days=7

# Target a dedicated worker (CLI override; optional --connection)
php artisan shopify-app:refresh-expiring-offline-tokens --queue=shopify-tokens
php artisan shopify-app:refresh-expiring-offline-tokens --queue=shopify-tokens --connection=redis
```

--------------------------------

### Artisan command: migrate-expiring-offline-tokens with --shop option

Source: https://github.com/kyon147/laravel-shopify/wiki/Expiring-Offline-Access-Tokens

Command to process a specific list of shops in a single run, useful for large datasets with sync queue driver. The --shop option accepts a comma-separated list of shop domains.

```bash
php artisan shopify-app:migrate-expiring-offline-tokens \
  --shop=store1.myshopify.com,store2.myshopify.com,store3.myshopify.com
```

--------------------------------

### List of Shopify plan names for reference

Source: https://github.com/kyon147/laravel-shopify/wiki/Free-Access-Based-on-Shopify-Plan

A reference list of Shopify plan names that can be used to determine which plans to allow free access. This list is provided by a user in the issue comments and includes plans like 'affiliate', 'staff', 'professional', and many others.

```text
"affiliate",
"staff",
"professional",
"custom",
"shopify_plus",
"unlimited",
"basic",
"cancelled",
"staff_business",
"trial",
"dormant",
"frozen",
"singtel_unlimited",
"npo_lite",
"singtel_professional",
"singtel_trial",
"npo_full",
"business",
"singtel_basic",
"uafrica_professional",
"sales_training",
"singtel_starter",
"uafrica_basic",
"fraudulent",
"enterprise",
"starter",
"comped",
"shopify_alumni"
```

--------------------------------

### Manual client reset with resetApiClient

Source: https://github.com/kyon147/laravel-shopify/wiki/Expiring-Offline-Access-Tokens

Replace manual workarounds like setting $shop->apiHelper = null with the official public helper resetApiClient(). This clears the cached client so the subsequent API call is forced to pull a freshly rotated token.

```php
// Clear the cached client so the subsequent call is forced to pull a freshly rotated token
$shop->resetApiClient();

$shop->api()->graph('...');
```

--------------------------------

### Create usage charge route in controller

Source: https://github.com/kyon147/laravel-shopify/wiki/Creating-a-Billable-App

Creates a usage charge array with description and price, generates an HMAC signature using the Shopify app secret, and builds a route to the billing.usage_charge endpoint. The redirect parameter is optional; if omitted, the user is redirected back with a flash success message.

```php
# App/Http/Controllers/Example
# ...
public function index()
{
    // Description and price of usage charge (the only two parameters required)
    $charge = [
        'description' => 'Five e-mails',
        'price'       => 1.00,
        'redirect'    => route('example.success') // Optional, if not supplied redirect goes back to previous page with flash `success`=`true`
    ];

    // Create a signature to prevent tampering
    $signature = Util::createHmac(['data' => $charge, 'buildQuery' => true], Config::get('shopify-app.api_secret'));

    // Create the route
    $usageChargeRoute = route('billing.usage_charge', array_merge($charge, ['signature' => $signature->toNative()]));

    return view('example.index', compact('usageChargeRoute'));
}
```

--------------------------------

### Configure iframe_ancestors in shopify-app.php

Source: https://github.com/kyon147/laravel-shopify/wiki/Installation

Configure additional domains for the frame-ancestors directive in the configs/shopify-app.php file. Domains are separated by spaces.

```php
    'iframe_ancestors' => 'mysite.com subdomain.yoursite.net', // domain will be separated by space
```

--------------------------------

### Configure local script tag in config/shopify-app.php

Source: https://github.com/kyon147/laravel-shopify/wiki/Installation

Configures a script tag pointing to a local JavaScript file. The dummy.js file should be placed in the public/scripttags directory.

```php
'scripttags' => [
    [
        'src' => env('SHOPIFY_SCRIPTTAG_1_SRC', env('APP_URL') . '/scripttags/dummy.js'),
        'event' => env('SHOPIFY_SCRIPTTAG_1_EVENT', 'onload'),
        'display_scope' => env('SHOPIFY_SCRIPTTAG_1_DISPLAY_SCOPE', 'online_store')
    ]
],
```

--------------------------------

### Enable APP_UNINSTALLED webhook in config/shopify-app.php

Source: https://github.com/kyon147/laravel-shopify/wiki/Installation

Enables the app uninstalled webhook in config/shopify-app.php. Set the topic to 'app/uninstalled' and the path to '/webhook/app-uninstalled' so the webhook manager handles it automatically.

```php
'webhooks' => [
    [
        'topic' => env('SHOPIFY_WEBHOOK_1_TOPIC', 'APP_UNINSTALLED'),
        'address' => env('SHOPIFY_WEBHOOK_1_ADDRESS', 'https://(your-domain).com/webhook/app-uninstalled')
    ],
],
```

--------------------------------

### Schedule with queue override baked in

Source: https://github.com/kyon147/laravel-shopify/wiki/Expiring-Offline-Access-Tokens

Alternative scheduler entry that bakes the queue override directly into the command string.

```php
Schedule::command('shopify-app:refresh-expiring-offline-tokens --queue=shopify-tokens')->daily();
```

--------------------------------

### Swap API Keys per Shop via config_api_callback in Laravel Shopify

Source: https://github.com/kyon147/laravel-shopify/wiki/Multiple-Custom-Apps-on-Same-Codebase

Configure the 'config_api_callback' option in config/shopify-app.php to dynamically swap API keys per shop. Requires a ShopDomain object or string; cleans the shop domain to create an environment variable name. Falls back to the default config value when no shop is passed.

```php
use Osiset\ShopifyApp\Contracts\Objects\Values\ShopDomain as ShopDomainValue;
use Illuminate\Support\Facades\Config;

    // ...

    'config_api_callback' => function (string $key, $shop) {
        $fullKey = "shopify-app.{$key}";
        if (! $shop) {
            // No shop passed, return default
            return Config::get($fullKey);
        }

        // Clean the shop domain
        $shopDomain = $shop instanceof ShopDomainValue ? $shop->toNative() : $shop;
        $shopDomain = preg_replace('/[^A-Z0-9]/', '', strtoupper(explode('.', $shopDomain)[0]));

        // Try to get env defined for shop, fallback to config value
        return env(
             strtoupper($key)."_".$shopDomain,
             Config::get($fullKey)
        );
    },
```

--------------------------------

### Programmatic migration using MigrateShopToExpiringOfflineAccessToken

Source: https://github.com/kyon147/laravel-shopify/wiki/Expiring-Offline-Access-Tokens

PHP code to execute the migration action class directly, returning a result object with properties: migrated, skipped, reason, or error. Useful for custom UI workflows or scripts.

```php
use Kyon147\LaravelShopify\Actions\MigrateShopToExpiringOfflineAccessToken;

$result = app(MigrateShopToExpiringOfflineAccessToken::class)($shop);

// The returned result object allows you to inspect: migrated, skipped, reason, or error.
```

--------------------------------

### Configure remote script tag in config/shopify-app.php

Source: https://github.com/kyon147/laravel-shopify/wiki/Installation

Configures a script tag with a remote source URL. The event defaults to 'onload' and display_scope to 'online_store'. Place this in config/shopify-app.php.

```php
'scripttags' => [
    [
        'src' => env('SHOPIFY_SCRIPTTAG_1_SRC', 'https://some-app.com/some-controller/js-method-response'),
        'event' => env('SHOPIFY_SCRIPTTAG_1_EVENT', 'onload'),
        'display_scope' => env('SHOPIFY_SCRIPTTAG_1_DISPLAY_SCOPE', 'online_store')
    ]
],
```

--------------------------------

### Publish Shopify jobs with artisan vendor:publish

Source: https://github.com/kyon147/laravel-shopify/wiki/Installation

Publishes the default AppUninstalledJob to App/Jobs/AppUninstalledJob. Run this before enabling the uninstalled webhook.

```bash
php artisan vendor:publish --tag=shopify-jobs
```

--------------------------------

### Add 'itp' middleware to custom web route

Source: https://github.com/kyon147/laravel-shopify/wiki/Upgrading

Shows the before and after of adding the 'itp' middleware to a custom web route. The first block is the original route, the second is the updated version with 'itp' prepended to the middleware array.

```php
Route::get('/tag-test', 'TagTestController@handle')
   ->middleware(['auth.shopify'])
   ->name('tag-test');
```

```php
Route::get('/tag-test', 'TagTestController@handle')
   ->middleware(['itp', 'auth.shopify'])
   ->name('tag-test');
```

--------------------------------

### Update job constructor to use scalar values

Source: https://github.com/kyon147/laravel-shopify/wiki/Upgrading

Shows the before and after of updating job constructors to use scalar values instead of objects. The first block is the old constructor with ShopDomain, the second is the new one with string and conversion using ShopDomain::fromNative.

```php
public function __construct(ShopDomain $domain, stdClass $data)
{
    $this->domain = $domain;
    // ...
}

public function handle(
    IShopCommand $shopCommand,
    IShopQuery $shopQuery,
    CancelCurrentPlan $cancelCurrentPlanAction
): bool {
    // ...
}
```

```php
public function __construct(string $domain, stdClass $data)
{
    $this->domain = $domain;
    // ...
}

public function handle(
    IShopCommand $shopCommand,
    IShopQuery $shopQuery,
    CancelCurrentPlan $cancelCurrentPlanAction
): bool {
    // Convert the domain
    $this->domain = ShopDomain::fromNative($this->domain);

    // ...
}
```

--------------------------------

### MySQL: Move data from shops into users

Source: https://github.com/kyon147/laravel-shopify/wiki/Upgrade-guide-v10.x-to--v11.x

Copies data from the shops table into the users table, keeping the same IDs. Maps shopify_domain to name, email to email, shopify_token to password, and other columns accordingly. Run this before the ModifyShopIdColumnForChargesTable migration if charges already exist.

```mysql
INSERT INTO users (id, name, email, password, created_at, updated_at, shopify_grandfathered, shopify_freemium, plan_id, deleted_at)
SELECT id, shopify_domain, email, shopify_token, created_at, updated_at, grandfathered, freemium, plan_id, deleted_at FROM shops;
```

--------------------------------

### Enable billing via environment variable

Source: https://github.com/kyon147/laravel-shopify/wiki/Creating-a-Billable-App

Set SHOPIFY_BILLING_ENABLED=1 in your .env file to enable billing for the application. This is a required configuration for billable mode.

```conf
SHOPIFY_BILLING_ENABLED=1
```

--------------------------------

### Publish Shopify migrations with artisan vendor:publish

Source: https://github.com/kyon147/laravel-shopify/wiki/Installation

Publishes the package migrations to your app's migration folder when SHOPIFY_MANUAL_MIGRATIONS=1 or manual migrations are configured. Run php artisan migrate afterwards to commit the changes.

```bash
php artisan vendor:publish --tag=shopify-migrations
```

--------------------------------

### SendPlanActivatedEmailListener class

Source: https://github.com/kyon147/laravel-shopify/wiki/Event-Listener-System

Listener class that sends an email to the store owner when a plan is activated. It implements ShouldQueue and uses the 'default' queue. The handle method sends a PlanActivatedMail to the shop's email address using the event's plan and chargeId.

```php
<?php

namespace App\Listeners;

use Illuminate\Bus\Queueable;
use App\Mail\PlanActivatedMail;
use Illuminate\Support\Facades\Mail;
use Illuminate\Contracts\Queue\ShouldQueue;
use Osiset\ShopifyApp\Messaging\Events\PlanActivatedEvent;

class SendPlanActivatedEmailListener implements ShouldQueue
{
    use Queueable;
    /**
     * Create the event listener.
     *
     * @return void
     */
    protected Shop $shop;

    public function __construct()
    {
        $this->onQueue('default');
    }

    /**
     * Handle the event.
     *
     * @param  object  $event
     * @return void
     */
    public function handle(PlanActivatedEvent $event)
    {
        Mail::to($event->shop->email)
            ->send(new PlanActivatedMail($event->plan, $event->chargeId));
    }
}
```

--------------------------------

### Config snippet for after_authenticate_job

Source: https://github.com/kyon147/laravel-shopify/wiki/After-Authentication-Job

Default configuration block in config/shopify-app.php. Replace the job value with the namespace to your job class, e.g., \App\Jobs\AfterAuthenticateJob::class.

```php
    'after_authenticate_job' => [
        'job' => '',
        'inline' => false,
    ],
```

--------------------------------

### AfterAuthenticateJob implementation for free access

Source: https://github.com/kyon147/laravel-shopify/wiki/Free-Access-Based-on-Shopify-Plan

Replace the contents of App\Jobs\AfterAuthenticateJob with this code. It checks if the shop is not already grandfathered, then fetches the shop's plan name via the Shopify Admin API. If the plan is 'affiliate' or 'staff_business', it sets the shopify_grandfathered flag to true and saves the shop. Modify the second if statement to change which plans are allowed.

```php
<?php

namespace App\Jobs;

use Osiset\ShopifyApp\Contracts\ShopModel;

class AfterAuthenticateJob
{
    /**
     * Shop's instance.
     *
     * @var ShopModel
     */
    protected $shop;

    /**
     * Create a new job instance.
     *
     * @param ShopModel $shop The shop's object
     *
     * @return void
     */
    public function __construct(ShopModel $shop)
    {
        $this->shop = $shop;
    }

    /**
     * Execute the job.
     *
     * @return void
     */
    public function handle()
    {
        if (!$this->shop->isGrandfathered()) {
            $planName = $this->shop->api()->rest('GET', '/admin/shop.json')->body->shop->plan_name;
            if ($planName === 'affiliate' || $planName === 'staff_business') {
                 $this->shop->shopify_grandfathered = true;
                 $this->shop->save();
            }
        }
    }
}
```

--------------------------------

### Enable global pre-flight check via SHOPIFY_REFRESH_OFFLINE_TOKEN_BEFORE_API_CALL

Source: https://github.com/kyon147/laravel-shopify/wiki/Expiring-Offline-Access-Tokens

Set SHOPIFY_REFRESH_OFFLINE_TOKEN_BEFORE_API_CALL=true in your .env file to enable a global pre-flight check. This forces the package to inspect the token's remaining lifespan before every API call and automatically refresh the client if the token is within the expiration or skew window.

```env
SHOPIFY_REFRESH_OFFLINE_TOKEN_BEFORE_API_CALL=true
```

--------------------------------

### Force HTTPS in Laravel AppServiceProvider boot method

Source: https://github.com/kyon147/laravel-shopify/wiki/ngrok

Add this code to the boot method of app/Providers/AppServiceProvider.php to force HTTPS, which may help resolve ngrok-related issues caused by http to https redirects.

```php
public function boot(Illuminate\Contracts\Routing\UrlGenerator $url)
{
    $url->forceScheme('https');
}
```

--------------------------------

### Generate CustomersDataRequestJob via artisan

Source: https://github.com/kyon147/laravel-shopify/wiki/GDPR

Artisan command to create a webhook job for the customers/data_request topic. The command creates App/Jobs/CustomersDataRequestJob which you can modify to gather customer data for the shop owner.

```bash
php artisan shopify-app:make:webhook CustomersDataRequestJob customers/data_request
```

--------------------------------

### Implement IShopModel on User class

Source: https://github.com/kyon147/laravel-shopify/wiki/Installation

Modify the class declaration of your User model to implement IShopModel.

```php
class User extends Authenticatable implements IShopModel
```

--------------------------------

### Use getShopifyConfig in Blade template

Source: https://github.com/kyon147/laravel-shopify/wiki/Upgrading

Reference the new global helper function in Blade templates to retrieve configuration values, such as 'app_name'.

```php
{{ \Osiset\ShopifyApp\getShopifyConfig('app_name') }}
```

--------------------------------

### Generate Self-Signed SSL Certificate with OpenSSL

Source: https://github.com/kyon147/laravel-shopify/wiki/Developing-Locally

Generates a self-signed certificate for local development. Replace 'localhost.ssl' with your desired domain and adjust the OpenSSL config path for OSX. The command saves 'ssl/domain.key' and 'ssl/domain.csr'.

```bash
openssl req -new -sha256 \
    -key ssl/domain.key \
    -subj "/C=US/ST=CA/O=Acme, Inc./CN=localhost.ssl" \
    -reqexts SAN \
    -config <(cat /etc/ssl/openssl.cnf \
        <(printf "\n[SAN]\nsubjectAltName=DNS:localhost.ssl")) \
    -out ssl/domain.csr
```

--------------------------------

### Schedule daily token refresh command

Source: https://github.com/kyon147/laravel-shopify/blob/master/README.md

Add this to your app's routes/console.php or Kernel to schedule the package's refresh command. The package does not register a schedule automatically, so this is required for proactive renewal.

```php
Schedule::command('shopify-app:refresh-expiring-offline-tokens')->daily();
```

--------------------------------

### Event listener registration for PlanActivatedEvent

Source: https://github.com/kyon147/laravel-shopify/wiki/Event-Listener-System

Event listener registration array for Laravel's EventServiceProvider. It maps events to their listeners, with the PlanActivatedEvent registered to the PlanActivatedEvent listener. Other events are commented out as placeholders.

```php
'listen' => [
        \Osiset\ShopifyApp\Messaging\Events\AppInstalledEvent::class => [
            // \App\Listeners\MyListener::class,
        ],
        \Osiset\ShopifyApp\Messaging\Events\ShopAuthenticatedEvent::class => [
            // \App\Listeners\MyListener::class,
        ],
        \Osiset\ShopifyApp\Messaging\Events\ShopDeletedEvent::class => [
            // \App\Listeners\MyListener::class,
        ],
        \Osiset\ShopifyApp\Messaging\Events\AppUninstalledEvent::class => [
            // \App\Listeners\MyListener::class,
        ],
        \Osiset\ShopifyApp\Messaging\Events\PlanActivatedEvent::class => [
            \App\Listeners\PlanActivatedEvent::class,
        ],
    ],
```

--------------------------------

### Add job_queues configuration to config/shopify-app.php

Source: https://github.com/kyon147/laravel-shopify/wiki/Upgrading

Add this block to config/shopify-app.php to specify queue names for webhooks, scripttags, and after_authenticate jobs. By default, Laravel falls back to the default queue if no name is given.

```php
    'job_queues' => [
        'webhooks'           => env('WEBHOOKS_JOB_QUEUE', null),
        'scripttags'         => env('SCRIPTTAGS_JOB_QUEUE', null),
        'after_authenticate' => env('AFTER_AUTHENTICATE_JOB_QUEUE', null),
    ],
```

--------------------------------

### Set AppBridge CDN URL via Environment Variable

Source: https://github.com/kyon147/laravel-shopify/wiki/Upgrading

Set the SHOPIFY_APPBRIDGE_CDN_URL environment variable to change the AppBridge CDN. Do not add a trailing slash.

```bash
SHOPIFY_APPBRIDGE_CDN_URL="https://cdn.jsdelivr.net/npm"
```

```bash
SHOPIFY_APPBRIDGE_CDN_URL="https://unpkg.com"
```

--------------------------------

### Add API rate limiting entries to config/shopify-app.php

Source: https://github.com/kyon147/laravel-shopify/wiki/Upgrading

Add these three new entries to config/shopify-app.php for API rate limiting. You can use artisan to vendor:publish the config or add them manually.

```php
'api_rate_limiting_enabled' => env('SHOPIFY_API_RATE_LIMITING_ENABLED', false),
'api_rate_limit_cycle' => env('SHOPIFY_API_RATE_LIMIT_CYCLE', null),
'api_rate_limit_cycle_buffer' => env('SHOPIFY_API_RATE_LIMIT_CYCLE_BUFFER', null),
```

--------------------------------

### Add Shopify middleware aliases

Source: https://github.com/kyon147/laravel-shopify/wiki/Upgrade-guide-v10.x-to--v11.x

Add the package middleware aliases to the route middleware in app/Http/Kernel.php.

```php
'auth.shopify' => \Osiset\ShopifyApp\Http\Middleware\AuthShopify::class,
'auth.webhook' => \Osiset\ShopifyApp\Http\Middleware\AuthWebhook::class,
'auth.proxy' => \Osiset\ShopifyApp\Http\Middleware\AuthProxy::class,
'billable' => \Osiset\ShopifyApp\Http\Middleware\Billable::class,
```

--------------------------------

### Namespace configuration in config/shopify-app.php

Source: https://github.com/kyon147/laravel-shopify/wiki/Namespacing-Your-App

Set a namespace for the app by modifying the 'namespace' key in the Laravel config file. The default is null, which can be overridden with the SHOPIFY_APP_NAMESPACE environment variable or a string directly.

```php
    /*
    |--------------------------------------------------------------------------
    | Namespace
    |--------------------------------------------------------------------------
    |
    | This option allows you to set a namespace.
    | Useful for multiple apps using the same database instance.
    | Meaning, one shop can be part of many apps on the same database.
    |
    */

    'namespace' => env('SHOPIFY_APP_NAMESPACE', null),
```
Tokens:
Raw