Shopping Cart and Order System

Purpose and Scope

The Shopping Cart and Order System manages the complete customer purchase flow from product selection through order completion. This includes cart operations, multi-step checkout, order creation, plugin integration for shipping/payment/totals, and post-order processing including email notifications.

This page covers the cart management architecture, the 8-step checkout process, order creation, and integration with payment/shipping plugins. For customer account management and authentication, see Customer Management. For product catalog and display logic, see Product Management System. For the plugin architecture details, see Plugin and Extension System.

---

Cart Management Architecture

The cart system uses the CartService class to manage multiple cart instances (default cart, wishlist, compare). Cart data is stored in session and the database table shop_shoppingcart with store_id isolation for multi-vendor support.

Cart Service Overview

Sources: src/Controllers/ShopCartController.php12 src/Controllers/ShopCartController.php684-746 src/Controllers/ShopCartController.php754-868

Cart Data Structure

Each cart item contains:

• id: Product ID
• name: Product name
• qty: Quantity
• storeId: Store/vendor ID for multi-vendor support
• options: Product attributes/configurations (optional)
• rowId: Unique row identifier for updates/deletions

The cart groups items by storeId to support multi-vendor checkouts where each vendor processes separately.

Sources: src/Controllers/ShopCartController.php728-735 src/Controllers/ShopCartController.php98-103

---

Checkout Process Flow

The checkout process follows an 8-step flow with session state management and validation at each stage. The controller uses step numbers in comments to track the progression.

8-Step Checkout Flow Diagram

Sources: src/Controllers/ShopCartController.php27-73 src/Controllers/ShopCartController.php79-132 src/Controllers/ShopCartController.php143-302 src/Controllers/ShopCartController.php311-404 src/Controllers/ShopCartController.php416-512 src/Controllers/ShopCartController.php521-677

Step-by-Step Breakdown

Step 01-02: Cart Display and Preparation

Step	Method	Route	Session Data Set	Purpose
01.1	getCartFront()	cart	Clears session	Display cart grouped by store
01.2	_getCart()	-	-	Render cart view with attribute groups
02	prepareCheckout()	cart.prepare_checkout	storeCheckout	Validate quantities, check minimum order

Sources: src/Controllers/ShopCartController.php35-73 src/Controllers/ShopCartController.php80-132

Step 03-04: Checkout Form and Validation

Step	Method	Session Data Set	Validation
03.1	getCheckoutFront()	-	Check storeCheckout exists
03.2	_getCheckout()	dataCheckout, shippingAddress (default)	Load plugins, prepare address
04	processCheckout()	shippingMethod, paymentMethod, address_process, shippingAddress	Dynamic validation via gp247_order_mapping_validate()

The validation in Step 04 is configuration-driven. Fields like last_name, address1-3, phone, country, postcode, company are validated only if enabled in config with gp247_config('customer_*').

Sources: src/Controllers/ShopCartController.php143-302 src/Controllers/ShopCartController.php311-404 src/Library/Helpers/order.php90-210

Step 05-06: Confirmation and Order Creation

Sources: src/Controllers/ShopCartController.php432-512 src/Controllers/ShopCartController.php521-677

---

Order Data Model

The order creation process in Step 06 constructs a comprehensive order record with totals breakdown and line items.

Order Record Structure

Sources: src/Controllers/ShopCartController.php559-615 src/Controllers/ShopCartController.php617-631

Order Total Calculation

Order totals are calculated through plugins implementing the "total" type. The system processes them in sort order:

Sources: src/Controllers/ShopCartController.php270 src/Controllers/ShopCartController.php487-488 src/Controllers/ShopCartController.php549-557

---

Cart Operations

Adding Products to Cart

The system provides two methods for adding products:

Method	Type	Use Case	Route
addToCart()	POST	Product detail page with form submission	cart.add
addToCartAjax()	AJAX	Quick add from product list	cart.add_ajax

Both methods perform validation:

1. Product exists and is available for the store
2. Product allows sale (stock check if product_buy_out_of_stock disabled)
3. Required attributes selected (if product has attributes)
4. Not a GROUP product type (requires detail page selection)

Sources: src/Controllers/ShopCartController.php684-746 src/Controllers/ShopCartController.php754-868

Multi-Vendor Cart Handling

For multi-vendor installations:

Sources: src/Controllers/ShopCartController.php694-713 src/Controllers/ShopCartController.php767-791 src/Controllers/ShopCartController.php98-103

Cart Instances: Default, Wishlist, Compare

The CartService supports multiple named instances:

Instance	Purpose	Operations	Display Route
default	Shopping cart	Add with attributes, quantity updates, checkout	cart
wishlist	Saved items	Add without quantity, one per product	wishlist
compare	Product comparison	Add without quantity, one per product	compare

Sources: src/Controllers/ShopCartController.php762-767 src/Controllers/ShopCartController.php793-857 src/Controllers/ShopCartController.php919-951 src/Controllers/ShopCartController.php959-992

---

Plugin Integration Points

The checkout process integrates with three plugin types at specific steps:

Plugin Loading and Execution

Sources: src/Controllers/ShopCartController.php176-213 src/Controllers/ShopCartController.php352-359 src/Controllers/ShopCartController.php669-676

Payment Plugin Integration

Payment plugins must implement:

• AppConfig::getInfo() - Return plugin display information
• FrontController::processOrder() - Process payment after order creation

The controller checks for existence before calling:

Sources: src/Controllers/ShopCartController.php669-676

---

Session Management

The checkout process relies heavily on session state to maintain data across steps:

Session Variables

Session Key	Set In Step	Used In Step	Contains
storeCheckout	02	03, 04, 05, 06	Store ID for current checkout
dataCheckout	03	04, 05, 06	Cart items for checkout
shippingAddress	03 (default), 04 (submitted)	04, 05, 06	Customer address data
shippingMethod	04	05, 06	Selected shipping plugin key
paymentMethod	04	05, 06	Selected payment plugin key
address_process	04	06	'new' or 'existing' address
dataTotal	05	06	Calculated order totals
orderID	06	07, 08	Created order ID
dataOrder	06	08	Order main data
arrCartDetail	06	08	Order line items

Sources: src/Controllers/ShopCartController.php129 src/Controllers/ShopCartController.php174 src/Controllers/ShopCartController.php269 src/Controllers/ShopCartController.php352-383 src/Controllers/ShopCartController.php491 src/Controllers/ShopCartController.php641-645

Session Cleanup

The system clears session data at specific points:

• Step 01: Clears all checkout session on cart view via clearSession()
• After order completion: Session is maintained for post-order processing (email)

Sources: src/Controllers/ShopCartController.php52

---

Validation System

Dynamic Configuration-Driven Validation

The order validation is dynamically constructed based on configuration settings via gp247_order_mapping_validate():

Sources: src/Library/Helpers/order.php90-210 src/Controllers/ShopCartController.php329-349

Quantity Validation

Product minimum order quantities are validated at two points:

1. Step 02 - Before checkout preparation
2. Step 04 - Before checkout confirmation

The validation aggregates quantities across multiple cart rows for the same product:

Sources: src/Controllers/ShopCartController.php105-126 src/Controllers/ShopCartController.php386-401

---

Email Notifications

Post-order email notifications are triggered in the final step via gp247_order_process_after_success().

Email Flow

Sources: src/Library/Helpers/order.php8-84

Email Content Structure

Both admin and customer emails include:

Data Field	Source	Format
orderID	Order ID	String
toname	first_name + last_name	String
address	address1 + address2 + address3	String
phone	Order phone	String
comment	Order comment	String
currency	Order currency code	String
orderDetail[]	Order details with product info	Array of items
subtotal	Rendered with currency	String
shipping	Rendered with currency	String
discount	Rendered with currency	String
otherFee	Rendered with currency	String
total	Rendered with currency	String

Email views are resolved using gp247_shop_process_view() to support template customization.

Sources: src/Library/Helpers/order.php32-81 src/Views/front/email/order_success_to_admin.blade.php1-67 src/Views/front/email/order_success_to_customer.blade.php1-67

---

Cart Display and UI Integration

Product Detail Page Integration

The product detail page includes a form that posts to the cart add endpoint:

For products with attributes, the form includes attribute selection fields rendered by $product->renderAttributeDetails().

Sources: src/Views/front/screen/shop_product_detail.blade.php61-93 src/Views/front/screen/shop_product_detail.blade.php96-104

AJAX Cart Operations

Product listing pages use AJAX for quick add operations:

Sources: src/Views/front/common/shop_js.blade.php3-38 src/Views/front/common/shop_product_single.blade.php15 src/Views/front/common/shop_product_single.blade.php32

Cart Count Display

The system updates cart counts dynamically in the UI using class selectors:

• .gp247-cart - Default cart count
• .gp247-wishlist - Wishlist count
• .gp247-compare - Compare count

Sources: src/Views/front/common/shop_js.blade.php20-24

---

Error Handling and Edge Cases

Stock Validation

When updating cart quantities, the system checks:

Sources: src/Controllers/ShopCartController.php896-902

Guest Checkout Control

Guest checkout is controlled by configuration:

This check occurs at:

• Step 02: Prepare checkout
• Step 04: Process checkout
• Step 06: Add order

Sources: src/Controllers/ShopCartController.php84-87 src/Controllers/ShopCartController.php322-325 src/Controllers/ShopCartController.php531-534

Plugin Validation

Before using plugins in Step 05, the system validates they are enabled:

Sources: src/Controllers/ShopCartController.php450-452 src/Controllers/ShopCartController.php469-471

Duplicate Item Prevention

For wishlist and compare instances, the system prevents duplicates:

Sources: src/Controllers/ShopCartController.php829-855

---

Key Controller Methods Reference

Method	Route	HTTP	Purpose
getCartFront()	cart	GET	Display shopping cart
prepareCheckout()	cart.prepare_checkout	POST	Validate cart and prepare checkout
getCheckoutFront()	checkout	GET	Display checkout form
processCheckout()	checkout.process	POST	Validate and save checkout data
getCheckoutConfirmFront()	checkout.confirm	GET	Display order confirmation
addOrder()	checkout.order	POST	Create order record
completeOrder()	checkout.complete	GET	Finalize and send emails
addToCart()	cart.add	POST	Add product from detail page
addToCartAjax()	cart.add_ajax	POST	Add product via AJAX
updateToCart()	cart.update	POST	Update cart quantity
wishlistProcessFront()	wishlist	GET	Display wishlist
compareProcessFront()	compare	GET	Display compare list

Sources: src/Controllers/ShopCartController.php35 src/Controllers/ShopCartController.php80 src/Controllers/ShopCartController.php143 src/Controllers/ShopCartController.php311 src/Controllers/ShopCartController.php416 src/Controllers/ShopCartController.php521 src/Controllers/ShopCartController.php684 src/Controllers/ShopCartController.php754 src/Controllers/ShopCartController.php875 src/Controllers/ShopCartController.php919 src/Controllers/ShopCartController.php959