Events and plugins
MiniShop3 runs on the MODX event system. A plugin steps into cart, order, product and customer processing without changing the source code.
Getting started
- Working with plugins — how to get parameters, abort an operation, modify data, pass data between plugins
Events by category
Cart
| Event | Description |
|---|---|
| msOnBeforeGetCart | Before getting cart |
| msOnGetCart | After getting cart |
| msOnBeforeAddToCart | Before adding product |
| msOnAddToCart | After adding product |
| msOnBeforeChangeInCart | Before changing quantity |
| msOnChangeInCart | After changing quantity |
| msOnBeforeChangeOptionsInCart | Before changing options |
| msOnChangeOptionInCart | After changing options |
| msOnBeforeRemoveFromCart | Before removing product |
| msOnRemoveFromCart | After removing product |
| msOnBeforeEmptyCart | Before clearing cart |
| msOnEmptyCart | After clearing cart |
| msOnGetStatusCart | Getting cart status |
Order
| Event | Description |
|---|---|
| msOnBeforeAddToOrder | Before adding field to order |
| msOnAddToOrder | After adding field |
| msOnBeforeValidateOrderValue | Before field validation |
| msOnValidateOrderValue | After field validation |
| msOnErrorValidateOrderValue | Validation error |
| msOnBeforeRemoveFromOrder | Before removing field |
| msOnRemoveFromOrder | After removing field |
| msOnBeforeEmptyOrder | Before clearing order draft |
| msOnEmptyOrder | After clearing order draft |
| msOnSubmitOrder | Frontend order submit |
| msOnBeforeMgrCreateOrder | Before manager finalization |
| msOnMgrCreateOrder | After manager finalization |
| msOnBeforeCreateOrder | Before creating order |
| msOnCreateOrder | After creating order |
Cost
| Event | Description |
|---|---|
| msOnBeforeGetCartCost | Before cart cost calculation |
| msOnGetCartCost | After cart cost calculation |
| msOnBeforeGetDeliveryCost | Before delivery cost calculation |
| msOnGetDeliveryCost | After delivery cost calculation |
| msOnBeforeGetPaymentCost | Before payment fee calculation |
| msOnGetPaymentCost | After payment fee calculation |
| msOnBeforeGetOrderCost | Before order total (cart + delivery + payment) |
| msOnGetOrderCost | After total: override cost / cart_cost / delivery_cost / payment_cost |
Order status
| Event | Description |
|---|---|
| msOnBeforeChangeOrderStatus | Before status change |
| msOnChangeOrderStatus | After status change |
Customer
| Event | Description |
|---|---|
| msOnBeforeGetOrderCustomer | Before getting customer |
| msOnGetOrderCustomer | After getting customer |
| msOnBeforeGetOrderUser | Before resolving modUser on submit |
| msOnGetOrderUser | After resolving modUser |
| msOnBeforeAddToCustomer | Before adding field |
| msOnAddToCustomer | After adding field |
| msOnBeforeValidateCustomerValue | Before field validation |
| msOnValidateCustomerValue | After field validation |
| msOnErrorValidateCustomerValue | Validation error |
| msOnBeforeCreateCustomer | Before creating customer |
| msOnCreateCustomer | After creating customer |
| msOnBeforeUpdateCustomer | Before updating customer (processor; neither the manager nor the Web API calls it yet) |
| msOnUpdateCustomer | After updating customer (processor; neither the manager nor the Web API calls it yet) |
| msOnBeforeAddCustomerAddress | Before adding address |
| msOnAddCustomerAddress | After adding address |
Products (catalog)
| Event | Description |
|---|---|
| msOnGetProductPrice | Product price modification |
| msOnGetProductWeight | Product weight modification |
| msOnGetProductFields | Product fields modification |
| msOnGetPublicSeo | After the public SEO set is assembled (PublicSeoService, ms3_public_seo_tv_map) |
msProducts snippet
Events for integrating third-party packages (ms3Variants, msBrands and others) without changing core code.
| Event | Description |
|---|---|
| msOnProductsLoad | After product list is loaded (bulk loading) |
| msOnProductPrepare | Preparing each product's data |
usePackages parameter
To enable data loading, pass the package name in the snippet parameter: &usePackages='ms3Variants,msBrands'
Order products
| Event | Description |
|---|---|
| msOnBeforeCreateOrderProduct | Before adding product to order |
| msOnCreateOrderProduct | After adding product |
| msOnBeforeUpdateOrderProduct | Before updating product |
| msOnUpdateOrderProduct | After updating product |
| msOnBeforeRemoveOrderProduct | Before removing product |
| msOnRemoveOrderProduct | After removing product |
Order model (xPDO)
| Event | Description |
|---|---|
| msOnBeforeSaveOrder | Before save (xPDO) |
| msOnSaveOrder | After save (xPDO) |
| msOnBeforeRemoveOrder | Before remove (xPDO) |
| msOnRemoveOrder | After remove (xPDO) |
| msOnBeforeUpdateOrder | Reserved — never fired (#844) |
| msOnUpdateOrder | Reserved — never fired (#844) |
Notifications
| Event | Description |
|---|---|
| msOnBeforeSendNotification | Before sending notification |
| msOnAfterSendNotification | After sending notification |
| msOnRegisterNotificationChannels | Channel registration |
Vendors
| Event | Description |
|---|---|
| msOnBeforeVendorCreate | Before creating vendor |
| msOnVendorCreate | After creating |
| msOnBeforeVendorUpdate | Before updating |
| msOnVendorUpdate | After updating |
| msOnBeforeVendorDelete | Before deleting |
| msOnVendorDelete | After deleting |
All six vendor events are fired only by the older Settings/Vendor/* processors. CRUD in the manager goes through the Manager API, and that does not call them — see vendor events and issue #847.
Import
| Event | Description |
|---|---|
| msOnBeforeImport | Before import start |
| msOnAfterImport | After import complete |
| msOnImportRow | When processing a row |
Manager
| Event | Description |
|---|---|
| msOnManagerCustomCssJs | Loading scripts and styles |
Shipments
The logic lives in ShipmentLifecycleService (ms3_shipment_lifecycle), the tables are ms3_shipments and ms3_shipment_events. Creating a shipment and setTracking work even with ms3_shipment_enabled=0, while the delivery webhook answers 404 in that case. Before-events are aborted with success=false in the invokeEvent response. The response of after-events is not read at all: an error raised by a plugin on msOnCreateShipment, msOnChangeShipmentStatus or msOnUpdateShipmentTracking neither aborts the operation nor reaches the log.
| Event | Parameters | When |
|---|---|---|
msOnBeforeCreateShipment / msOnCreateShipment | before: order_id, delivery_id; after: shipment (the record) | create() |
msOnBeforeChangeShipmentStatus / msOnChangeShipmentStatus | before: shipment, status; after: shipment | transition() / delivery provider webhook |
msOnBeforeUpdateShipmentTracking / msOnUpdateShipmentTracking | before: shipment, tracking_number; after: shipment | setTracking() / webhook on a tracking change |
Shipment statuses: preparing, shipped, in_transit, delivered, cancelled, returned, failed (ShipmentStatus).
Inventory
With ms3_inventory_enabled=1 the work is done by ProductStockInventory (ms3_inventory), the contract is InventoryServiceInterface. Event parameters: key (InventoryKey), qty, ctx (InventoryContext: orderId, origin — defaults to 'order', holdState — defaults to null). A before-event returning success=false raises an InventoryException (ms3_err_inventory_cancelled). Passing $notify=false to reserve and release skips the event pair — compensation happens inside the SQL transaction.
Inventory after-events abort the operation too
Reserve, commit and release share one dispatch method, so success=false in an after-event raises the same InventoryException — after the database write. An output() in msOnInventoryCommit breaks the status change when the stock decrement is already committed.
The Adjust pair behaves differently: the after-event response only goes to the error log. For an analytics plugin that subscribes to after-events just to observe, the difference matters.
Reserve: before per line, after in a batch
reserveBatch() fires msOnBeforeInventoryReserve for every order line, while msOnInventoryReserve fires once per held line — but only after the whole batch has been held. If the third line runs out of stock, the first two are rolled back through an internal release with notify = false.
A plugin that pairs before with after will see a before without an after on a partial failure — and no release event either.
| Event | When, in terms of order status |
|---|---|
msOnBeforeInventoryReserve / msOnInventoryReserve | Reserve on ms3_status_new (and right before commit, when an order goes straight to paid) |
msOnBeforeInventoryCommit / msOnInventoryCommit | Commit on ms3_status_paid (does not decrease the stock twice) |
msOnBeforeInventoryRelease / msOnInventoryRelease | Release on ms3_status_canceled before commit. Also when payment send() fails |
msOnBeforeInventoryAdjust / msOnInventoryAdjust | Editing order lines in the manager: the reserve is brought to the new line quantity (since 1.14.3-beta1) |
The Adjust pair has its own parameters, not the ones used by reserve, commit and release:
| Parameter | Type | Value |
|---|---|---|
product_id | int | The product whose reserve changes |
order_id | int | The order |
old_qty | float | How much the order held before the edit |
new_qty | float | How much it will hold after |
forced | bool | The edit went through despite a shortage, using the msorder_inventory_override permission |
The event fires for every product whose quantity changed, including when a line is removed. Then new_qty is zero. msOnBeforeInventoryAdjust with success=false cancels the edit: the order line is not saved, and the stock and the reserve stay as they were.
Changes from miniShop2
| miniShop2 | MiniShop3 | Changes |
|---|---|---|
product | msProduct | Parameter renamed |
msOnGetOrderCost | Kept + 3 partials | Also msOnGetCartCost, msOnGetDeliveryCost, msOnGetPaymentCost. Override the total in msOnGetOrderCost |
controller | controller | In miniShop2 the parameter arrived in msOnManagerCustomCssJs and in the order and settings controllers. In MiniShop3 it is present in every cart event and in the msOnBeforeGetOrderCustomer / msOnGetOrderCustomer pair; see The controller parameter |
msOnBeforeEmptyOrder / msOnEmptyOrder | Same names | Carried over from miniShop2 unchanged. Draft cleanup |
msOnBeforeMgrCreateOrder / msOnMgrCreateOrder | Same names | Carried over from miniShop2 unchanged. Manager finalization |
| — | msOnBeforeGetOrderUser / msOnGetOrderUser | modUser on submit |
| — | msOnBeforeValidateCustomerValue | New event |
| — | msOnCreateCustomer | New event |
| — | msOnAddCustomerAddress | New event |
| — | msOnBeforeSendNotification | New event |
| — | msOnImportRow | New event |
| — | msOnProductsLoad | Third-party package integration |
| — | msOnProductPrepare | Third-party package integration |
| — | msOnGetPublicSeo | Public SEO for the Web API |
| — | msOn*Shipment* | Shipment lifecycle |
| — | msOn*Inventory* | Stock reserve / commit / release |
Call chains (where to look in code)
| Action | Events in order |
|---|---|
Clear draft (order/clean) | msOnBeforeEmptyOrder → field reset → msOnEmptyOrder |
| Frontend total | cart/delivery/payment cost → msOnBeforeGetOrderCost → compose → msOnGetOrderCost (return any of the 4 amounts) |
| Frontend submit | msOnSubmitOrder → … → msOnBeforeCreateOrder → msOnCreateOrder |
| Manager finalize | msOnBeforeMgrCreateOrder → msOnBeforeCreateOrder → msOnCreateOrder → msOnMgrCreateOrder |
All names above are registered in MODX; the registration list is _build/elements/events.php.