Callbacks are hooks into the lifecycle of an Active Record object that allow 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 destroyis 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#savecall for a new record:

  • (-) save

  • (-) valid

  • (1) before_validation

  • (2) before_validation_on_create

  • (-) validate

  • (-) validate_on_create

  • (3) after_validation

  • (4) after_validation_on_create

  • (5) before_save

  • (6) before_create

  • (-) create

  • (7) after_create

  • (8) after_save

That's a total of eight callbacks, which gives you immense power to react and prepare for each state in the Active Record lifecycle. The sequence for calling Base#savean existing record is similar, except that each _on_createcallback is replaced by the corresponding _on_updatecallback.

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
  before_create :record_signup
  private
    def record_signup
      self.signed_up_on = Date.today
    end
end
class Firm < ActiveRecord::Base
  # Destroys the associated clients and people when the firm is destroyed
  before_destroy { |record| Person.destroy_all "firm_id = #{record.id}"   }
  before_destroy { |record| Client.destroy_all "client_of = #{record.id}" }
end

Inheritable callback queues

Besides the overwritable 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#destroyis run only destroy_authoris called. When Reply#destroyis run, both destroy_authorand destroy_readersare 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#destroywould only run destroy_readersand not destroy_author. So, use the callback macros when you want to ensure that a certain callback is called for the entire hierarchy, and use the regular overwriteable methods when you want to leave it up to each descendant to decide whether they want to call superand trigger the inherited callbacks.

IMPORTANT:In order for inheritance to work for the callback queues, you must specify the callbacks before specifying the associations. Otherwise, you might trigger the loading of a child before the parent has registered the callbacks and they won't be inherited.

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 are sometimes 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
  after_save       EncryptionWrapper.new
  after_initialize EncryptionWrapper.new
end
class EncryptionWrapper
  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_find, :after_save
  private
    def encrypt(value)
      # Secrecy is committed
    end
    def decrypt(value)
      # Secrecy is unveiled
    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. You can make these callbacks more flexible by passing in other initialization data such as the name of the attribute to work with:

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.send("#{@attribute}=", encrypt(record.send("#{@attribute}")))
  end
  def after_save(record)
    record.send("#{@attribute}=", decrypt(record.send("#{@attribute}")))
  end
  alias_method :after_find, :after_save
  private
    def encrypt(value)
      # Secrecy is committed
    end
    def decrypt(value)
      # Secrecy is unveiled
    end
end

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 quotes (') 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_findand after_initializeexceptions

Because after_findand after_initializeare called for each object found and instantiated 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_findand after_initializewill only be run if an explicit implementation is defined ( def after_find). In that case, all of the callback types will be called.

before_validation*returning statements

If the returning value of a before_validationcallback can be evaluated to false, the process will be aborted and Base#savewill return false. If ActiveRecord::Base#save! is called it will raise a ActiveRecord::RecordInvalid exception. Nothing will be appended to the errors object.

Canceling callbacks

If a before_*callback returns false, all the later callbacks and the associated action are cancelled. If an after_*callback returns false, all the later callbacks are cancelled. Callbacks are generally run in the order they are defined, with the exception of callbacks defined as methods on the model, which are called last.

Transactions

The entire callback chain of a save, save!, or destroycall runs within a transaction. That includes after_*hooks. If everything goes fine a COMMIT is executed once the chain has been completed.

If a before_*callback cancels the action a ROLLBACK is issued. You can also trigger a ROLLBACK raising an exception in any of the callbacks, including after_*hooks. Note, however, that in that case the client needs to be aware of it because an ordinary savewill raise such exception instead of quietly returning false.

Methods
A
B
Constants
CALLBACKS = %w( after_find after_initialize before_save after_save before_create after_create before_update after_update before_validation after_validation before_validation_on_create after_validation_on_create before_validation_on_update after_validation_on_update before_destroy after_destroy )
 
Instance Public methods
after_create()

Is called after Base.saveon new objects that haven't been saved yet (no record exists). Note that this callback is still wrapped in the transaction around save. For example, if you invoke an external indexer at this point it won't see the changes in the database.

# File activerecord/lib/active_record/callbacks.rb, line 263
def after_create() end
after_destroy()

Is called after Base.destroy(and all the attributes have been frozen).

class Contact < ActiveRecord::Base
  after_destroy { |record| logger.info( "Contact #{record.id} was destroyed." ) }
end
# File activerecord/lib/active_record/callbacks.rb, line 334
def after_destroy()  end
after_save()

Is called after Base.save(regardless of whether it's a createor updatesave). Note that this callback is still wrapped in the transaction around save. For example, if you invoke an external indexer at this point it won't see the changes in the database.

class Contact < ActiveRecord::Base
  after_save { logger.info( 'New contact saved!' ) }
end
# File activerecord/lib/active_record/callbacks.rb, line 247
def after_save()  end
after_update()

Is called after Base.saveon existing objects that have a record. Note that this callback is still wrapped in the transaction around save. For example, if you invoke an external indexer at this point it won't see the changes in the database.

# File activerecord/lib/active_record/callbacks.rb, line 278
def after_update() end
after_validation()

Is called after Validations.validate(which is part of the Base.savecall).

# File activerecord/lib/active_record/callbacks.rb, line 292
def after_validation() end
after_validation_on_create()

Is called after Validations.validate(which is part of the Base.savecall) on new objects that haven't been saved yet (no record exists).

# File activerecord/lib/active_record/callbacks.rb, line 300
def after_validation_on_create()  end
after_validation_on_update()

Is called after Validations.validate(which is part of the Base.savecall) on existing objects that have a record.

# File activerecord/lib/active_record/callbacks.rb, line 308
def after_validation_on_update()  end
before_create()

Is called before Base.saveon new objects that haven't been saved yet (no record exists).

# File activerecord/lib/active_record/callbacks.rb, line 258
def before_create() end
before_destroy()

Is called before Base.destroy.

Note: If you need to destroyor nullifyassociated records first, use the :dependentoption on your associations.

# File activerecord/lib/active_record/callbacks.rb, line 327
def before_destroy() end
before_save()

Is called before Base.save(regardless of whether it's a createor updatesave).

# File activerecord/lib/active_record/callbacks.rb, line 238
def before_save() end
before_update()

Is called before Base.saveon existing objects that have a record.

# File activerecord/lib/active_record/callbacks.rb, line 273
def before_update() end
before_validation()

Is called before Validations.validate(which is part of the Base.savecall).

# File activerecord/lib/active_record/callbacks.rb, line 289
def before_validation() end
before_validation_on_create()

Is called before Validations.validate(which is part of the Base.savecall) on new objects that haven't been saved yet (no record exists).

# File activerecord/lib/active_record/callbacks.rb, line 296
def before_validation_on_create() end
before_validation_on_update()

Is called before Validations.validate(which is part of the Base.savecall) on existing objects that have a record.

# File activerecord/lib/active_record/callbacks.rb, line 304
def before_validation_on_update() end