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