# module ActiveRecord::Callbacks

# Active Record Callbacks¶ ↑

Callbacks are hooks into the life cycle 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 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 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 you immense power 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 down through an inheritance hierarchy.

    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` are called. Contrast this to the following situation where the `before_destroy` method is overridden:

    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 use the regular overwritable methods when you want to leave it up to each descendant to decide whether they want to call `super` and 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_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 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 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 the code needs that the callbacks execute in a specific order. For example, a `before_destroy` callback (`log_children` in this case) should be executed before the children get 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, the children are not available because the ActiveRecord::Base#destroy callback gets 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` gets 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
      has_many :children

      after_save :log_children
      after_save :do_something_else

      private

      def log_chidren
        # Child processing
      end

      def do_something_else
        # Something else
      end
    end

In this case the `log_children` gets executed before `do_something_else`. The same applies to all non-transactional callbacks.

In case there are multiple transactional callbacks as seen below, the order is reversed.

For example:

    class Topic
      has_many :children

      after_commit :log_children
      after_commit :do_something_else

      private

      def log_chidren
        # Child processing
      end

      def do_something_else
        # Something else
      end
    end

In this case the `do_something_else` gets 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.

### Constants

CALLBACKS

### Private Instance Methods

_create_record() click to toggle source
Calls superclass method

    # File lib/active_record/callbacks.rb, line 339
    def _create_record
      _run_create_callbacks { super }
    end

_update_record(*) click to toggle source
Calls superclass method

    # File lib/active_record/callbacks.rb, line 343
    def _update_record(*)
      _run_update_callbacks { super }
    end

create_or_update(*) click to toggle source
Calls superclass method

    # File lib/active_record/callbacks.rb, line 335
    def create_or_update(*)
      _run_save_callbacks { super }
    end