class PaperTrail::Events::Base
We refer to times in the lifecycle of a record as “events”. There are three events:
-
create
-
‘after_create` we call `RecordTrail#record_create`
-
-
update
-
‘after_update` we call `RecordTrail#record_update`
-
‘after_touch` we call `RecordTrail#record_update`
-
‘RecordTrail#save_with_version` calls `RecordTrail#record_update`
-
‘RecordTrail#update_columns` is also referred to as an update, though it uses `RecordTrail#record_update_columns` rather than `RecordTrail#record_update`
-
-
destroy
-
‘before_destroy` or `after_destroy` we call `RecordTrail#record_destroy`
-
The value inserted into the ‘event` column of the versions table can also be overridden by the user, with `paper_trail_event`.
@api private
Constants
- E_FORBIDDEN_METADATA_KEY
- FORBIDDEN_METADATA_KEYS
Public Class Methods
@api private
# File lib/paper_trail/events/base.rb, line 39 def initialize(record, in_after_callback) @record = record @in_after_callback = in_after_callback end
Public Instance Methods
Determines whether it is appropriate to generate a new version instance. A timestamp-only update (e.g. only ‘updated_at` changed) is considered notable unless an ignored attribute was also changed.
@api private
# File lib/paper_trail/events/base.rb, line 49 def changed_notably? if ignored_attr_has_changed? timestamps = @record.send(:timestamp_attributes_for_update_in_model).map(&:to_s) (notably_changed - timestamps).any? else notably_changed.any? end end
Private Instance Methods
@api private
# File lib/paper_trail/events/base.rb, line 61 def assert_metadatum_key_is_permitted(key) return unless FORBIDDEN_METADATA_KEYS.include?(key.to_sym) raise PaperTrail::InvalidOption, format(E_FORBIDDEN_METADATA_KEY, key, FORBIDDEN_METADATA_KEYS) end
Rails
5.1 changed the API of ‘ActiveRecord::Dirty`. See github.com/paper-trail-gem/paper_trail/pull/899
@api private
# File lib/paper_trail/events/base.rb, line 71 def attribute_changed_in_latest_version?(attr_name) if @in_after_callback @record.saved_change_to_attribute?(attr_name.to_s) else @record.attribute_changed?(attr_name.to_s) end end
Rails
5.1 changed the API of ‘ActiveRecord::Dirty`. See github.com/paper-trail-gem/paper_trail/pull/899
Event can be any of the three (create, update, destroy).
@api private
# File lib/paper_trail/events/base.rb, line 95 def attribute_in_previous_version(attr_name, is_touch) if @in_after_callback && !is_touch # For most events, we want the original value of the attribute, before # the last save. @record.attribute_before_last_save(attr_name.to_s) else # We are either performing a `record_destroy` or a # `record_update(is_touch: true)`. @record.attribute_in_database(attr_name.to_s) end end
@api private
# File lib/paper_trail/events/base.rb, line 108 def calculated_ignored_array ignore = @record.paper_trail_options[:ignore].dup # Remove Hash arguments and then evaluate whether the attributes (the # keys of the hash) should also get pushed into the collection. ignore.delete_if do |obj| obj.is_a?(Hash) && obj.each { |attr, condition| ignore << attr if condition.respond_to?(:call) && condition.call(@record) } end end
@api private
# File lib/paper_trail/events/base.rb, line 121 def changed_and_not_ignored skip = @record.paper_trail_options[:skip] (changed_in_latest_version - calculated_ignored_array) - skip end
@api private
# File lib/paper_trail/events/base.rb, line 127 def changed_in_latest_version # Memoized to reduce memory usage @changed_in_latest_version ||= changes_in_latest_version.keys end
Memoized to reduce memory usage
@api private
# File lib/paper_trail/events/base.rb, line 135 def changes_in_latest_version @changes_in_latest_version ||= load_changes_in_latest_version end
@api private
# File lib/paper_trail/events/base.rb, line 140 def evaluate_only only = @record.paper_trail_options[:only].dup # Remove Hash arguments and then evaluate whether the attributes (the # keys of the hash) should also get pushed into the collection. only.delete_if do |obj| obj.is_a?(Hash) && obj.each { |attr, condition| only << attr if condition.respond_to?(:call) && condition.call(@record) } end only end
An attributed is “ignored” if it is listed in the ‘:ignore` option and/or the `:skip` option. Returns true if an ignored attribute has changed.
@api private
# File lib/paper_trail/events/base.rb, line 158 def ignored_attr_has_changed? ignored = calculated_ignored_array + @record.paper_trail_options[:skip] ignored.any? && (changed_in_latest_version & ignored).any? end
Rails
5.1 changed the API of ‘ActiveRecord::Dirty`. See github.com/paper-trail-gem/paper_trail/pull/899
@api private
# File lib/paper_trail/events/base.rb, line 167 def load_changes_in_latest_version if @in_after_callback @record.saved_changes else @record.changes end end
PT 10 has a new optional column, ‘item_subtype`
@api private
# File lib/paper_trail/events/base.rb, line 178 def merge_item_subtype_into(data) if @record.class.paper_trail.version_class.columns_hash.key?("item_subtype") data.merge!(item_subtype: @record.class.name) end end
Updates ‘data` from `controller_info`.
@api private
# File lib/paper_trail/events/base.rb, line 197 def merge_metadata_from_controller_into(data) metadata = PaperTrail.request.controller_info || {} metadata.keys.each { |k| assert_metadatum_key_is_permitted(k) } data.merge(metadata) end
Updates ‘data` from the model’s ‘meta` option.
@api private
# File lib/paper_trail/events/base.rb, line 206 def merge_metadata_from_model_into(data) @record.paper_trail_options[:meta].each do |k, v| assert_metadatum_key_is_permitted(k) data[k] = model_metadatum(v, data[:event]) end end
Updates ‘data` from the model’s ‘meta` option and from `controller_info`. Metadata is always recorded; that means all three events (create, update, destroy) and `update_columns`.
@api private
# File lib/paper_trail/events/base.rb, line 189 def merge_metadata_into(data) merge_metadata_from_model_into(data) merge_metadata_from_controller_into(data) end
The model method can either be an attribute or a non-attribute method.
If it is an attribute that is changing in an existing object, be sure to grab the correct version.
@api private
# File lib/paper_trail/events/base.rb, line 234 def metadatum_from_model_method(event, method) if event != "create" && @record.has_attribute?(method) && attribute_changed_in_latest_version?(method) attribute_in_previous_version(method, false) else @record.send(method) end end
Given a ‘value` from the model’s ‘meta` option, returns an object to be persisted. The `value` can be a simple scalar value, but it can also be a symbol that names a model method, or even a Proc.
@api private
# File lib/paper_trail/events/base.rb, line 218 def model_metadatum(value, event) if value.respond_to?(:call) value.call(@record) elsif value.is_a?(Symbol) && @record.respond_to?(value, true) metadatum_from_model_method(event, value) else value end end
@api private
# File lib/paper_trail/events/base.rb, line 80 def nonskipped_attributes_before_change(is_touch) record_attributes = @record.attributes.except(*@record.paper_trail_options[:skip]) record_attributes.each_key do |k| if @record.class.column_names.include?(k) record_attributes[k] = attribute_in_previous_version(k, is_touch) end end end
@api private
# File lib/paper_trail/events/base.rb, line 245 def notable_changes changes_in_latest_version.delete_if { |k, _v| notably_changed.exclude?(k) } end
@api private
# File lib/paper_trail/events/base.rb, line 252 def notably_changed # Memoized to reduce memory usage @notably_changed ||= begin only = evaluate_only cani = changed_and_not_ignored only.empty? ? cani : (cani & only) end end
Returns hash of attributes (with appropriate attributes serialized), omitting attributes to be skipped.
@api private
# File lib/paper_trail/events/base.rb, line 265 def object_attrs_for_paper_trail(is_touch) attrs = nonskipped_attributes_before_change(is_touch) AttributeSerializers::ObjectAttribute.new(@record.class).serialize(attrs) attrs end
@api private
# File lib/paper_trail/events/base.rb, line 272 def prepare_object_changes(changes) changes = serialize_object_changes(changes) recordable_object_changes(changes) end
Returns a boolean indicating whether to store the original object during save.
@api private
# File lib/paper_trail/events/base.rb, line 312 def record_object? @record.class.paper_trail.version_class.column_names.include?("object") end
Returns a boolean indicating whether to store serialized version diffs in the ‘object_changes` column of the version record.
@api private
# File lib/paper_trail/events/base.rb, line 305 def record_object_changes? @record.class.paper_trail.version_class.column_names.include?("object_changes") end
Returns an object which can be assigned to the ‘object` attribute of a nascent version record. If the `object` column is a postgres `json` column, then a hash can be used in the assignment, otherwise the column is a `text` column, and we must perform the serialization here, using `PaperTrail.serializer`.
@api private
# File lib/paper_trail/events/base.rb, line 323 def recordable_object(is_touch) if @record.class.paper_trail.version_class.object_col_is_json? object_attrs_for_paper_trail(is_touch) else PaperTrail.serializer.dump(object_attrs_for_paper_trail(is_touch)) end end
Returns an object which can be assigned to the ‘object_changes` attribute of a nascent version record. If the `object_changes` column is a postgres `json` column, then a hash can be used in the assignment, otherwise the column is a `text` column, and we must perform the serialization here, using `PaperTrail.serializer`.
@api private @param changes HashWithIndifferentAccess
# File lib/paper_trail/events/base.rb, line 285 def recordable_object_changes(changes) if PaperTrail.config.object_changes_adapter.respond_to?(:diff) # We'd like to avoid the `to_hash` here, because it increases memory # usage, but that would be a breaking change because # `object_changes_adapter` expects a plain `Hash`, not a # `HashWithIndifferentAccess`. changes = PaperTrail.config.object_changes_adapter.diff(changes.to_hash) end if @record.class.paper_trail.version_class.object_changes_col_is_json? changes else PaperTrail.serializer.dump(changes) end end
@api private
# File lib/paper_trail/events/base.rb, line 332 def serialize_object_changes(changes) AttributeSerializers::ObjectChangesAttribute. new(@record.class). serialize(changes) # We'd like to convert this `HashWithIndifferentAccess` to a plain # `Hash`, but we don't, to save memory. changes end