Skip to content
Rishabh Tayal edited this page Nov 15, 2024 · 22 revisions

Please refer to the Changelog doc as well..

v21.2.0 => v22.0.0

Important: This is a major release. Please test your upgrade locally beforehand.

This version moves away from the the older AppBridge to AppBridge v4 which no longer requires initialising with host the same way.

These config values are now deprecated and have been removed from the config.

SHOPIFY_APPBRIDGE_ENABLED SHOPIFY_APPBRIDGE_VERSION SHOPIFY_APPBRIDGE_CDN_URL

Turbolinks/Livewire has also been removed in this version

SHOPIFY_TURBO_ENABLED

If you have overloaded the default.blade.php file please see the changes that were made so you can make the same updates.

v21.1.0 => v21.2.0

Some small comments and additions were added to the config but nothing should be breaking changes between this version and the previous.

    /*
    |--------------------------------------------------------------------------
    | Sub Domain
    |--------------------------------------------------------------------------
    |
    | This is the subdomain where Shopify will be accessible from. If the
    | setting is null, Shopify will reside under the same domain as the
    | application. Otherwise, this value will be used as the subdomain.
    |
    */

    'domain' => env('SHOPIFY_DOMAIN'),

v21.0.0 => v21.1.0

The api version for Shopify has been upgraded, so check to make sure your app is not affected by any api changes.

v20.0.0 => v21.0.0

Laravel 11 support was added please make sure you check the Laravel requirements https://laravel.com/docs/11.x/upgrade

v19.x.x => v20.0.0

Base Shopify API version was updated so there could be breaking api changes so please check.

v19.x.x => v19.2.0

This version added in a automated way to verify that your api scopes have not changed.

You can add verfiy.scopes to your route middleware and it will check the current scopes with the shop vs the ones set in your config. If they are different it will push them to re-auth and accept the new permissions.

v18.x.x => v19.0.0

v19 releases the theme level support. This checks to see if a theme can use app blocks or just script tags and sets a flag in the database for what level.

This means you will need to run php artisan migrate to get the latest changes into your DB. If you are running manual migrations then you will need to add the changes from this file

The namespace for the underlying Shopify API Package has also changed. The affected areas are in the shopify-app config file.

You will need to change the API time store, limit store and deferrer to point to the new namespace. Here's the three updated below.

 /*
    |--------------------------------------------------------------------------
    | Shopify API Time Store
    |--------------------------------------------------------------------------
    |
    | This option is for the class which will hold the timestamps for
    | API calls.
    |
    */

    'api_time_store' => env('SHOPIFY_API_TIME_STORE', \Gnikyt\BasicShopifyAPI\Store\Memory::class),

    /*
    |--------------------------------------------------------------------------
    | Shopify API Limit Store
    |--------------------------------------------------------------------------
    |
    | This option is for the class which will hold the call limits for REST
    | and GraphQL.
    |
    */

    'api_limit_store' => env('SHOPIFY_API_LIMIT_STORE', \Gnikyt\BasicShopifyAPI\Store\Memory::class),

    /*
    |--------------------------------------------------------------------------
    | Shopify API Deferrer
    |--------------------------------------------------------------------------
    |
    | This option is for the class which will handle sleep deferrals for
    | API calls.
    |
    */

    'api_deferrer' => env('SHOPIFY_API_DEFERRER', \Gnikyt\BasicShopifyAPI\Deferrers\Sleep::class),

v18.0.0 => v18.2.0

Although 18.2.0 should be backwards compatible to change the App Bridge CDN you need to add a value to your Shopify config

// Set a new CDN URL if you want to host the AppBridge JS yourself or unpkg goes down.
'appbridge_cdn_url' => env('SHOPIFY_APPBRIDGE_CDN_URL', 'https://unpkg.com'),

Then you can change it like so;

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

SHOPIFY_APPBRIDGE_CDN_URL="https://unpkg.com"

Note: please don't add a trailing slash.

v17.x.x => v18.0.0

PHP8.0 is now the minimum requirement for the package on Laravel 8/9

PHP8.1 is now the minimum requirement for the package on Laravel 10

Please check the upgrade guides on Laravel to see what other dependancies you need to update.

v17.4.4 => v17.5.0

PHP 7.3 is the minimum requirement for the package in this version.

17.4.4

You can now use the Token Route helper, it will pass the host along if it exists.

<a href="{{ URL::tokenRoute('new-page', ['foo' => 'bar']) }}">New page</a>

v17.3.0 => 17.4.0

This update removes the shopOrigin from the AppBridge init - so if you are using this anywhere else in the code you will need to update to host now.

Also support for PHP 7.2 is no longer included.

Billing routes have been updated to pass along the host param, so you might need to update your links on BLADE templates like so

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

This will get the host param if it exists in the url and passes it through to billing so that it comes back on the return url.

v17.2.0 => 17.3.0

You will need to add this to your config.

    /*
    |--------------------------------------------------------------------------
    | Frontend engine used
    |--------------------------------------------------------------------------
    |
    | Available engines: "BLADE", "VUE", or "REACT".
    | For example, if you use React, you do not need to be redirected to a separate page to get the JWT token.
    | No changes are made for Vue.js and Blade.
    |
    */
    'frontend_engine' => env('SHOPIFY_FRONTEND_ENGINE', 'BLADE'),

v17.0.x => 17.2.0

You will need to add this to your config which sets an ENV for the session token interval. Otherwise you will get an error in the console.

    /*
    |--------------------------------------------------------------------------
    | 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),

v16.x.x => v17.0.0

Caution: This may or may not be a complete idea of the upgrade path required. Note: This release has no per-user support.

  1. Copy all new internal view files
  2. Replace all routes with auth.shopify middleware to verify.shopify
  3. Replace all routes with auth.token middleware to verify.shopify
  4. Remove all reference to routes with itp middleware
  5. Run php artisan vendor:publish --tag=shopify-migrations (note: This step is only needed if config.shopify-app.manual_migrations is true (default is false)).
  6. Run php artisan migrate to run the new migration for users to add password time field
  7. Open \App\Http\Middleware\VerifyCsrfToken.php and add:
protected $except = [
    '*',
];

to disable all CSRF. There is no workaround for this at the moment.

  1. Update built-in route names, your config/shopify-app.php should have:
    /*
    |--------------------------------------------------------------------------
    | Route names
    |--------------------------------------------------------------------------
    |
    | This option allows you to override the package's built-in route names.
    | This can help you avoid collisions with your existing route names.
    |
    */
    'route_names' => [
        'home'                 => env('SHOPIFY_ROUTE_NAME_HOME', 'home'),
        'authenticate'         => env('SHOPIFY_ROUTE_NAME_AUTHENTICATE', 'authenticate'),
        'authenticate.token'   => env('SHOPIFY_ROUTE_NAME_AUTHENTICATE_TOKEN', 'authenticate.token'),
        'billing'              => env('SHOPIFY_ROUTE_NAME_BILLING', 'billing'),
        'billing.process'      => env('SHOPIFY_ROUTE_NAME_BILLING_PROCESS', 'billing.process'),
        'billing.usage_charge' => env('SHOPIFY_ROUTE_NAME_BILLING_USAGE_CHARGE', 'billing.usage_charge'),
        'webhook'              => env('SHOPIFY_ROUTE_NAME_WEBHOOK', 'webhook'),
    ],
  1. Change the topic value for all of your webhooks in config/shopify-app.php to their GraphQL equivalent
  • This is typically the webhook topic/event, uppercased, with the / replaced by an underscore _
  • Examples:
    • app/uninstalled => APP_UNINSTALLED
    • customers/update => CUSTOMERS_UPDATE
    • orders/partially_fulfilled => ORDERS_PARTIALLY_FULFILLED
    • order_transactions/create => ORDER_TRANSACTIONS_CREATE
  • The full list of GraphQL webhook topic values can be found here
  • Refer to Creating Webhooks on the wiki for more information on using webhooks.
  1. If using a custom layouts/default.blade.php copied from pre-v17 layouts/default.blade.php: Change all instances of \Osiset\ShopifyApp\getShopifyConfig(...) to \Osiset\ShopifyApp\Util::getShopifyConfig(...). Add the new token handler include at the bottom. Compare the vendor file to the custom file for other changes.

10a. You might also get an error saying Str can not be found this is because you need to import it into the token.blade.php file. This can be because you are missing the Alias in config/app.php just add 'Str' => \Illuminate\Support\Str::class, to that file and it will allow blade to use the alias instead of the full import.

See Authentication Process on the wiki for more information on understanding and using session tokens.

v15.x.x => v16.0.0

ITP:

Any custom web routes you have defined, it is a good idea to append the new itp middleware. Example:

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

Would become:

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

Config:

ConfigAccessible trait, and ConfigHelper service have been removed. The main config function has moved to a global helper getShopifyConfig.

If you're using either the trait or service in your own code, simply remove it from the files, and instead include:

use function Osiset\ShopifyApp\getShopifyConfig;

And update any $this->getConfig to getShopifyConfig.

Similarly, in your Blade files you can reference this new function as well:

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

v14.x.x => v15.0.0

All jobs have changed, including webhook jobs. Serializing job constructors with objects (such as ShopDomain, various classes) causes an error, so all jobs now use basic scalar values.

Example: AppUninstalledJob.php was:

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

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

and is now:

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);

    // ...
}

You will need to convert your existing jobs to use scalar values in the contructor, including AppUninstalledJob if you have overloaded that job class.

v13.x.x => v14.0.0

No changes required.

12.x.x => v13.0.0

No changes should be required. However, be aware, the login route and view are no longer available. Instead, an exception will be thrown (MissingShopDomainException) if someone accesses your app directly outside of Shopify.

You may view Custom Exception Handling on how to handle any package exception to your own requirements.

11.x.x => 12.0.0

Removal in config/shopify-app.php The following config options were removed:

  1. api_rate_limit_cycle_buffer
  2. api_rate_limit_cycle
  3. api_rate_limiting_enabled
  4. api_class.

Addition in config/shopify-app.php The following config options we're added, see config/shopify-app.php in this repo:

  1. api_time_store
  2. api_limit_store
  3. api_deferrer
  4. api_init

Change for API access The responses from GraphQL and REST calls now return an array, where previously it was stdClass. The body also returns instance of Osiset\BasicShopifyAPI\ResponseAccess, which allows you to access the data by object notation or array.

Upgrading is simple, anything where you have $response->body->...., change to $response['body']->... or even to $response['body'][...].

Example, before:

$response = $shop->api()->rest('GET', '/admin/shop.json');
echo $response->body->shop->name;

Example, after:

$response = $shop->api()->rest('GET', '/admin/shop.json');
echo $response['body']->shop->name; // or $response['body']['shop']['name'];

10.x.x => 11.0.0

While the package has been completely rewritten for v11, it may be possible (untested) to upgrade.

(Almost) complete guide

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

Short guide

First, follow the installation guide again as shops have moved into native Laravel users.

After this, you would need to match the new database schema for tables like plans, charges, etc, as well as apply the new column entries for users.

Once done, a SELECT INSERT statement to move data from shops into users with their respective columns, keeping the IDs the same will be smoother.

Next, SELECT UPDATE all rows in charges and plans table to move the IDs from shop_id to user_id.

Next, all casing for status and type on charges table will need to be converted to uppercase.

Next, all casing for type on plans table will need to be converted to uppercase.

Next, you would need to update any use statements to the new namespacings.

Next, any webhook jobs would need to accept ShopDomain as the first argument, not string, and to get the domain as a string, you would need to use ->toNative().

... more to come ...

9.x.x => 10.0.0

No internal changes are required. However, be aware partial flow for auth was removed and only full flow auth exists now.

8.x.x => 9.x.x

No internal changes are required.

7.x.x => 8.0.0

ESDK is now moved to AppBridge. You'll need to update config/shopify-app.php.

Change

    /*
    |--------------------------------------------------------------------------
    | ESDK Mode
    |--------------------------------------------------------------------------
    |
    | ESDK (embedded apps) are enabled by default. Set to false to use legacy
    | mode and host the app inside your own container.
    |
    */

    'esdk_enabled' => (bool) env('SHOPIFY_ESDK_ENABLED', true),

To:

    /*
    |--------------------------------------------------------------------------
    | AppBridge Mode
    |--------------------------------------------------------------------------
    |
    | AppBridge (embedded apps) are enabled by default. Set to false to use legacy
    | mode and host the app inside your own container.
    |
    */

    'appbridge_enabled' => (bool) env('SHOPIFY_APPBRIDGE_ENABLED', true),

As well, you'll need to migrate your internal views to use AppBridge. The default layout provided by this package (views/layouts/default.blade.php) pulls AppBridge in via CDN; however, you're welcome to override this and use Shopify's NPM package. Toast messages are also migrated.

6.x.x => 7.0.0

Two new config values are required in config/shopify-app.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'),

5.x.x, 5.3.x => 6

Follow optional guide for 5.2.x => 5.3.0 if applicable.

This release introduces a new major version bump to the underlying Shopify API library, Basic-Shopify-API. This package was bumped as well in case some of you are are handling errors with API calls through try/catch. The difference is, the underlying package now internally catches 4XX-500 errors for you and provides the error and messaging in the response object, so your catch block will not fire for these issues.

5.2.x => 5.3.0

For issue #177, this adds the ability to specify a queue name each job should go to (webhooks, scripttags, and after_authenticate).

By default, you do not need to do anything to upgrade, Laravel will fallback to the default queue if no name is given.

However, if you wish to specify, you can re-publish the config for this package or manually modify your config/shopify-app.php to add the following:

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

4.1.x => 5.0.0

If you have not extended the package in anyway, you should be fine. Else, please see Changelog, upgrade your code and test to ensure it works. This is a major version release.

v4.0.x => v4.1.0

Three new entries for config/shopify-app.php, you can use artisan to vendor:publish the config or add the new entries:

'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),

v3.1.x => v4.0.0

Breaking changes. Can not guarentee full workability.

  1. Run the migrations, which will:
    • Add plan_id to shops table
    • Add freemium to shops table
    • Add plan_id to charges table
    • Create a plans table

php artisan vendor:publish --tag=migrations and php artisan migrate

  1. Remove all billing environment values from your env file or config/shopify-app.php execept for:

    • billing_enabled
    • billing_redirect
  2. Add to config/shopify-app.php:

    • billing_freemium_enabled with true or false
  3. Create a plan or migrate the existing one in your old config, to the database, with on_install set to true, see [wiki entry|Creating-a-Billable-App#creating-plans] for exact information

  4. Set all shops' plan_id in the database to the ID of the plan created in step 4

v3.1.x => v3.2.0

  1. Run the migrations to change the shops table and add namespace column:

php artisan vendor:publish --tag=migrations and php artisan migrate

v3.x.x => v3.1.0

  1. Remove the facade entry for this package in config/app.php under the facades array (now handled by auto-discovery).

  2. Remove the provider entry for this package in config/app.php under the providers array (now handled by auto-discovery).

  3. Run the migrations to change the charges table's charge_id column from int to bigint via:

php artisan vendor:publish --tag=migrations and php artisan migrate

v2.x.x => v3.0.0

Breaking changes.

  1. Run migrations which will remove charge_id from the Shop table and create a charges table:

php artisan vendor:publish --tag=migrations and php artisan migrate

  1. Review the installation guide of the wiki (theres a new section on enabling an optional app/uninstalled webhook job).

That's it. There's currently no script to convert the old charge_id into the charges table for the shops. You can view our wiki on creating a charge under the billing section and manually write a migration script in the meantime.

v1.x.x => v2.0.0

No internal code upgrades are required.

Simply upgrade the version in your composer file.

To enable billing feature on existing installs of this package:

Open app/Http/Kernel.php find routeMiddleware array. Add a new line with:

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

Just under auth.shop, auth.proxy, auth.webhook, etc.

Welcome to the wiki!

Please see the homepage for a list of relevant pages.

Clone this wiki locally