- 1.0.0 (0)
- 1.1.6 (0)
- 1.2.6 (10)
- 2.0.3 (8)
- 2.1.0 (0)
- 2.2.1 (27)
- 2.3.8 (26)
- 3.0.0 (20)
- 3.0.9 (-22)
- 3.1.0 (15)
- 3.2.1 (0)
- 3.2.8 (0)
- 3.2.13 (0)
- 4.0.2 (38)
- 4.1.8 (0)
- 4.2.1 (0)
- 4.2.7 (-3)
- 4.2.9 (0)
- 5.0.0.1 (-9)
- 5.1.7 (29)
- 5.2.3 (-1)
- 6.0.0 (-21)
- 6.1.3.1 (2)
- 6.1.7.7 (0)
- 7.0.0 (0)
- 7.1.3.2 (1)
- 7.1.3.4 (0)
- What's this?
Active Record Callbacks
Callbacks are hooks into the life cycle of an Active Record object that allow you to trigger logic before or after a change in the object state. This can be used to make sure that associated and dependent objects are deleted when {ActiveRecord::Base#destroy}[rdoc-ref:Persistence#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 {ActiveRecord::Base#save}[rdoc-ref:Persistence#save] call for a new record:
-
(-) save
-
(-) valid
-
(-) validate
-
(2) after_validation
-
(3) before_save
-
(4) before_create
-
(-) create
-
(5) after_create
-
(6) after_save
-
(7) after_commit
Also, an after_rollback callback can be configured to be triggered whenever a rollback is issued. Check out ActiveRecord::Transactions for more details about after_commit and after_rollback.
Additionally, an after_touch callback is triggered whenever an object is touched.
Lastly an after_find and after_initialize callback is triggered for each object that is found and instantiated by a finder, with after_initialize being triggered after new objects are instantiated as well.
There are nineteen callbacks in total, which give a lot of control over how to react and prepare for each state in the Active Record life cycle. The sequence for calling {ActiveRecord::Base#save}[rdoc-ref:Persistence#save] for an existing record is similar, except that each _create callback is replaced by the corresponding _update callback.
Examples:
class CreditCard < ActiveRecord::Base # Strip everything but digits, so the user can specify "555 234 34" or # "5552-3434" and both will mean "55523434" before_validation(on: :create) do 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 # Disables access to the system, for associated clients and people when the firm is destroyed before_destroy { |record| Person.where(firm_id: record.id).update_all(access: 'disabled') } before_destroy { |record| Client.where(client_of: record.id).update_all(access: 'disabled') } 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 through an inheritance hierarchy.
class Topic < ActiveRecord::Base before_destroy :destroy_author end class Reply < Topic before_destroy :destroy_readers end
When Topic#destroy is run only destroy_author is called. When Reply#destroy is run, both destroy_author and destroy_readers are called.
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 three types of callbacks accepted by the callback macros: method references (symbol), callback objects, inline methods (using a proc). Method references and callback objects are the recommended approaches, inline methods using a proc are sometimes appropriate (such as for creating mix-ins).
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_by(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_initialize, :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 to be 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_initialize, :after_save private def encrypt(value) # Secrecy is committed end def decrypt(value) # Secrecy is unveiled end end
before_validation* returning statements
If the before_validation callback throws :abort, the process will be aborted and {ActiveRecord::Base#save}[rdoc-ref:Persistence#save] will return false. If {ActiveRecord::Base#save!}[rdoc-ref:Persistence#save!] is called it will raise an ActiveRecord::RecordInvalid exception. Nothing will be appended to the errors object.
Canceling callbacks
If a before_* callback throws :abort, all the later callbacks and the associated action 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.
Ordering callbacks
Sometimes application code requires that callbacks execute in a specific order. For example, a before_destroy callback (log_children in this case) should be executed before records in the children association are destroyed by the dependent: :destroy option.
Let’s look at the code below:
class Topic < ActiveRecord::Base has_many :children, dependent: :destroy before_destroy :log_children private def log_children # Child processing end end
In this case, the problem is that when the before_destroy callback is executed, records in the children association no longer exist because the {ActiveRecord::Base#destroy}[rdoc-ref:Persistence#destroy] callback was executed first. You can use the prepend option on the before_destroy callback to avoid this.
class Topic < ActiveRecord::Base has_many :children, dependent: :destroy before_destroy :log_children, prepend: true private def log_children # Child processing end end
This way, the before_destroy is executed before the dependent: :destroy is called, and the data is still available.
Also, there are cases when you want several callbacks of the same type to be executed in order.
For example:
class Topic < ActiveRecord::Base has_many :children after_save :log_children after_save :do_something_else private def log_children # Child processing end def do_something_else # Something else end end
In this case the log_children is executed before do_something_else. This applies to all non-transactional callbacks, and to before_commit.
For transactional after_ callbacks (after_commit, after_rollback, etc), the order can be set via configuration.
config.active_record.run_after_transaction_callbacks_in_order_defined = false
When set to true (the default from Rails 7.1), callbacks are executed in the order they are defined, just like the example above. When set to false, the order is reversed, so do_something_else is executed before log_children.
Transactions
The entire callback chain of a {#save}[rdoc-ref:Persistence#save], {#save!}[rdoc-ref:Persistence#save!], or {#destroy}[rdoc-ref:Persistence#destroy] call 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 {#save}[rdoc-ref:Persistence#save] will raise such exception instead of quietly returning false.
Debugging callbacks
The callback chain is accessible via the _*_callbacks method on an object. Active Model Callbacks support :before, :after and :around as values for the kind property. The kind property defines what part of the chain the callback runs in.
To find all callbacks in the before_save callback chain:
Topic._save_callbacks.select { |cb| cb.kind.eql?(:before) }
Returns an array of callback objects that form the before_save chain.
To further check if the before_save chain contains a proc defined as rest_when_dead use the filter property of the callback object:
Topic._save_callbacks.select { |cb| cb.kind.eql?(:before) }.collect(&:filter).include?(:rest_when_dead)
Returns true or false depending on whether the proc is contained in the before_save callback chain on a Topic model.
Constants
CALLBACKS = [ :after_initialize, :after_find, :after_touch, :before_validation, :after_validation, :before_save, :around_save, :after_save, :before_create, :around_create, :after_create, :before_update, :around_update, :after_update, :before_destroy, :around_destroy, :after_destroy, :after_commit, :after_rollback ]
Attributes
![Default_avatar_30](https://www.gravatar.com/avatar/2fb97d9bab9b2ddf4979e3ea1e5d6ea5?size=30&default=http://apidock.com/images/default_avatar_30.png)
module includes with callbacks
If you write a plugin or module that includes callbacks make sure to define the method and call super after you’re done with your business.
module CoolStuff
def self.included(base) super base.extend(ClassMethods) # the next line seems to clobber. instead opt for defining an inheritable method # base.after_save :chill end module ClassMethods # cool class methods end def chill self.cool = true end def after_save self.chill super # if you don't call super, bloggy won't run end
end # yes I know this next line is a divisive issue but it’s common enough ActiveRecord::Base.send :include, CoolStuff
class Blog < ActiveRecord::Base
after_save :bloggy def bloggy slugify_title end
end
![Default_avatar_30](https://www.gravatar.com/avatar/7bb849e723bac78e14e8c61d583577da?size=30&default=http://apidock.com/images/default_avatar_30.png)
How to test callback methods
When testing callback methods, try to test the callback chain separate from its implementation.
Say this is your model:
class Project belongs_to :owner has_many :milestones after_save :create_milestones after_save :notify_owner private def notify_owner owner.project_created! end def create_milestones milestones.create(:name => 'Milestone 1') end end
You should write your spec like this:
describe Project do describe 'create_milestones' do it 'should create an initial milestone' do project = Project.new project.milestones.should_receive(:create) project.send(:create_milestones) end end describe 'notify_owner' do it 'should notify its owner' do project = Project.new(:owner => mock_model(User)) project.owner.should_receive(:project_created!) project.send(:notify_owner) end end describe 'after_save' do it 'should run the proper callbacks' do project = Project.new project.should_receive(:create_milestones) project.should_receive(:notify_owner) project.run_callbacks(:after_save) end end end
Here is some more advice on how to test callback methods in Rails:
http://gem-session.com/2010/03/how-to-test-callback-methods-in-rails
![Default_avatar_30](https://www.gravatar.com/avatar/98c31121f2534664762297ba01d6b498?size=30&default=http://apidock.com/images/default_avatar_30.png)
You can add if: :query_method and unless: :query_method
You can make the callback conditional:
before_save :before_method, if: :needs_before_method? private def needs_before_method? false end def before_method # .. end