Commerce Commerce 1.x Upgrades v1.1

Most upgrades are automatically applied, but sometimes you may need to update custom templates, or configuration, to take advantage of new features or improvements. Those changes are discussed here.

Commerce v1.1 introduces new features and developer tools/utilities, but also cleans up legacy code that was marked as deprecated before v1.0.

v1.1 also bumps the minimum PHP version to 7.1 as a hard requirement, we’ve incorporated PHP 7.1 features in this release that will break on earlier versions of PHP. When upgrading, the installer will stop automatically if you run a too old version of PHP.

Items marked [Technical] only affect module developers. Other items may require action on implementations.

#New infinite stock

It’s now possible to set a product to have infinite stock. To use this in your product templates, see the product stock documentation.

#Updated Stripe, Braintree and Mollie Gateways

The Stripe, Braintree and Mollie gateways have received major updates.

• Stripe now uses Payment Intents, which are SCA-ready, supporting 3D Secure and the latest checkout flow for credit cards.
• Braintree now uses the Drop-in UI v3, also SCA-ready and supports vaulting credit card/paypal accounts for quicker payment for repeat customers (only for logged in users).
• Mollie can now show more issuers and options on-site, including a new “show” value for the payment option selection that will show all enabled payment methods and their respective issuers in a single view. The default CSS also includes some new styling for this.

For SCA-readiness of the different gateways we offer, see the payment methods overview.

#invoice/web.twig minor tweaks

To make sure the img tag is only created when a logo URL is set, change:

<img src="{{ logo_url }}" style="width: 33%" />

on line 76 to:

{% if logo_url != '' %}<img src="{{ logo_url }}" style="width: 33%" />{% else %}{{ site_name }}{% endif %}

To align the invoice meta block right, add these styles around line 62:

table.cells-align-right td, table.cells-align-right th {
    text-align: right;
}

and add the cells-align-right class to the <table class="layout"> around line 95.

To use the right order date, replace:

<th>{{ data.order.created_on|date('Y-m-d') }}</th>

around line 102 with:

<th>{{ data.order.received_on|date('Y-m-d') }}</th>

#[Technical] PriceTypeInterface (breaking) changes

To make it possible to have more powerful select fields on price types, the getFields method signature changed.

This is a breaking change and any custom price type will need to be updated - which luckily is very quick to do.

Previous:

public static function getFields();

New:

public static function getFields(\Commerce $commerce);

#[Technical] Twig abstracted into new View classes

To avoid future breaking changes, we’ve deprecated direct access to Twig (previously via $commerce->twig/$commerce->loadTwig()) and have implemented a new ViewInterface/TwigView. You can learn more about how to use the ViewInterface in the documentation.

To access the new View class, use $commerce->view(). On the resulting object (guaranteed to be there, so can be chained), you can use render($template, $placeholders), renderString($stringTemplate, $placeholders) and addTemplatesPath($absolutePath) methods.

Modules that add custom loaders to Twig should rewrite to addTemplatesPath and any code that renders twig templates should refactor to the new render and renderString methods.

We will keep the legacy $twig variable around until at least v1.3 to give you time to migrate.

The modmore\Commerce\Pricing\Renderer\TwigRenderer class accepts either a \Twig\Environment or a ViewInterface instance for now; support for \Twig\Environment will be removed in v1.3.

#[Technical] New Payment Gateway implementations

In v1.1 we’ve incorporated a brand new way of building payment gateways. The pre-1.1 based exclusively on Omnipay still works, and will continue to work for the time being, but new gateways should be based on the new classes and interfaces and we’d encourage migrating if there are user benefits to be gained from the more flexible integration.

#[Technical] comShippingMethod and comOrderShipment changes

To support more powerful shipping implementations, a couple of additions and changes have been made to shipping methods and order shipments.

To clarify, a shipping method controls the pricing and customer selection, while the order shipment controls the delivery and merchant interaction. You’ll often need both for more complex integrations.

• comOrderShipment.setShippingMethod signature change. Previously public function setShippingMethod(comShippingMethod $method) with a void return, now public function setShippingMethod(comShippingMethod $method, array $data = []) with a true|string|void return value. When the return is a string, that is considered an error message that will be shown to the customer.
• New comShippingMethod.getShippingForm(comOrder $order, comOrderShipment $shipment): string method, allowing you to generate a form shown to the customer. Is automatically called and added to the pre-existing {{ method.gateway_form }} placeholder in shipping-method.twig. The getShippingForm() method may throw a ViewException if it can’t be rendered, which will discard the shipping method as an available option.
• New comOrderShipment.getShipmentDetails(): array method to define key => value pairs of additional shipping information to show in the order items grid.
• New comOrderShipment.getTrackingURL(): string method to define a track and trace URL, available both to the merchant in the order view and in outgoing emails.

#[Technical] Removed deprecated/defunct code

If you’re using any of the constants, methods, variables, or classes detailed below, your code may break and cause a fatal error or warning (depending on context) when upgrading to v1.1.

Most of these deprecations date back to v0.8-v0.10 and were originally planned for removal in 1.0.

Removed deprecated event constants:

• comAddress::EVENT_VALIDATE, use Commerce::EVENT_ADDRESS_VALIDATE
• comOrder::EVENT_BEFORE_CALCULATE, use Commerce::EVENT_ORDER_BEFORE_CALCULATE
• comOrder::EVENT_AFTER_CALCULATE, use Commerce::EVENT_ORDER_AFTER_CALCULATE
• comOrder::EVENT_ITEM_ADDED, use Commerce::EVENT_ORDERITEM_ADDED
• comOrder::EVENT_ITEM_UPDATED, use Commerce::EVENT_ORDERITEM_UPDATED
• comOrder::EVENT_ITEM_REMOVED, use Commerce::EVENT_ORDERITEM_REMOVED
• comOrder::EVENT_BEFORE_STATUS_CHANGE, use Commerce::EVENT_ORDER_BEFORE_STATUS_CHANGE
• comOrder::EVENT_AFTER_STATUS_CHANGE, use Commerce::EVENT_ORDER_AFTER_STATUS_CHANGE
• comOrder::EVENT_AFTER_PAYMENT_RECEIVED, use Commerce::EVENT_TRANSACTION_COMPLETED
• comOrder::EVENT_GET_ORDER_ACTIONS, use Commerce::EVENT_ORDER_GET_ACTIONS, use Commerce::EVENT_DASHBOARD_ORDER_ACTIONS
• comOrder::EVENT_CART_TO_PROCESSING_STATE, use Commerce::EVENT_STATE_CART_TO_PROCESSING
• comOrder::EVENT_CART_TO_CANCELLED_STATE, use Commerce::EVENT_STATE_CART_TO_CANCELLED
• comOrder::EVENT_PROCESSING_TO_COMPLETED_STATE, use Commerce::EVENT_STATE_PROCESSING_TO_COMPLETED
• comOrder::EVENT_PROCESSING_TO_CANCELLED_STATE, use Commerce::EVENT_STATE_PROCESSING_TO_CANCELLED
• comOrderAddress::EVENT_ADDED, use Commerce::EVENT_ORDER_ADDRESS_ADDED
• comOrderItem::EVENT_BEFORE_CALCULATE, use Commerce::EVENT_ORDERITEM_BEFORE_CALCULATE
• comOrderItem::EVENT_AFTER_CALCULATE, use Commerce::EVENT_ORDERITEM_AFTER_CALCULATE
• Commerce::EVENT_ORDER_GET_ACTIONS, use Commerce::EVENT_DASHBOARD_ORDER_ACTIONS
• Commerce::EVENT_DASHBOARD_GET_PAGES, use Commerce::EVENT_DASHBOARD_INIT_GENERATOR
• modmore\Commerce\Admin\Generator::COLLECT_PAGES_EVENT, use Commerce::EVENT_DASHBOARD_GET_PAGES
• modmore\Commerce\Admin\Generator::COLLECT_MENU_EVENT, use Commerce::EVENT_DASHBOARD_GET_MENU
• modmore\Commerce\Admin\Page::EVENT_BEFORE_GENERATE, use Commerce::EVENT_DASHBOARD_PAGE_BEFORE_GENERATE
• modmore\Commerce\Admin\Configuration\Checklist::EVENT_GET_CHECKS, use \Commerce::EVENT_DASHBOARD_CHECKLIST_GET_CHECKS
• modmore\Commerce\Frontend\Checkout\Process::BEFORE_PROCESS_STEP, use \Commerce::EVENT_CHECKOUT_BEFORE_STEP
• modmore\Commerce\Frontend\Checkout\Process::AFTER_PROCESS_STEP, use \Commerce::EVENT_CHECKOUT_AFTER_STEP
• modmore\Commerce\Reports\ReportInterface::EVENT_GET_REPORTS, use \Commerce::EVENT_DASHBOARD_REPORTS_GET_REPORT
• modmore\Commerce\Taxes\RateProvider::COLLECT_RATE_PROVIDERS = \Commerce::EVENT_DASHBOARD_GET_RATE_PROVIDERS

Removed deprecated methods/variables:

• modmore\Commerce\Frontend\Steps\Shipping::getShipments - replaced by comOrder::getShipments
• modmore\Commerce\Frontend\Steps\Shipping::getItemsByDeliveryType - replaced by comOrder::getShipments
• comOrder::getItemsByDeliveryType() - replaced by comOrderShipment objects
• comOrder::$_itemsByDeliveryType
• comOrder::getShippingPrice() - replaced by comOrderShipment objects
• comOrder::setShippingMethod($methodId) - replaced by a shipping method being set on the order shipment
• comOrder::removeAddress($address) - simply remove the comOrderAddress record or use removeAddressType instead
• comAddress::getTextSummary() - use Commerce::formatAddress
• comOrderAddress::getAddress() - use the comOrderAddress information directly
• comShippingMethodByWeight::getTotalOrderWeight($order) - use comOrderShipment->getWeight() instead
• Commerce\Events\Address->getAddress() - use information from getOrderAddress() instead
• Commerce\Events\Address->getAddressJoin() - use information from getOrderAddress() instead
• Commerce\Events\AddressValidation::getOrder()
• modmore\Commerce\Frontend\Checkout\Process::completeOrder - replaced by comOrder::triggerPaidStatusChange
• modmore\Commerce\Modules\Discounts::loadPage() - replaced by initGenerator()

Removed classes:

• modmore\Commerce\Frontend\Requirements\ShippingMethod - replaced with modmore\Commerce\Frontend\Requirements\ShipmentsWithMethod
• modmore\Commerce\Frontend\Checkout\NoAccount, OnePage, and RequiresAccount, replaced by configuration on Standard checkout process

Other changes from cleaned up deprecated functionality:

• Commerce\Events\AddressValidation constructor no longer accepts a comOrder
• modmore\Commerce\Pricing\PriceType\Quantity no longer accepts [prices:[..]] instead of [..] serialised data
• Checkout templates no longer have a shipping_method placeholder