ActiveRecord::Callbacks ^(Module)

Callbacks are hooks into the lifecycle of an Active Record object that allows you to trigger logic before or after an alteration of the object state. This can be used to make sure that associated and dependent objects are deleted when destroy is called (by overwriting before_destroy) or to massage attributes before they’re validated (by overwriting before_validation). As an example of the callbacks initiated, consider the Base#save call:

• (-) save
• (-) valid?
• (1) before_validation
• (2) before_validation_on_create
• (-) validate
• (-) validate_on_create
• (4) after_validation
• (5) after_validation_on_create
• (6) before_save
• (7) before_create
• (-) create
• (8) after_create
• (9) after_save

That’s a total of nine callbacks, which gives you immense power to react and prepare for each state in the Active Record lifecyle.

Examples:

  class CreditCard < ActiveRecord::Base
    # Strip everything but digits, so the user can specify "555 234 34" or
    # "5552-3434" or both will mean "55523434"
    def before_validation_on_create
      self.number = number.gsub(/[^0-9]/, "") if attribute_present?("number")
    end
  end

  class Subscription < ActiveRecord::Base
    # Automatically assign the signup date
    def before_create
      self.signed_up_on = Date.today
    end
  end

  class Firm < ActiveRecord::Base
    # Destroys the associated clients and people when the firm is destroyed
    def before_destroy
      Client.destroy_all "client_of = #{id}"
      Person.destroy_all "firm_id = #{id}"
    end

Inheritable callback queues

Besides the overwriteable callback methods, it’s also possible to register callbacks through the use of the callback macros. Their main advantage is that the macros add behavior into a callback queue that is kept intact down through an inheritance hierarchy. Example:

  class Topic < ActiveRecord::Base
    before_destroy :destroy_author
  end

  class Reply < Topic
    before_destroy :destroy_readers
  end

Now, when Topic#destroy is run only destroy_author is called. When Reply#destroy is run both destroy_author and destroy_readers is called. Contrast this to the situation where we’ve implemented the save behavior through overwriteable methods:

  class Topic < ActiveRecord::Base
    def before_destroy() destroy_author end
  end

  class Reply < Topic
    def before_destroy() destroy_readers end
  end

In that case, Reply#destroy would only run destroy_readers and not destroy_author. So use the callback macros when you want to ensure that a certain callback is called for the entire hierarchy and the regular overwriteable methods when you want to leave it up to each descendent to decide whether they want to call super and trigger the inherited callbacks.

Types of callbacks

There are four types of callbacks accepted by the callback macros: Method references (symbol), callback objects, inline methods (using a proc), and inline eval methods (using a string). Method references and callback objects are the recommended approaches, inline methods using a proc is some times appropriate (such as for creating mix-ins), and inline eval methods are deprecated.

The method reference callbacks work by specifying a protected or private method available in the object, like this:

  class Topic < ActiveRecord::Base
    before_destroy :delete_parents

    private
      def delete_parents
        self.class.delete_all "parent_id = #{id}"
      end
  end

The callback objects have methods named after the callback called with the record as the only parameter, such as:

  class BankAccount < ActiveRecord::Base
    before_save      EncryptionWrapper.new("credit_card_number")
    after_save       EncryptionWrapper.new("credit_card_number")
    after_initialize EncryptionWrapper.new("credit_card_number")
  end

  class EncryptionWrapper
    def initialize(attribute)
      @attribute = attribute
    end

    def before_save(record)
      record.credit_card_number = encrypt(record.credit_card_number)
    end

    def after_save(record)
      record.credit_card_number = decrypt(record.credit_card_number)
    end

    alias_method :after_initialize, :after_save

    private
      def encrypt(value)
        # Secrecy is committed
      end

      def decrypt(value)
        # Secrecy is unvieled
      end
  end

So you specify the object you want messaged on a given callback. When that callback is triggered, the object has a method by the name of the callback messaged.

The callback macros usually accept a symbol for the method they’re supposed to run, but you can also pass a "method string", which will then be evaluated within the binding of the callback. Example:

  class Topic < ActiveRecord::Base
    before_destroy 'self.class.delete_all "parent_id = #{id}"'
  end

Notice that single plings (’) are used so the #{id} part isn’t evaluated until the callback is triggered. Also note that these inline callbacks can be stacked just like the regular ones:

  class Topic < ActiveRecord::Base
    before_destroy 'self.class.delete_all "parent_id = #{id}"',
                   'puts "Evaluated after parents are destroyed"'
  end

The after_find and after_initialize exceptions

Because after_find and after_initialize is called for each object instantiated found by a finder, such as Base.find_all, we’ve had to implement a simple performance constraint (50% more speed on a simple test case). Unlike all the other callbacks, after_find and after_initialize can only be declared using an explicit implementation. So using the inheritable callback queue for after_find and after_initialize won’t work.

Methods

Constants

External Aliases