Module: ActiveRecord::Callbacks
Relationships & Source Files | |
Namespace Children | |
Modules:
| |
Extension / Inclusion / Inheritance Descendants | |
Included In:
| |
Super Chains via Extension / Inclusion / Inheritance | |
Class Chain:
self,
::ActiveSupport::Concern
|
|
Defined in: | activerecord/lib/active_record/callbacks.rb |
Overview
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} 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} call for a new record:
-
(-)
save
-
(-)
valid
-
(1)
before_validation
-
(-)
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 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} 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 :
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} will return false
. If {ActiveRecord::Base#save!} is called it will raise an 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} 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, #save!, or #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 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.
Constant Summary
-
CALLBACKS =
# File 'activerecord/lib/active_record/callbacks.rb', line 281[ :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 ]
Class Method Summary
::ActiveSupport::Concern
- Extended
class_methods | Define class methods from given block. |
included | Evaluate given block in context of base class, so that you can write class macros here. |
prepended | Evaluate given block in context of base class, so that you can write class macros here. |
Instance Method Summary
-
#after_create(*args, &block)
Registers a callback to be called after a record is created.
-
#after_destroy(*args, &block)
Registers a callback to be called after a record is destroyed.
-
#after_find(*args, &block)
Registers a callback to be called after a record is instantiated via a finder.
-
#after_initialize(*args, &block)
Registers a callback to be called after a record is instantiated.
-
#after_save(*args, &block)
Registers a callback to be called after a record is saved.
-
#after_touch(*args, &block)
Registers a callback to be called after a record is touched.
-
#after_update(*args, &block)
Registers a callback to be called after a record is updated.
-
#around_create(*args, &block)
Registers a callback to be called around the creation of a record.
-
#around_destroy(*args, &block)
Registers a callback to be called around the destruction of a record.
-
#around_save(*args, &block)
Registers a callback to be called around the save of a record.
-
#around_update(*args, &block)
Registers a callback to be called around the update of a record.
-
#before_create(*args, &block)
Registers a callback to be called before a record is created.
-
#before_destroy(*args, &block)
Registers a callback to be called before a record is destroyed.
-
#before_save(*args, &block)
Registers a callback to be called before a record is saved.
-
#before_update(*args, &block)
Registers a callback to be called before a record is updated.
DSL Calls
included
[ GitHub ]412 413 414 415 416 417
# File 'activerecord/lib/active_record/callbacks.rb', line 412
included do include ActiveModel::Validations::Callbacks define_model_callbacks :initialize, :find, :touch, only: :after define_model_callbacks :save, :create, :update, :destroy end
Instance Method Details
#after_create(*args, &block)
Registers a callback to be called after a record is created. See Callbacks
for more information.
# File 'activerecord/lib/active_record/callbacks.rb', line 356
rdoc_method :method: after_create
#after_destroy(*args, &block)
Registers a callback to be called after a record is destroyed. See Callbacks
for more information.
# File 'activerecord/lib/active_record/callbacks.rb', line 404
rdoc_method :method: after_destroy
#after_find(*args, &block)
Registers a callback to be called after a record is instantiated via a finder. See Callbacks
for more information.
# File 'activerecord/lib/active_record/callbacks.rb', line 300
rdoc_method :method: after_find
#after_initialize(*args, &block)
Registers a callback to be called after a record is instantiated. See Callbacks
for more information.
# File 'activerecord/lib/active_record/callbacks.rb', line 292
rdoc_method :method: after_initialize
#after_save(*args, &block)
Registers a callback to be called after a record is saved. See Callbacks
for more information.
# File 'activerecord/lib/active_record/callbacks.rb', line 332
rdoc_method :method: after_save
#after_touch(*args, &block)
Registers a callback to be called after a record is touched. See Callbacks
for more information.
# File 'activerecord/lib/active_record/callbacks.rb', line 308
rdoc_method :method: after_touch
#after_update(*args, &block)
Registers a callback to be called after a record is updated. See Callbacks
for more information.
# File 'activerecord/lib/active_record/callbacks.rb', line 380
rdoc_method :method: after_update
#around_create(*args, &block)
Registers a callback to be called around the creation of a record. See Callbacks
for more information.
# File 'activerecord/lib/active_record/callbacks.rb', line 348
rdoc_method :method: around_create
#around_destroy(*args, &block)
Registers a callback to be called around the destruction of a record. See Callbacks
for more information.
# File 'activerecord/lib/active_record/callbacks.rb', line 396
rdoc_method :method: around_destroy
#around_save(*args, &block)
Registers a callback to be called around the save of a record. See Callbacks
for more information.
# File 'activerecord/lib/active_record/callbacks.rb', line 324
rdoc_method :method: around_save
#around_update(*args, &block)
Registers a callback to be called around the update of a record. See Callbacks
for more information.
# File 'activerecord/lib/active_record/callbacks.rb', line 372
rdoc_method :method: around_update
#before_create(*args, &block)
Registers a callback to be called before a record is created. See Callbacks
for more information.
# File 'activerecord/lib/active_record/callbacks.rb', line 340
rdoc_method :method: before_create
#before_destroy(*args, &block)
Registers a callback to be called before a record is destroyed. See Callbacks
for more information.
# File 'activerecord/lib/active_record/callbacks.rb', line 388
rdoc_method :method: before_destroy
#before_save(*args, &block)
Registers a callback to be called before a record is saved. See Callbacks
for more information.
# File 'activerecord/lib/active_record/callbacks.rb', line 316
rdoc_method :method: before_save
#before_update(*args, &block)
Registers a callback to be called before a record is updated. See Callbacks
for more information.
# File 'activerecord/lib/active_record/callbacks.rb', line 364
rdoc_method :method: before_update