v5.0: Improve DX of Gateways

[duncanmcclean]

This pull request aims to improve the developer experience around building custom payment gateways.

The signatures for gateway methods have changed. Instead of dealing with custom objects, you're now dealing with simple arrays.

For developers building gateways for the first time, the Gateway contract now includes some documentation about each of the methods in docblocks.

Upgrade Guide

As part of improving the developer experience, there's been some changes the API for implementing custom gateways.

If you're using a custom gateway, you will need to make some manual changes:

prepare

• The parameters for this method have changed. It now accepts $request and $order parameters, instead of a Prepare 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 a Prepare 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

To Do

• [x] Update documentation around writing custom gateways
• [x] Add notes to upgrade guide
• [x] Update on-site/off-site stubs
• [x] Save returned array of refund method for future reference
• [x] Implement any other TODOs

[github-actions[bot]]

Released as part of v5.0.0.