Hooks reference

Every action and filter the engine fires, as implemented in src/. Hooks run through artisanpack-ui/hooks v1.2+ (addAction() / doAction(), addFilter() / applyFilters()).

This page is the authoritative reference for what the code fires today. hooks-spec.md is the original design-time spec it grew from. Where the two differ, this page is right.

Conventions

• Names are ap.ecommerce.{domain}.{camelCaseEvent}, for example ap.ecommerce.cart.itemAdded or ap.ecommerce.order.statusChanged. The parent plan's ecommerce.order.placed-style names (§6.3) were renamed to this scheme so that they don't collide with other ArtisanPack UI packages.
• Tense tells you the kind. A present-participle name (…ing: cart.creating, tax.calculating, review.submitting) is usually a filter that runs before the engine acts. Its return value changes what happens. A past-tense name (…ed: cart.itemAdded, order.refunded) is an action that fires after the change is committed.
• Dynamic names. Some hooks are built from a variable segment: ap.ecommerce.abilities.{resource}.{action}, ap.ecommerce.api.resource.{resource}, ap.ecommerce.api.list.{resource}, and ap.ecommerce.gateway.{provider}.webhook_received.
• Filters must return the same type they receive. Most engine call sites validate the return value and either fall back to the original, discard invalid entries, or throw UnexpectedValueException (noted per hook below).
• After commit. Hooks marked after commit fire once the outermost database transaction commits (immediately when none is open), so a rolled-back write never announces itself.
• Priority. Lower numbers run first (default 10).

Hooks vs. Laravel events

The two are deliberately complementary (parent plan §6.4):

Many lifecycle points fire both, for example ap.ecommerce.order.refunded and OrderRefunded. The action always fires first.

// AppServiceProvider::boot()
addFilter( 'ap.ecommerce.shipping.rateCalculated', function ( Money $amount, ShippingMethod $method, Cart $cart ): Money {
    return $cart->customer?->meta['vip'] ?? false ? $amount->multiply( '0' ) : $amount;
} );

addAction( 'ap.ecommerce.order.statusChanged', function ( Order $order, string $from, string $to ): void {
    Log::channel( 'ecommerce' )->info( 'order.status', compact( 'from', 'to' ) + [ 'order_id' => $order->id ] );
} );

All hooks below are available since 1.0.0.

Cart

Checkout

The checkout state machine (not_started → addressing → shipping_selection → payment_selection → payment_pending → payment_confirmed → completed, or failed) lives in Services/CheckoutService.

Pricing and promotions

pricing.itemPrice, pricing.subtotal, pricing.total and pricing.priceDisplay fall back to the original amount when a listener returns something other than a Money in the same currency, or a negative amount.

Tax

Shipping

Payments and fraud

Orders

ap.ecommerce.order.placed. Checkout places the order through OrderPlacementService, which fires this action. The engine listens for it to send the order-confirmation notification, route the order onto kanban boards, and so on. Code that creates orders some other way must fire it itself, with doAction( 'ap.ecommerce.order.placed', $order ), once the order and its lines are persisted.

Customers

Activity log

Event types and payloads are listed in activity-log.md.

Inventory

Products and search

The lifecycle hooks fire from the models, so they run for every write path (ProductService, imports, raw Eloquent). All but .saving run once the surrounding database transaction commits (immediately when there is none). See products.md.

Reviews

Digital delivery and licenses

Kanban

Notifications

Outbound webhooks

Settings

Registries

Each filter runs once, after every service provider has booted, starting from []. Return entries keyed by registry key; an entry is a class name, an instance, or [ 'entry' => class|instance, 'meta' => [ 'label' => … ] ]. Every entry goes through the registry's own register(). A non-array return, an integer key, or a malformed entry throws UnexpectedValueException. See contracts.md.

Navigation

Reports

API augmentation

{resource} is the resource's NAME constant: activityLogEntry, cart, cartItem, coupon, customer, customerAddress, customerNote, digitalDownload, digitalFile, inventoryItem, inventoryReservation, kanbanAutomation, kanbanBoard, kanbanCard, kanbanCardWidget, kanbanColumn, licenseActivation, licenseKey, notificationTemplate, order, orderEdit, orderItem, orderNote, orderSubstatus, orderTimelineEntry, product, productAttribute, productAttributeValue, productCategory, productChild, productImage, productPrice, productTag, promotion, promotionAction, promotionCondition, promotionUsage, refund, refundItem, review, shipment, shipmentItem, shippingMethod, shippingZone, taxClass, taxRate, variant, webhookDelivery, webhookSubscription.

The publicMetaKeys filters only run for non-admin requests; admin requests see the whole meta object.

addFilter( 'ap.ecommerce.api.resource.product', function ( array $data, Product $product, Request $request ): array {
    $data['loyalty_points'] = (int) ( $product->meta['loyalty_points'] ?? 0 );

    return $data;
} );

Authorization

For example, ap.ecommerce.abilities.order.refund. See api-auth.md for how the decision is built.

Planned, not yet fired

Of the hooks parent plan §6.3 sketched, these have no firing site in 1.0.0: product.updated (use product.saved) and the filters cart.tax (use tax.calculating / tax.calculated) and cart.shipping_options (use shipping.availableMethods). They will use the ap.ecommerce.* scheme if they land.