Class: Spree::Subscriber

Inherits:
Object
  • Object
show all
Defined in:
app/models/spree/subscriber.rb

Overview

Base class for event subscribers.

Subscribers handle events published through the Spree event system. They provide a clean DSL for declaring which events to subscribe to and are automatically registered during Rails initialization.

Examples:

Basic subscriber

class OrderCompletedNotifier < Spree::Subscriber
  subscribes_to 'order.complete'

  def call(event)
    order_id = event.payload['id']
    Spree::OrderMailer.confirm_email(order_id).deliver_later
  end
end

Multi-event subscriber

class OrderAuditLogger < Spree::Subscriber
  subscribes_to 'order.complete', 'order.cancel', 'order.resume'

  def call(event)
    AuditLog.create!(
      event_name: event.name,
      payload: event.payload,
      occurred_at: event.timestamp
    )
  end
end

Pattern matching subscriber

class OrderEventLogger < Spree::Subscriber
  subscribes_to 'order.*'

  def call(event)
    Rails.logger.info("Order event: #{event.name}")
  end
end

Subscriber with method routing

class PaymentSubscriber < Spree::Subscriber
  subscribes_to 'payment.complete', 'payment.void', 'payment.refund'

  on 'payment.complete', :handle_complete
  on 'payment.void', :handle_void
  on 'payment.refund', :handle_refund

  private

  def handle_complete(event)
    # Handle payment completion
  end

  def handle_void(event)
    # Handle payment void
  end

  def handle_refund(event)
    # Handle payment refund
  end
end

Synchronous subscriber (runs immediately, not via ActiveJob)

class CriticalOrderHandler < Spree::Subscriber
  subscribes_to 'order.complete', async: false

  def call(event)
    # This runs synchronously
  end
end

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.call(event) ⇒ Object

Class-level call method for when the class itself is used as subscriber

Parameters:



137
138
139
 
# File 'app/models/spree/subscriber.rb', line 137

def call(event)
  new.call(event)
end

.event_handlers ⇒ Hash<String, Symbol>

Get event handlers mapping

Returns:

  • (Hash<String, Symbol>) 


130
131
132
 
# File 'app/models/spree/subscriber.rb', line 130

def event_handlers
  @event_handlers ||= {}
end

.on(pattern, method_name) ⇒ void

This method returns an undefined value.

DSL method to route specific events to specific methods

Examples:

on 'payment.complete', :handle_complete
on 'payment.void', :handle_void

Parameters:

  • pattern (String) —

    Event pattern

  • method_name (Symbol) —

    Method to call for this event



108
109
110
111
 
# File 'app/models/spree/subscriber.rb', line 108

def on(pattern, method_name)
  @event_handlers ||= {}
  @event_handlers[pattern.to_s] = method_name
end

.subscribes_to(*patterns, **options) ⇒ void

This method returns an undefined value.

DSL method to declare which events this subscriber handles

Examples:

subscribes_to 'order.complete'
subscribes_to 'order.complete', 'order.cancel'
subscribes_to 'order.*'
subscribes_to 'order.complete', async: false

Parameters:

  • patterns (Array<String>) —

    Event patterns to subscribe to

  • options (Hash) —

    Subscription options

Options Hash (**options):

  • :async (Boolean) — default: true —

    Whether to run async via ActiveJob



89
90
91
92
93
94
95
96
 
# File 'app/models/spree/subscriber.rb', line 89

def subscribes_to(*patterns, **options)
  @subscription_patterns ||= []
  @subscription_options = options

  patterns.flatten.each do |pattern|
    @subscription_patterns << pattern.to_s
  end
end

.subscription_options ⇒ Hash

Get subscription options

Returns:

  • (Hash) 


123
124
125
 
# File 'app/models/spree/subscriber.rb', line 123

def subscription_options
  @subscription_options ||= {}
end

.subscription_patterns ⇒ Array<String>

Get all subscription patterns for this subscriber

Returns:

  • (Array<String>) 


116
117
118
 
# File 'app/models/spree/subscriber.rb', line 116

def subscription_patterns
  @subscription_patterns ||= []
end

Instance Method Details

#call(event) ⇒ void

This method returns an undefined value.

Handle an event

Override this method in subclasses to handle events. If you’ve defined event handlers with ‘on`, this method will route to the appropriate handler automatically.

Parameters:



150
151
152
153
154
155
156
157
158
159
 
# File 'app/models/spree/subscriber.rb', line 150

def call(event)
  handler = find_handler(event)

  if handler
    send(handler, event)
  else
    # Default behavior - subclasses should override
    handle(event)
  end
end

#handle(event) ⇒ Object

Default event handler

Override this in subclasses if not using the ‘on` DSL

Parameters:



166
167
168
 
# File 'app/models/spree/subscriber.rb', line 166

def handle(event)
  # Override in subclass
end