Cart, Checkout and Orders

A cart is a row of ps_cart plus its lines in ps_cart_product, and it exists as soon as the first product is added: a visitor who is not logged in gets a cart without a customer (only an id_guest), and a cart is attached to the customer when the customer logs in or creates an account. A browser cookie remembers which cart belongs to a visitor, so the cart survives for as long as the front-office cookie does (Configure, Advanced parameters, Administration, "Lifetime of front office cookies"). When a customer signs in with an empty cart and has an earlier cart that was never ordered, the shop restores the most recent one if the setting "Re-display cart at login" (configuration key PS_CART_FOLLOWING) is on, which is the default.

Source: PrestaShop devdocs: Order lifecycle (Cart, Checkout and Order)

The columns of ps_cart that matter for the rest of the page are:

Source: PrestaShop 9.2.0: classes/Cart.php

The amounts of a cart are always read through Cart::getOrderTotal($withTaxes, $type, $products, $idCarrier), and the $type decides which part of the total is returned. The constants are on the Cart class.

The Pocket Coffee cart of the test (three bags of Ethiopia whole bean 250 g, one Colombia filter 1 kg bag and the starter kit, for the Coffee Club member in Madrid) totalled 91.33 before discounts, 83.65 after the two automatic cart rules, and 88.35 with the 4.70 of the roastery pickup carrier added in the delivery step. The same cart is built by a script in the next sections, with no browser.

The cart presenter (CartPresenter) turns the cart into the array that Smarty templates read; the hooks actionPresentCart and actionPresentCartProduct let a module change it, actionCartSave runs when the cart is saved, actionCartUpdateQuantityBefore before a quantity changes, actionUpdateCartAddress when an address of the cart is replaced and actionCartSummary when the summary used by payment modules is built. Products leave the cart for the order only in validateOrder(); the cart row itself is kept (it is how an order finds its cart, Order::getIdByCartId()), and Cart::orderExists() is the test that a cart has already become an order.

The page /order is served by OrderController. On every request it builds a CheckoutProcess, restores the progress stored in the cart, lets the process handle the request parameters, decides whether the customer must go back to the cart, and renders the current step. The classes are in classes/checkout/.

Source: PrestaShop 9.2.0: classes/checkout

The steps run in order, and a step becomes reachable only when the one before it is complete. The delivery step is added only when the cart is not virtual (Cart::isVirtualCart()); the personal information, addresses and payment steps are always there, which the test confirmed with a cart that held only the virtual workshop ticket of the previous page: three steps, with the delivery step missing (the devdocs say that the addresses step is skipped for virtual carts too, but the 9.2.0 source adds it unconditionally and the storefront asked for the invoice address). Each step handles its own request parameters:

Two things happen on every request that the steps do not see. First, restorePersistedData() reads ps_cart.checkout_session_data and applies it only if the checksum stored in it equals the checksum of the cart now. CartChecksum is a SHA-1 over the shop, customer, guest, currency, language, both addresses and, for every line, the product, combination, quantity and tax-included total; so any change of those values discards the saved progress and the customer is taken back to the first step that is not complete. The test showed it: after the delivery option had been chosen, adding one more product to the cart made /order open on the addresses step again, with the delivery step not reachable. Second, OrderController redirects to the cart page (where CartController shows the reason) when the cart is empty, when the minimum purchase amount is not reached, when a product is out of stock or no longer available for ordering, when a product is below its minimal quantity, or when an address uses a disabled country. Enable a country before using an address in it (International, Locations, Countries); Spain and Germany are disabled in a fresh installation, and they were enabled for the test.

Hooks around the process: actionCheckoutRender receives the process by reference after it was built (a module can add or replace a step), actionCheckoutStepRenderTemplate runs before each step template is rendered, actionCheckoutBuildProcess (new in 9.2) lets a module replace the whole process, actionPresentPaymentOptions receives the payment options before they are shown, actionFilterDeliveryOptionList filters the delivery options, displayBeforeCarrier and displayAfterCarrier add HTML before and after the carrier list, displayCarrierExtraContent adds content for one carrier (pickup points, for example), displayPaymentTop runs at the top of the payment step, displayPaymentByBinaries carries the payment form generated by binary payment options, displayCheckoutBeforeConfirmation shows custom content before the order is confirmed and displayExpressCheckout is where express payment buttons appear in the cart (Hummingbird renders it in cart-detailed-actions.tpl). All of these exist in the 9.2.0 hook table.

Source: PrestaShop devdocs: actionCheckoutRender

PrestaShop 9.2 includes a module, ps_onepagecheckout, that replaces the four steps with one page: contact, addresses, delivery and payment in a single form, refreshed by AJAX. In the 9.2.0 image the module is installed and enabled but the checkout stays native, because the configuration key PS_ONE_PAGE_CHECKOUT_ENABLED is 0; the merchant switches it on in the back office, and the module reads and writes the key. The module is 0.x software (0.6.7 in the image, pinned in the core composer.json), which is worth knowing before relying on it.

The integration is a hook, not an override. OrderController::buildCheckoutProcess() asks the CheckoutProcessProviderResolver for a process before it builds the native one. The resolver runs the hook actionCheckoutBuildProcess for every module, keeps the values that are CheckoutProcessProviderInterface instances and report isEnabled(), and uses the provider only if exactly one is left. With none, with several, or with a provider whose buildCheckoutProcess() does not return a CheckoutProcess, the native process runs, so a broken module cannot break the checkout.

Source: PrestaShop devdocs: One Page Checkout for module developers

With the key set to 1 for the duration of one request, the shop served the single page. The markup carries one form, opc-form, with the sections js-opc-contact-section, js-opc-addresses-section, js-opc-delivery-section and js-opc-payment-section; the payment modules appear as the same payment-option entries with the same fallback forms that post to the validation controllers (/module/ps_wirepayment/validation and the others); and the page defines a JavaScript object window.ps_onepagecheckout with enabled, taxAddressType, persistAddressDraft, buyerIdentified, the translated messages, and the URL of every AJAX endpoint: guestInit, addressForm, addressModal, addressesList, states, saveAddress, saveDraft, deleteAddress, carriers, selectCarrier, paymentMethods, selectPayment, opcSubmit, giftWrapping, cartTotals and selectAddress. The key was set back to 0 right after the request, and no order was placed through the single page: that path was not exercised.

What module authors have to do is small and documented. A payment module that returns normal PaymentOption objects works unchanged; a module that injects JavaScript into the carrier or payment sections must re-run it when the section is refreshed (the events opcCarriersLoading, opcCarriersUpdated and opcPaymentMethodsUpdated on the prestashop event bus), and a module that submits its own payment (binary options, smart buttons, redirects) must call window.ps_onepagecheckout.submitBeforePayment() first so that the customer, address and delivery method are saved before its flow takes over. OnePageCheckoutAvailability is the single place that reads PS_ONE_PAGE_CHECKOUT_ENABLED; the template variable is_one_page_checkout_enabled stays available to themes.

Source: PrestaShop devdocs: One Page Checkout for theme developers

Every payment module ends the same way: it calls PaymentModule::validateOrder(), and that one method creates the order. Knowing what it does explains most "my order is wrong" questions, and it is also the contract that payment modules have to respect, so the steps are listed here in the order the 9.2.0 source runs them.

Source: PrestaShop 9.2.0: PaymentModule::validateOrder()

PrestaShop 9.1 introduced shipments: one order that is delivered in several parcels, each with its own carrier, cost and tracking number. The feature is behind the flag improved_shipment (disabled by default, "work in progress" in the devdocs), and the ground rules are: enable the flag with php bin/console prestashop:feature-flag enable improved_shipment, test your payment and carrier modules with it on, and expect changes in later releases. With the flag on, OrderController uses a DeliveryOptionsProvider instead of the DeliveryOptionsFinder, and validateOrder() creates a single order and a row of ps_shipment per carrier, with the lines of the order in ps_shipment_product.

The same two-carrier cart gave this result (order 12, reference FSKTCIOYD, flag enabled for the duration of the request):

The differences that matter to code: ps_orders.id_carrier is 0 (the carriers are in the shipments), the shipping cost of each parcel is in ps_shipment, a shipment has its own packed_at, shipped_at, delivered_at, cancelled_at and tracking_number, and a virtual product is left out of the shipments. The hook actionGetOrderShipments lets a module change the shipments of an order. One more oddity of the run: the weight stored in the ps_order_carrier row of carrier 6 was 0.75 kg although its parcel (three 250 g bags and a 1 kg bag) weighs 1.75 kg, while the same cart ordered with the flag off stored 1.75; the 0.90 kg of the other parcel was right. The flag was switched on and off by the console for each experiment and left disabled. The feature is described in the project blog post that the devdocs link, but its developer documentation had not been written at the check date, so code that reads ps_orders.id_carrier should be reviewed before the flag is enabled in production.

Source: PrestaShop devdocs: Changes in 9.1.x (multi-shipment system)

An order state is a row of ps_order_state with a name per language, and it is the only status an order has. Moving an order to another state is done by adding an OrderHistory row; the history is the audit trail, and ps_orders.current_state is a copy of the latest row. The back office command UpdateOrderStatusCommand (and the legacy OrderHistory::changeIdOrderState()) refuses only a change to the state the order already has; the core does not enforce a sequence, so "Delivered" can be set on an order that was never paid. The sequence is a convention, and the states that module and merchants add are free to fit in anywhere.

The customer sees the order on the confirmation page (order-confirmation, which renders the hooks displayOrderConfirmation, displayOrderConfirmation1, displayOrderConfirmation2 and, for the payment module, displayPaymentReturn) and in the account under "Order history", whose detail page renders displayOrderDetail and displayOrderDetailProductLine. The history shown to the customer leaves out the states flagged hidden. In the back office the employee uses Sell, Orders; the order page has the hooks displayAdminOrder, displayAdminOrderMain, displayAdminOrderSide, displayAdminOrderTop and the tab hooks, and actionGetAdminOrderButtons adds buttons. A module that must act on every order should use the hooks of this page, not the pages of the back office, because orders are also created by the Admin API clients and by the Webservice.

Run on PrestaShop 9.2.0 in Docker (Apache 2.4.68, PHP 8.5.12, MySQL 8.4; Hummingbird 2.1.2; ps_onepagecheckout 0.6.7): the cart, address, delivery and payment steps of the real storefront through curl for a logged-in customer (a dozen orders with the three offline payment modules and the example payment module, with one carrier, with two carriers, and with a carrier module); the cart and cart rule totals; the One Page Checkout page rendered for one request; the multi-shipment flag enabled for one checkout; the order states 2 to 5 on a real order and 6, 3 and 7 on another with the stock figures read from the database; the hooks of the module pcffcheckout (installed, executed, log read back); a virtual-only cart.

Not run: an order placed through the One Page Checkout page, a guest checkout (the forms were not submitted), the back-office order page and its status dropdown (the same command was used from the console), the e-mails (no mail transport, PS_MAIL_METHOD was set to "never send" during the run and restored), the PDF invoice and delivery slip rendering, credit slips and merchandise returns, and the Admin API operations on orders (the Admin API of 9.2.0 has no order resource other than order messages, order returns and their states).