Upgrade Guide: v4.x to v5.0
- Overview
-
Changes
- High: Order & Payment Statuses
- High: Variables are passed differently into the {{ sc:checkout }} form
- High: Stripe Gateway now defaults to Payment Elements integration
- Medium: Support for PHP 8.1 has been dropped
- Medium: Support for Statamic 3.3 & 3.4 has been dropped
- Medium: New order_number column for database orders
- Medium: Changes to Gateway API
- Low: Control Panel Nav
- Low: ReceiveGatewayWebhook event has been renamed
- Previous upgrade guides
Overview
Warning
Please don't upgrade multiple versions at once (eg. from v3 to v5). Please upgrade one step at a time.
To get started with the upgrade process, follow the below steps:
1. In your composer.json
file, update the doublethreedigital/simple-commerce
version constraint:
1"doublethreedigital/simple-commerce": "^5.0"
2. Then run:
1composer update doublethreedigital/simple-commerce --with-dependencies
3. You may also want to clear your route & view caches:
1php artisan route:clear2php artisan view:clear
4. Simple Commerce will have attempted upgrading some things for you (like config files, blueprints, etc). However, it's possible you'll need to make some manual changes. Please review this guide for information on changes which may effect your site.
Please test locally before deploying to production!
Changes
High: Order & Payment Statuses
Previously, orders had status fields like is_paid
and is_shipped
to determine the "status" of orders.
In v5.0, Simple Commerce has introduced two new concepts: Order Statuses & Payment Statuses. One marks the status of the order (Cart, Placed, Dispatched, Cancelled) and the other marks the status of the payment (Unpaid, Paid, Refunded).
They'll be saved in your order like so:
1order_status: placed2payment_status: paid
When you run the composer update
command to upgrade to v5.0, Simple Commerce will attempt to migrate your existing orders to the new format.
In addition, it will add the new status fields to your order blueprint & remove the old ones.
If you previously had notifications configured to send on the order_shipped
event, Simple Commerce should have updated the event name to order_dispatched
.
However, it's worth noting that depending on your setup, you may need to take some manual steps:
Flat-file orders
Note!
Before running Simple Commerce's migration command on production, please take a backup of your Orders collection so you can rollback if needed.
If you store your orders as entries AND you're Git-ignoring those entries, you will need to run the migration script manually after deploying the Simple Commerce update.
1php please sc:migrate-order-statuses
It will update order entries to use the new format for statuses.
Database orders
Note!
Before running Simple Commerce's migration command on production, please take a backup of your orders
database table so you can rollback if needed.
You will need to run the migration script manually after deploying the Simple Commerce update.
1php please sc:migrate-order-statuses
It will generate a migration to add two new columns to the orders
table: order_status
and payment_status
. It'll then run these migrations for you.
It'll then work through the orders in your database and set the status columns. After this migration has run, the 'old' status columns will be set to null
.
You may create your own migration to remove the 'old' columns after deploying if you wish (is_paid
, is_shipped
, is_refunded
).
{{ sc:checkout }}
form
High: Variables are passed differently into the Sometimes, you could run into issues with the {{ sc:checkout }}
form where variables for one gateway would leak over into the other because they were sharing the same "space" for their variables.
In v5, we've slightly changed the format variables are passed into the {{ sc:checkout }}
form to prevent this from happening.
Due to the format changing, you may need to update code in your checkout form.
- If you're getting any variables that come from gateways, you should get it from that gateway's array:
-
{{ client_secret }}
->{{ stripe:client_secret }}
-
- If you're getting config values for a gateway, you should get it from that gateway's config array:
-
{{ gateway-config:key }}
->{{ stripe:config:key }}
-
- If you're getting the callback URL for a gateway, you should get it from that gateway's array:
-
{{ callback_url }}
->{{ stripe:callback_url }}
-
High: Stripe Gateway now defaults to Payment Elements integration
By default, Simple Commerce now takes advantage of Stripe's Payment Elements integration. This allows for customers to pick the payment methods that work for them - the payment methods are localised based on the user's location.
Any existing sites though will be using Card Elements, which just gives you a basic card payment form. To continue using in Card Elements, you'll need to specify a mode
in your Gateways config.
1// config/simple-commerce.php 2 3/* 4|-------------------------------------------------------------------------- 5| Payment Gateways 6|-------------------------------------------------------------------------- 7| 8| This is where you configure the payment gateways you wish to use across 9| your site. You may configure as many as you like.10|11| https://simple-commerce.duncanmcclean.com/gateways12|13*/14 15'gateways' => [16 \DoubleThreeDigital\SimpleCommerce\Gateways\Builtin\StripeGateway::class => [ 17 'key' => env('STRIPE_KEY'), 18 'secret' => env('STRIPE_SECRET'), 19 'mode' => 'card_elements', 20 ], 21 22 \DoubleThreeDigital\SimpleCommerce\Gateways\Builtin\DummyGateway::class => [23 'display' => 'Card',24 ],25],
Medium: Support for PHP 8.1 has been dropped
Simple Commerce has dropped support for PHP 8.1, leaving only PHP 8.2 supported.
Medium: Support for Statamic 3.3 & 3.4 has been dropped
Simple Commerce has dropped support for Statamic 3.3 and 3.4, leaving only Statamic 4.0 and above supported.
To upgrade to Statamic 4.0, you should follow the steps outlined in the official Upgrade Guide.
order_number
column for database orders
Medium: New Previously, when storing orders in the database, Simple Commerce has used the id
column as order numbers. This meant order numbers started in the single digits and it wasn't possible to set a minimum order number (eg. 1000) like you can with entry orders.
In v5, Simple Commerce has introduced a separate order_number
column. During the update process, a migration will be published & your existing orders will be updated.
Medium: Changes to Gateway API
As part of improving the developer experience in Simple Commerce, there has been some changes to the Gateways API. If you're using a custom gateway in your project, you will need to make some manual changes, as detailed below.
If you're using a built-in gateway, you don't need to worry about these changes.
prepare
- The parameters for this method have changed. It now accepts
$request
and$order
parameters, instead of aPrepare
object. - This method no longer returns a
Response
, instead it simply returns an array.
purchase
- This method has been renamed
checkout
- The parameters for this method have changed. It now accepts
$request
and$order
parameters, instead of aPrepare
object. - This method no longer returns a
Response
, instead it simply returns an array.
purchaseRules
- This method has been renamed
checkoutRules
purchaseMessages
- This method has been renamed
checkoutMessages
getCharge
- This method has been removed. It wasn't used by Simple Commerce anywhere so it didn't make sense to keep it.
- If you use it inside your gateway's class, you can keep it.
refundCharge
- This method has been renamed
refund
- This method now returns an
array
. The contents of which will be saved to the order's gateway data for future reference.
paymentDisplay
- This method has been renamed
fieldtypeDisplay
Low: Control Panel Nav
Previously, Simple Commerce would use custom JavaScript to re-order your Control Panel navigation to place the 'Simple Commerce' section under 'Content'.
However, after the introduction of the CP Nav Customiser in Statamic 3.4, you may now customise the order of the Control Panel Nav as you'd like.
For continuity, we've set your 'default preferences' for the CP Nav to how it was before. However, you're free to change this.
ReceiveGatewayWebhook
event has been renamed
Low: If you are listening to the ReceiveGatewayWebhook
anywhere in your site, you should instead listen for GatewayWebhookReceived
. The event has been renamed