Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Document services and workflows, and fix twin hook registration

Damian Legawiec7eecb5511a4e
diff --git a/docs/developer/customization/dependencies.mdx b/docs/developer/customization/dependencies.mdx
index 0a32e83e1b..c64d0823f7 100644
--- a/docs/developer/customization/dependencies.mdx
+++ b/docs/developer/customization/dependencies.mdx
@@ -5,7 +5,18 @@ section: customization
## Overview
-With Dependencies, you can easily replace parts of Spree core with your custom code. You can replace [Services](https://github.com/spree/spree/tree/master/core/app/services/spree), CanCanCan Abilities (used for [Permissions](permissions)), and [API Serializers](https://github.com/spree/spree/tree/master/api/app/serializers/spree/v2) (used for generating JSON API responses).
+With Dependencies, you can replace parts of Spree core with your custom code:
+[Services and Workflows](/developer/customization/workflows), CanCanCan
+Abilities (used for [Permissions](permissions)), and API Serializers (used for
+generating JSON API responses).
+
+<Tip>
+Replacing a whole class means keeping your copy in sync with every Spree
+release. If you only need to run code inside an existing flow — validating,
+reacting, or contributing data to a calculation — use a
+[hook](/developer/customization/workflows#extending-a-workflow-with-hooks)
+instead. Hooks survive upgrades.
+</Tip>
## Application (global) customization
@@ -14,50 +25,70 @@ This will change every aspect of the application (both APIs, Admin Panel, and St
In your `config/initializers/spree.rb` file, you can set the following:
```ruby
-Spree.cart_add_item_service = MyAddToCartService
+Spree.cart_update_service = MyStore::CartUpdate
```
or using the block syntax:
```ruby
Spree.dependencies do |dependencies|
- dependencies.cart_add_item_service = MyAddToCartService
+ dependencies.cart_update_service = MyStore::CartUpdate
end
```
Now let's create your custom service.
```bash
-mkdir -p app/services && touch app/services/my_add_to_cart_service.rb
+mkdir -p app/services/my_store && touch app/services/my_store/cart_update.rb
```
And add the following code to it:
```ruby
-class MyAddToCartService < Spree::Cart::AddItem
- def call(order:, variant:, quantity: nil, metadata: {}, options: {})
- ApplicationRecord.transaction do
- run :add_to_line_item
- run Spree.cart_recalculate_service
- run :update_in_external_system
+module MyStore
+ class CartUpdate < Spree::Carts::Update
+ def call(cart:, params:)
+ result = super
+
+ MyStore::ErpSync.push(result.value) if result.success?
+
+ result
end
end
+end
+```
+
+Inheriting and calling `super` keeps Spree's behaviour and adds yours around it,
+which is usually what you want — a full rewrite means re-implementing logic that
+changes between releases.
+
+### Replacing a workflow
- private
+Workflow-backed seams end in `_workflow` (`cart_add_item_workflow`,
+`carts_complete_workflow`, `payment_capture_workflow`, …). A replacement
+subclasses the workflow and overrides `perform`:
- def update_in_external_system(new_order_line_item)
- # Your custom logic here
+```ruby
+module MyStore
+ class AddItem < Spree::Carts::AddItem
+ def perform(variant:, cart: nil, **rest)
+ super
+
+ # your logic, then the standard result
+ end
end
end
-```
-This code will:
+Spree.cart_add_item_workflow = MyStore::AddItem
+```
-1. Inherit from `Spree::Cart::AddItem`
-2. Override the `call` method to add your custom logic
-3. Call `run :add_to_line_item` to add the item to the cart
-4. Call `run Spree.cart_recalculate_service` to recalculate the cart (returns the resolved class)
-5. Call `run :update_in_external_system` to execute your custom logic, eg. updating Order in an external system such as ERP
+<Note>
+Before writing this, check whether a
+[hook](/developer/customization/workflows#available-hooks) covers your case —
+`carts.add_item.validate` and `carts.add_item.after_item_added` handle most
+reasons people replace this class, and they don't need maintaining across
+upgrades.
+</Note>
## Using dependencies in your code
@@ -65,7 +96,7 @@ When you need to use a dependency in your code, you can access it directly via t
```ruby
# Returns the resolved class (not a string)
-Spree.cart_add_item_service.call(order: order, variant: variant, quantity: 1)
+Spree.cart_add_item_workflow.call(cart: cart, variant: variant, quantity: 1)
# For API dependencies, use the Spree.api accessor
Spree.api.storefront_cart_serializer.new(order).serializable_hash
@@ -99,7 +130,7 @@ end
This will change the serializer in this API endpoint to `MyNewAwesomeCartSerializer` and also it will swap the default `add_item_service` to `MyNewAwesomeAddItemToCart`.
-Different API endpoints can have different dependency injection points. You can review their [source code](https://github.com/spree/spree/tree/master/api/app/controllers/spree/api/v2) to see what you can replace.
+Different API endpoints can have different dependency injection points. You can review their [source code](https://github.com/spree/spree/tree/main/api/app/controllers/spree/api/v3) to see what you can replace.
## API level customization
@@ -117,7 +148,7 @@ This will swap the default Cart serializer and Add Item to Cart service for your
You can mix and match both global and API-level customizations:
```ruby
-Spree.cart_add_item_service = MyNewAwesomeAddItemToCart
+Spree.cart_add_item_workflow = MyNewAwesomeAddItemToCart
Spree.api.storefront_cart_add_item_service = AnotherAddItemToCart
```
@@ -137,9 +168,9 @@ This will output all dependencies with their current values:
```
[CORE]
-cart_add_item_service Spree::Cart::AddItem
-cart_create_service Spree::Cart::Create
-cart_recalculate_service Spree::Cart::Recalculate [OVERRIDDEN]
+cart_add_item_workflow Spree::Carts::AddItem
+carts_create_service Spree::Carts::Create
+cart_recalculate_workflow Spree::Carts::Recalculate [OVERRIDDEN]
...
[API]
@@ -164,10 +195,10 @@ This shows only the dependencies that have been customized, along with their ori
```
[Core OVERRIDES]
-cart_recalculate_service Spree::Cart::Recalculate -> MyApp::CartRecalculate (config/initializers/spree.rb:15)
+cart_recalculate_workflow Spree::Carts::Recalculate -> MyApp::CartRecalculate (config/initializers/spree.rb:15)
[API OVERRIDES]
-storefront_cart_add_item_service Spree::Cart::AddItem -> MyApp::CartAddItem (config/initializers/spree.rb:20)
+storefront_cart_add_item_service Spree::Carts::AddItem -> MyApp::CartAddItem (config/initializers/spree.rb:20)
```
### Validate all dependencies
@@ -181,7 +212,7 @@ This validates that all dependencies can be resolved to valid classes. If any de
```
..........F.........
1 invalid dependencies:
- [Core] cart_add_item_service: uninitialized constant NonExistentClass
+ [Core] cart_add_item_workflow: uninitialized constant NonExistentClass
```
## Programmatic introspection
@@ -191,14 +222,14 @@ You can also inspect dependencies programmatically:
```ruby
# Check all current values
Spree::Dependencies.current_values
-# => [{name: :cart_add_item_service, current: MyApp::CartAddItem, default: 'Spree::Cart::AddItem', overridden: true}, ...]
+# => [{name: :cart_add_item_workflow, current: MyApp::CartAddItem, default: 'Spree::Carts::AddItem', overridden: true}, ...]
# Check if a specific dependency is overridden
-Spree::Dependencies.overridden?(:cart_add_item_service)
+Spree::Dependencies.overridden?(:cart_add_item_workflow)
# => true
# Get override information (where it was set)
-Spree::Dependencies.override_info(:cart_add_item_service)
+Spree::Dependencies.override_info(:cart_add_item_workflow)
# => {value: MyApp::CartAddItem, source: "config/initializers/spree.rb:15", set_at: 2024-01-15 10:30:00}
# Validate all dependencies resolve to valid classes
@@ -206,18 +237,45 @@ Spree::Dependencies.validate!
# => true (or raises Spree::DependencyError)
```
+## Renamed seams in Spree 6.0
+
+Seams backed by a [workflow](/developer/customization/workflows) were renamed
+from `*_service` to `*_workflow` in 6.0:
+
+| Legacy name | Current name |
+|---|---|
+| `cart_add_item_service` | `cart_add_item_workflow` |
+| `cart_recalculate_service` | `cart_recalculate_workflow` |
+| `carts_complete_service` | `carts_complete_workflow` |
+| `cart_merge_strategy` | `cart_merge_workflow` |
+| `order_cancel_service` | `order_cancel_workflow` |
+| `order_complete_service` | `order_complete_workflow` |
+| `fulfillment_create_service` | `fulfillment_create_workflow` |
+| `payments_handle_webhook_service` | `payments_handle_webhook_workflow` |
+
+<Warning>
+The legacy names stay readable for one release, but **assigning to one no longer
+has any effect** — the override is recorded and a deprecation warning names the
+seam to port to. A class written against the old service contract isn't
+interchangeable with the workflow the new call sites use, so applying it
+silently would break checkout in ways that are hard to trace.
+
+If you override any of these, move to the `*_workflow` name and make sure your
+class subclasses the workflow. The legacy names are removed in Spree 6.1.
+</Warning>
+
## Backwards compatibility
The legacy string-based syntax is still supported for backwards compatibility:
```ruby
# Legacy syntax (still works)
-Spree::Dependencies.cart_add_item_service = 'MyAddToCartService'
-result = Spree::Dependencies.cart_add_item_service.constantize
+Spree::Dependencies.carts_create_service = 'MyStore::CartCreate'
+result = Spree::Dependencies.carts_create_service.constantize
# New syntax (recommended)
-Spree.cart_add_item_service = MyAddToCartService
-result = Spree.cart_add_item_service
+Spree.carts_create_service = MyStore::CartCreate
+result = Spree.carts_create_service
```
Both syntaxes can coexist, but the new syntax is recommended as it's more concise and provides better error messages at assignment time.
diff --git a/docs/developer/customization/workflows.mdx b/docs/developer/customization/workflows.mdx
new file mode 100644
index 0000000000..e445195994
--- /dev/null
+++ b/docs/developer/customization/workflows.mdx
@@ -0,0 +1,389 @@
+---
+title: Services & Workflows
+section: customization
+---
+
+## Overview
+
+Spree's business logic lives in two kinds of plain Ruby classes. Both are called
+the same way and both return the same result object, so as a caller you never
+need to know which one you're using.
+
+**Services** (`app/services/`) are the default. A service is an ordinary class
+with a `call` method — creating a customer, updating a price, removing an item
+from a cart. Most of Spree is services.
+
+**Workflows** (`app/workflows/`) handle the flows that need more: completing a
+checkout, cancelling an order, capturing a payment, creating a fulfillment.
+These are the operations where something can go wrong halfway through, where
+money moves, or where you might want to inject your own logic partway.
+
+A workflow earns its place by needing at least one of:
+
+* **Extension points** — named places where your code can run inside the flow
+* **External calls** — payment gateways, carrier APIs, anything over the network
+* **Compensation** — undoing earlier work when a later step fails
+
+Everything else stays a service. If you're writing a plain create-update-delete
+operation, write a service.
+
+## Calling them
+
+Identical for both:
+
+```ruby
+result = Spree.cart_add_item_workflow.call(cart: cart, variant: variant, quantity: 2)
+
+if result.success?
+ line_item = result.value
+else
+ puts result.error.value
+end
+```
+
+Never raise on expected failures — check `result.success?`. See
+[Dependencies](/developer/customization/dependencies) for how to swap either one
+for your own class.
+
+## Extending a workflow with hooks
+
+Before hooks, customizing a flow meant replacing the whole class and keeping
+your copy in sync with every Spree release. Hooks let you run your own code at a
+named point inside a flow you don't own.
+
+Register in `config/initializers/spree.rb`:
+
+```ruby
+Spree.hooks.register('carts.add_item.validate', 'MyStore::CheckPurchaseLimit')
+```
+
+The key is `<workflow>.<hook>`. Handlers are stored as **class name strings**,
+resolved when the hook fires — that keeps registration safe at boot time and
+survives code reloading in development. A block works for one-liners:
+
+```ruby
+Spree.hooks.register('orders.cancel.after_cancel') do |workflow|
+ MyStore::Analytics.track(:order_cancelled, workflow.order.number)
+end
+```
+
+Your handler is a class with a `call` method that receives the workflow:
+
+```ruby
+module MyStore
+ class CheckPurchaseLimit
+ def call(workflow)
+ # every #perform keyword is a reader: cart, variant, quantity, ...
+ return if workflow.quantity <= 10
+
+ workflow.reject!('You can order at most 10 of this item.')
+ end
+ end
+end
+```
+
+<Note>
+Hook keys are validated at boot. Registering against a hook that doesn't exist
+raises `Spree::Hooks::UnknownHookError` with the list of valid hooks for that
+workflow, so a typo fails immediately instead of silently never firing.
+</Note>
+
+## Every hook can have many handlers
+
+A hook is not a single slot. Your extension, another extension and the host
+application can all register against the same key, and every one of them runs.
+Assume you are never alone on a hook.
+
+```ruby
+Spree.hooks.register('carts.add_item.validate', 'MyStore::CheckPurchaseLimit')
+Spree.hooks.register('carts.add_item.validate', 'OtherGem::CheckChannelRules')
+Spree.hooks.register('carts.add_item.validate') { |workflow| ... }
+# all three run
+```
+
+**Handlers run in registration order** — the order the `register` calls
+happened, which for gems is initializer load order. Don't depend on it. If your
+handler only makes sense after another one has run, you have a sequencing
+requirement that hooks don't express; put both pieces in one handler.
+
+**Registering the same class twice is a no-op.** `register` deduplicates by
+class name, so an initializer that runs twice (or a gem registering defensively)
+won't double up. Two *different* classes are two handlers, and two separate
+blocks are always two handlers — blocks can't be compared, so prefer class names
+anywhere registration might repeat.
+
+What "many handlers" means differs by kind:
+
+| Kind | With several handlers |
+|---|---|
+| `validate` | Runs in order until one rejects. **The first `reject!` stops the flow** — later validate handlers never run, so don't rely on yours executing. |
+| Context | **All** run and their hashes are merged. A key set by two handlers goes to the last one registered, and the collision is reported through `Rails.error`. |
+| Lifecycle | All run in order. Return values are ignored. |
+
+One consequence worth planning for: because any handler can veto, a `validate`
+handler should say *why* it rejected in the message, and a lifecycle handler
+should not assume it is the only observer of the event.
+
+<Warning>
+Handlers are not isolated from each other. An exception raised in one propagates
+out of the workflow, later handlers on that hook never run, and an open
+transaction rolls back — a `raise` in an `after_item_added` handler leaves the
+customer's item not added at all.
+
+If your handler does something optional (analytics, a nice-to-have
+notification), rescue inside it so a failure in your code can't undo someone
+else's order. Work that is genuinely allowed to fail belongs in an
+[event subscriber](/developer/core-concepts/events), not a hook.
+</Warning>
+
+## The three kinds of hooks
+
+### Lifecycle hooks — react to something that happened
+
+Named in the past tense (`after_item_added`, `after_cancel`, `after_create`).
+They run after the work is done. Return values are ignored; you cannot change
+the outcome.
+
+```ruby
+class MyStore::NotifyWarehouse
+ def call(workflow)
+ WarehouseApi.notify(workflow.fulfillment.number)
+ end
+end
+
+Spree.hooks.register('fulfillments.create.after_create', 'MyStore::NotifyWarehouse')
+```
+
+Note that some lifecycle hooks run **inside** the flow's database transaction
+(`after_item_added`, `after_cancel`). That's deliberate — it lets you write
+related records atomically with the change. It also means slow work does not
+belong there: use an [event subscriber](/developer/core-concepts/events) for
+emails, webhooks and other eventual work.
+
+### Validation hooks — veto before the work happens
+
+Always called `validate`. They run **before** anything is written, so rejecting
+costs nothing — no rollback, no partial state, no money moved.
+
+Call `reject!` on the workflow to stop the flow:
+
+```ruby
+module MyStore
+ class LimitReturnWindow
+ def call(workflow)
+ return if workflow.order.completed_at > 30.days.ago
+
+ workflow.reject!('This order is outside the 30-day return window.')
+ end
+ end
+end
+```
+
+The caller receives a normal failure result — no exception reaches your
+controller:
+
+```ruby
+result = Spree.cart_add_item_workflow.call(cart: cart, variant: variant)
+result.success? # => false
+result.error.value # => "You can order at most 10 of this item."
+```
+
+<Warning>
+Reject from `validate` hooks, not from `after_*` hooks. Rejecting late still
+rolls the database back, but it cannot undo work that already left the system —
+`carts.complete.before_finalize` runs *after* the customer's card was charged,
+so rejecting there rolls back the order while the charge stands. If you need to
+stop a flow, `validate` is the place.
+</Warning>
+
+### Context hooks — feed data into a calculation
+
+Named imperatively (`set_promotion_context`, `set_tax_line_context`,
+`get_provider_data`). They run before a calculation so you can contribute data
+to it.
+
+Your handler **returns a hash**. Spree merges the hashes from every registered
+handler and hands the result to the workflow:
+
+```ruby
+module MyStore
+ class TaxExemption
+ def call(workflow)
+ certificate = workflow.cart.customer&.tax_exemption_certificate
+ return {} if certificate.blank?
+
+ { exemption_certificate: certificate.number }
+ end
+ end
+end
+
+Spree.hooks.register('carts.recalculate_totals.set_tax_line_context', 'MyStore::TaxExemption')
+```
+
+Handlers stay independent — there is no shared object to mutate and no ordering
+to reason about. A handler returning anything other than a hash contributes
+nothing, so lifecycle-style handlers are harmless if registered here by mistake.
+
+If two handlers set the same key, the last registered one wins and the collision
+is reported through `Rails.error` so it's visible rather than mysterious.
+
+## Available hooks
+
+| Workflow key | Hook | Kind | When it runs |
+|---|---|---|---|
+| `carts.add_item` | `validate` | validate | Before the line item is built |
+| `carts.add_item` | `after_item_added` | lifecycle | After the item is saved and totals recalculated (in transaction) |
+| `carts.complete` | `validate` | validate | After checkout requirements pass, before the order is created |
+| `carts.complete` | `before_finalize` | lifecycle | After payment, before the order is placed |
+| `carts.complete` | `after_finalize` | lifecycle | After the order is placed |
+| `carts.merge` | `validate` | validate | Before any items move between carts |
+| `carts.merge` | `after_merge` | lifecycle | After the carts are folded together |
+| `carts.recalculate` | `set_promotion_context` | context | Before promotions are evaluated |
+| `carts.recalculate` | `after_recalculate` | lifecycle | After the cart is fully repriced |
+| `carts.recalculate_totals` | `set_tax_line_context` | context | Before tax is estimated |
+| `orders.cancel` | `before_cancel` | validate | Before the cancellation is recorded |
+| `orders.cancel` | `after_cancel` | lifecycle | With the cancellation, in transaction |
+| `orders.resume` | `before_resume` | validate | Before the order is un-cancelled |
+| `orders.resume` | `after_resume` | lifecycle | With the status flip, in transaction |
+| `fulfillments.create` | `validate` | validate | Before the order is locked |
+| `fulfillments.create` | `get_provider_data` | context | Before the fulfillment is built |
+| `fulfillments.create` | `after_create` | lifecycle | After the fulfillment is created and totals recalculated |
+| `payments.capture` | `validate` | validate | Before the gateway is called |
+| `payments.capture` | `before_capture` | lifecycle | Immediately before the gateway call |
+| `payments.capture` | `after_capture` | lifecycle | After a successful capture |
+| `payments.refund` | `validate` | validate | Before the refund record exists |
+| `payments.refund` | `before_refund` | lifecycle | Immediately before the gateway call |
+| `payments.refund` | `after_refund` | lifecycle | After a successful refund |
+| `payments.handle_webhook` | `after_handle` | lifecycle | After the gateway callback is processed |
+
+`before_cancel` and `before_resume` accept `reject!` like a `validate` hook.
+
+Draft-order editing in the admin uses **twin workflows** with their own keys —
+`orders.add_item`, `orders.recalculate`, `orders.recalculate_totals` — carrying
+the same hooks as their cart counterparts. Register against the cart key for
+storefront carts, the order key for admin edits, or both.
+
+Inspect what's available at runtime:
+
+```ruby
+Spree.hooks.workflows # => { 'carts.add_item' => 'Spree::Carts::AddItem', ... }
+Spree::Carts::Complete.declared_hooks # => [:validate, :before_finalize, :after_finalize]
+Spree.hooks.keys # => registered keys
+Spree.hooks.validate! # => true, or raises on a bad registration
+```
+
+## Writing your own workflow
+
+Most extensions only need hooks. Write a workflow when you're adding a *new*
+multi-step operation of your own — one with external calls, compensation, or
+extension points for others.
+
+```ruby
+module MyStore
+ class Subscriptions::Renew < Spree::Workflow
+ hooks :validate, :after_renew
+
+ attr_reader :order
+
+ # The method signature is the contract — Ruby raises on a missing or
+ # unknown keyword, and a bare `super` turns each parameter into a reader.
+ #
+ # @param subscription [MyStore::Subscription]
+ # @param renewed_at [Time, nil]
+ def perform(subscription:, renewed_at: nil)
+ super
+
+ step :ensure_renewable
+ run_hooks :validate
+
+ ApplicationRecord.transaction do
+ step :build_order, on_flow_failure: :discard_order
+ step :extend_period
+ end
+
+ external_step :charge_customer
+
+ run_hooks :after_renew
+ subscription.publish_event('subscription.renewed')
+ success(order)
+ end
+
+ private
+
+ def ensure_renewable
+ failure(subscription, :not_active) unless subscription.active?
+ end
+
+ def build_order
+ @order = MyStore::Subscriptions::BuildOrder.call(subscription: subscription).value
+ end
+
+ def extend_period
+ subscription.update!(renews_at: (renewed_at || Time.current) + 1.month)
+ end
+
+ def charge_customer
+ Spree.payment_capture_workflow.call(payment: order.payments.last)
+ end
+
+ # Runs if a later step fails after the transaction committed.
+ def discard_order
+ order&.destroy
+ end
+ end
+end
+```
+
+The whole vocabulary:
+
+| | |
+|---|---|
+| `step :name` | Runs the private method of that name |
+| `external_step :name` | Same, but refuses to run inside a database transaction this workflow opened — use it for every network call |
+| `with: -> { ... }` | Delegates a step to a swappable collaborator, keyword arguments sliced from the workflow's readers |
+| `on_flow_failure: :name` | Names the undo for a step, run in reverse if a later step fails |
+| `run_hooks :name` | Dispatches a declared hook; returns the merged hash from context handlers |
+| `failure(value, error)` | Aborts the flow — rolls back an open transaction and returns a failure result |
+| `reject!(message)` | The same, named for hook handlers vetoing a flow |
+| `halt!(value)` | Successful early exit (not valid inside a transaction the workflow opened) |
+| `hooks :a, :b` | Declares the extension points this workflow dispatches |
+
+Everything else is ordinary Rails — `ApplicationRecord.transaction`,
+`with_lock`, `if`, `rescue`, `publish_event`.
+
+Two rules worth internalising:
+
+**Network calls never share a database transaction.** That's what
+`external_step` enforces. A gateway call inside a transaction holds a database
+connection open across a network round trip, and a timeout leaves your database
+and the payment processor disagreeing about what happened.
+
+**New models get a plain `status` string, not a state machine.** Transitions are
+workflows: `MyStore::Subscriptions::Cancel.call(...)`, not `subscription.cancel!`.
+Transition callbacks hide side effects inside a save, cannot take arguments, and
+have no compensation story.
+
+## Observability
+
+Every step emits an `ActiveSupport::Notifications` event, so your APM sees the
+flow without extra instrumentation:
+
+```ruby
+ActiveSupport::Notifications.subscribe('step.spree_workflow') do |*, payload|
+ Rails.logger.info("#{payload[:workflow]}##{payload[:step]}")
+end
+```
+
+## Choosing an extension point
+
+| You want to | Use |
+|---|---|
+| Stop an operation from happening | A `validate` hook |
+| Add data to a pricing or tax calculation | A context hook |
+| Do something after an operation, in the same transaction | A lifecycle hook |
+| Send an email, call a webhook, update a search index | An [event subscriber](/developer/core-concepts/events) |
+| Replace an operation entirely | [Dependencies](/developer/customization/dependencies) |
+| Add a brand-new multi-step operation | Your own workflow |
+
+Reach for the smallest one that does the job. A hook survives Spree upgrades;
+a replaced class has to be kept in sync with every release.
diff --git a/docs/docs.json b/docs/docs.json
index c42000b3bf..f0e322dd84 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -328,6 +328,7 @@
"developer/customization/authentication",
"developer/customization/checkout",
"developer/customization/permissions",
+ "developer/customization/workflows",
"developer/customization/dependencies",
"developer/customization/decorators",
"developer/customization/model-preferences",
diff --git a/spree/core/lib/spree/workflow.rb b/spree/core/lib/spree/workflow.rb
index fb6f1ecef3..37a03a5067 100644
--- a/spree/core/lib/spree/workflow.rb
+++ b/spree/core/lib/spree/workflow.rb
@@ -84,9 +84,16 @@ module Spree
class << self
attr_reader :declared_hooks
+ # A subclass inherits the parent's declared hooks but dispatches them
+ # under its OWN key — Spree::Orders::AddItem fires
+ # 'orders.add_item.validate', not the cart key — so it registers
+ # itself too, otherwise Spree.hooks.validate! rejects registrations
+ # against a twin's perfectly valid hook.
def inherited(subclass)
super
- subclass.instance_variable_set(:@declared_hooks, (declared_hooks || []).dup)
+ inherited_hooks = (declared_hooks || []).dup
+ subclass.instance_variable_set(:@declared_hooks, inherited_hooks)
+ Spree.hooks.register_workflow(subclass.workflow_key, subclass.name) if inherited_hooks.any? && subclass.name
end
# Dotted identity used for hook keys and instrumentation; derived
diff --git a/spree/core/spec/lib/spree/workflow_spec.rb b/spree/core/spec/lib/spree/workflow_spec.rb
index 15798cc21d..b78736f00b 100644
--- a/spree/core/spec/lib/spree/workflow_spec.rb
+++ b/spree/core/spec/lib/spree/workflow_spec.rb
@@ -330,6 +330,35 @@ RSpec.describe Spree::Workflow do
.to raise_error(Spree::Workflow::ContractError, /does not declare hook :never_declared/)
end
+ it 'registers a subclass under its own key so twin hooks are reachable' do
+ parent = build_workflow do
+ hooks :validate
+
+ def perform(subject:)
+ super
+ run_hooks :validate
+ success(subject)
+ end
+ end
+
+ twin = Class.new(parent) do
+ def self.name = 'Spree::Testing::TwinWorkflow'
+ workflow_key 'testing.twin_workflow'
+ end
+ stub_const('Spree::Testing::TwinWorkflow', twin)
+ # workflow_key is resolved lazily, so re-register under the final key.
+ twin.hooks :validate
+
+ fired = []
+ Spree.hooks.register('testing.twin_workflow.validate') { |_flow| fired << :twin }
+ Spree.hooks.register('testing.sample_workflow.validate') { |_flow| fired << :parent }
+
+ expect(Spree.hooks.validate!).to be(true)
+
+ twin.call(subject: 1)
+ expect(fired).to eq([:twin])
+ end
+
describe 'reject!' do
it 'aborts the flow with a failure result the caller can inspect' do
workflow = build_workflow do