Quickstart

# Gemfile:
gem 'rails-ioc'

# config/dependencies/development.rb:
RailsIOC::Dependencies.define do     
  prototype :card_validator,  CreditCardValidator, "Visa", "Mastercard"
  prototype :payment_gateway, DummyPaymentGateway, ref(:card_validator)

  controller PaymentsController, {
    payment_gateway: ref(:payment_gateway),
  }
end   

# app/controllers/payments_controller.rb:
class PaymentsController < ApplicationController
  def accept_payment
    @payment_gateway.process(params[:credit_card])
  end
end

# spec/controllers/payments_controller_spec.rb
it "processes a succesful payment" do
  controller_dependencies(payment_gateway: mock(PaymentGateway))
  controller.payment_gateway.should_receive(:process).with("4111").and_return(true)
  post :accept_payment, credit_card: "4111"
  response.status.should == 200
end

Background

Inversion of control via dependency injection is widely used in large software systems and is generally accepted to be a "Good Thing". If the terms are unfamiliar these are good places to start reading:

• http://en.wikipedia.org/wiki/Inversion_of_control
• http://martinfowler.com/articles/injection.html

The practice as described in the articles above is not particularly common in Ruby applications. Jamis Buck, author of the erstwhile DI framework Copland makes a compelling argument against it. If you have to ask the question "Will I need IOC for my next Rails app", the answer is almost certainly "No". The core components of a standard Rails app usually interact politely and can generally be easily tested.

Still, having run into several Rails projects which dealt with dependencies beyond an ActiveRecord database connection (payment gateways, email services, version control systems, image processing services and more) I realised that I was reminiscing fondly about Java and .NET's various containers for two reasons:

1. I really despise mocking calls to MyService#new to force a controller to use a stub implementation in a unit test.
2. There is no clean way to switch dependencies out on a per-environment basis (to use the testable version of a payment gateway in the staging environment, for example).

RailsIOC attempts to make these problems less painful for applications with complex interactions with external services by providing a lightweight way to define dependencies and inject them into ActionController. The patterns will be familiar to anyone who has used Spring or Unity. Dependencies are defined in pure Ruby using a simple internal DSL. Where possible, RailsIOC enforces constructor injection. The exception to this rule is the creation of controllers, where it avoids interfering with Rails' own instantiation and injects dependencies as @local_variables.

Cleaner Testing

Before

# Controller:
@gateway = Gateway.new(ServiceA.new, ServiceB.new)
@gateway.do_something!

# RSpec:
@svc_a = mock(ServiceA)
@svc_b = mock(ServiceB)
ServiceA.stub(:new).and_return(@svc_a)
ServiceB.stub(:new).and_return(@svc_b)
@gateway = mock(Gateway)
@gateway.should_receive(:do_something!).and_return(12345)
Gateway.stub(:new).with(@svc_a, @svc_b).and_return(@gateway)

After

# Controller:
@gateway.do_something!

# RSpec:
controller_dependencies(gateway: mock(Gateway))
controller.gateway.should_receive(:do_something!).and_return(12345)

Customise and Override Dependencies Per-Environment

Before

# app/controllers/payments_controller.rb:
class PaymentsController < ApplicationController
  def accept_payment
    if Rails.env.development? || Rails.env.test?
      @credit_card_validator = BogusCardValidator.new
    else
      @credit_card_validator = RealCardValidator.new
    end
    if Rails.env.production? 
      @gateway = RealPaymentGateway.new
    elsif Rails.env.staging? 
      @gateway = RealPaymentGateway.new(use_testing_url: true)
    else
      @gateway = BogusPaymentGateway.new
    end
    card = @credit_card_validator.validate(params[:card])
    @gateway.process(card)
  end
end

After

# app/controllers/payments_controller:
class PaymentsController < ApplicationController
  def accept_payment    
    card = @credit_card_validator.validate(params[:card])
    @gateway.process(card)
  end
end
  
# config/dependencies/production.rb:
RailsIOC::Dependencies.define do
  prototype :payment_gateway,       RealPaymentGateway
  prototype :credit_card_validator, RealCardValidator

  controller PaymentsController, {
    gateway:               ref(:payment_gateway)
    credit_card_validator: ref(:credit_card_validator)
  }
end

# config/dependencies/staging.rb:
RailsIOC::Dependencies.define do
  inherit_environment(:production)
  
  prototype :payment_gateway, RealPaymentGateway, {use_testing_url: true}
end

# config/dependencies/development.rb:
RailsIOC::Dependencies.define do
  inherit_environment(:production)

  singleton :payment_gateway, BogusPaymentGateway
  singleton :credit_card_validator, BogusCardValidator
end