ActiveRecord Callbacks ordering examples

1 files changed, 43 insertions, 0 deletions

diff --git a/activerecord/lib/active_record/callbacks.rb b/activerecord/lib/active_record/callbacks.rb
index 111208d0b9..9626df08aa 100644
--- a/activerecord/lib/active_record/callbacks.rb
+++ b/activerecord/lib/active_record/callbacks.rb
@@ -200,6 +200,49 @@ module ActiveRecord
   # 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
+  # dependant destroy option.
+  #
+  # Let's take at the code below:
+  #
+  #   class Topic < ActiveRecord::Base
+  #
+  #     has_many :children, dependant: destroy
+  #
+  #     before_destroy :log_children
+  #
+  #     def log_children
+  #       children.each do |child|
+  #         # Some child processing
+  #       end
+  #     end
+  #
+  #   end
+  #
+  # In this case the problem is that when the +before_destroy+ is executed, the children are not available
+  # because the dependant destroy gets executed first. To solve this issue it is possible
+  # to use the +prepend+ option on the +before_destroy+ callback.
+  #
+  #   class Topic < ActiveRecord::Base
+  #
+  #     has_many :children, dependant: destroy
+  #
+  #     before_destroy :log_children, prepend: true
+  #
+  #     def log_children
+  #       children.each do |child|
+  #         # Some child processing
+  #       end
+  #     end
+  #
+  #   end
+  #
+  # This way, the +before_destroy+ gets executed before the <tt>dependant: destroy</tt> is called, and
+  # the data is still available.
+  #
   # == Transactions
   #
   # The entire callback chain of a +save+, <tt>save!</tt>, or +destroy+ call runs