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 new improved dependencies system

Damian Legawieceeadd2a9b73a
diff --git a/docs/developer/customization/dependencies.mdx b/docs/developer/customization/dependencies.mdx
index 9fd52f5533..2240c16ece 100644
--- a/docs/developer/customization/dependencies.mdx
+++ b/docs/developer/customization/dependencies.mdx
@@ -5,7 +5,7 @@ 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 (user 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 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).
## Application (global) customization
@@ -14,31 +14,31 @@ 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::Dependencies.cart_add_item_service = 'MyAddToCartService'
+Spree.cart_add_item_service = MyAddToCartService
```
-or
+or using the block syntax:
```ruby
Spree.dependencies do |dependencies|
- dependencies.cart_add_item_service = 'MyAddToCartService'
+ dependencies.cart_add_item_service = MyAddToCartService
end
```
Now let's create your custom service.
```bash
-mkdir app/services -f && touch app/services/my_add_to_cart_service.rb
+mkdir -p app/services && touch app/services/my_add_to_cart_service.rb
```
And add the following code to it:
```ruby
-module MyAddToCartService < Spree::Cart::AddItem
+class MyAddToCartService < Spree::Cart::AddItem
def call(order:, variant:, quantity: nil, public_metadata: {}, private_metadata: {}, options: {})
ApplicationRecord.transaction do
run :add_to_line_item
- run Spree::Dependencies.cart_recalculate_service.constantize
+ run Spree.cart_recalculate_service
run :update_in_external_system
end
end
@@ -56,19 +56,27 @@ This code will:
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::Dependencies.cart_recalculate_service.constantize` to recalculate 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
-<Warning>
-Values set in the initializer have to be strings, eg. `'MyNewAwesomeAddItemToCart'`
-</Warning>
+## Using dependencies in your code
+
+When you need to use a dependency in your code, you can access it directly via the `Spree` module:
+
+```ruby
+# Returns the resolved class (not a string)
+Spree.cart_add_item_service.call(order: order, variant: variant, quantity: 1)
+
+# For API dependencies, use the Spree.api accessor
+Spree.api.storefront_cart_serializer.new(order).serializable_hash
+```
## Controller level customization
If you need to replace [serializers](https://github.com/jsonapi-serializer/jsonapi-serializer) or Services in a specific API endpoint you can create a [code decorator](/developer/customization/decorators):
```bash
-mkdir app/controllers/spree -f && touch app/controllers/spree/cart_controller_decorator.rb
+mkdir -p app/controllers/spree && touch app/controllers/spree/cart_controller_decorator.rb
```
and add the following code to it:
@@ -100,8 +108,8 @@ Storefront API and Platform API have separate Dependencies injection points so y
In your Spree initializer (`config/initializers/spree.rb`) please add:
```ruby
-Spree::Api::Dependencies.storefront_cart_serializer = 'MyNewAwesomeCartSerializer'
-Spree::Api::Dependencies.storefront_cart_add_item_service = 'MyNewAwesomeAddItemToCart'
+Spree.api.storefront_cart_serializer = MyNewAwesomeCartSerializer
+Spree.api.storefront_cart_add_item_service = MyNewAwesomeAddItemToCart
```
This will swap the default Cart serializer and Add Item to Cart service for your custom ones within all Storefront API endpoints that use those classes.
@@ -109,15 +117,116 @@ 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::Dependencies.cart_add_item_service = 'MyNewAwesomeAddItemToCart'
-Spree::Api::Dependencies.storefront_cart_add_item_service = 'AnotherAddItemToCart'
+Spree.cart_add_item_service = MyNewAwesomeAddItemToCart
+Spree.api.storefront_cart_add_item_service = AnotherAddItemToCart
+```
+
+The second line will have precedence over the first one, and the Storefront API will use `AnotherAddItemToCart` and the rest of the application will use `MyNewAwesomeAddItemToCart`.
+
+## Debugging dependencies
+
+Spree provides rake tasks to help you debug and inspect dependencies:
+
+### List all dependencies
+
+```bash
+bin/rake spree:dependencies:list
+```
+
+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]
+...
+
+[API]
+storefront_cart_serializer Spree::V2::Storefront::CartSerializer
+storefront_cart_add_item_service MyApp::CartAddItem [OVERRIDDEN]
+...
+```
+
+You can use `grep` to filter results:
+
+```bash
+bin/rake spree:dependencies:list | grep cart
+```
+
+### Show only overridden dependencies
+
+```bash
+bin/rake spree:dependencies:overrides
+```
+
+This shows only the dependencies that have been customized, along with their original and current values:
+
+```
+[Core OVERRIDES]
+cart_recalculate_service Spree::Cart::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)
+```
+
+### Validate all dependencies
+
+```bash
+bin/rake spree:dependencies:validate
+```
+
+This validates that all dependencies can be resolved to valid classes. If any dependency points to a non-existent class, it will report an error:
+
+```
+..........F.........
+1 invalid dependencies:
+ [Core] cart_add_item_service: uninitialized constant NonExistentClass
+```
+
+## Programmatic introspection
+
+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}, ...]
+
+# Check if a specific dependency is overridden
+Spree::Dependencies.overridden?(:cart_add_item_service)
+# => true
+
+# Get override information (where it was set)
+Spree::Dependencies.override_info(:cart_add_item_service)
+# => {value: MyApp::CartAddItem, source: "config/initializers/spree.rb:15", set_at: 2024-01-15 10:30:00}
+
+# Validate all dependencies resolve to valid classes
+Spree::Dependencies.validate!
+# => true (or raises Spree::DependencyError)
+```
+
+## 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
+
+# New syntax (recommended)
+Spree.cart_add_item_service = MyAddToCartService
+result = Spree.cart_add_item_service
```
-The second line will have precedence over the first one, and the Storefront API will use `AnotherAddItemToCart` and the rest of the application will use `MyNewAwesomeAddItemToCart`
+Both syntaxes can coexist, but the new syntax is recommended as it's more concise and provides better error messages at assignment time.
## Default values
-By default values can be easily checked by looking at the source code of Dependencies classes:
+Default values can be easily checked by:
-* [Application (global) dependencies](https://github.com/spree/spree/blob/main/core/lib/spree/core/dependencies.rb)
-* [API level dependencies](https://github.com/spree/spree/blob/main/api/lib/spree/api/dependencies.rb)
+1. Using the rake task: `bin/rake spree:dependencies:list`
+2. Looking at the source code:
+ * [Application (global) dependencies](https://github.com/spree/spree/blob/main/core/lib/spree/core/dependencies.rb)
+ * [API level dependencies](https://github.com/spree/spree/blob/main/api/lib/spree/api/dependencies.rb)