/
has_paper_trail.rb
377 lines (324 loc) · 16.5 KB
/
has_paper_trail.rb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
module PaperTrail
module Model
def self.included(base)
base.send :extend, ClassMethods
end
module ClassMethods
# Declare this in your model to track every create, update, and destroy. Each version of
# the model is available in the `versions` association.
#
# Options:
# :on the events to track (optional; defaults to all of them). Set to an array of
# `:create`, `:update`, `:destroy` as desired.
# :class_name the name of a custom Version class. This class should inherit from `PaperTrail::Version`.
# :ignore an array of attributes for which a new `Version` will not be created if only they change.
# it can also aceept a Hash as an argument where the key is the attribute to ignore (a `String` or `Symbol`),
# which will only be ignored if the value is a `Proc` which returns truthily.
# :if, :unless Procs that allow to specify conditions when to save versions for an object
# :only inverse of `ignore` - a new `Version` will be created only for these attributes if supplied
# it can also aceept a Hash as an argument where the key is the attribute to track (a `String` or `Symbol`),
# which will only be counted if the value is a `Proc` which returns truthily.
# :skip fields to ignore completely. As with `ignore`, updates to these fields will not create
# a new `Version`. In addition, these fields will not be included in the serialized versions
# of the object whenever a new `Version` is created.
# :meta a hash of extra data to store. You must add a column to the `versions` table for each key.
# Values are objects or procs (which are called with `self`, i.e. the model with the paper
# trail). See `PaperTrail::Controller.info_for_paper_trail` for how to store data from
# the controller.
# :versions the name to use for the versions association. Default is `:versions`.
# :version the name to use for the method which returns the version the instance was reified from.
# Default is `:version`.
def has_paper_trail(options = {})
# Lazily include the instance methods so we don't clutter up
# any more ActiveRecord models than we have to.
send :include, InstanceMethods
class_attribute :version_association_name
self.version_association_name = options[:version] || :version
# The version this instance was reified from.
attr_accessor self.version_association_name
class_attribute :version_class_name
self.version_class_name = options[:class_name] || 'PaperTrail::Version'
class_attribute :paper_trail_options
self.paper_trail_options = options.dup
[:ignore, :skip, :only].each do |k|
paper_trail_options[k] =
[paper_trail_options[k]].flatten.compact.map { |attr| attr.is_a?(Hash) ? attr.stringify_keys : attr.to_s }
end
paper_trail_options[:meta] ||= {}
class_attribute :versions_association_name
self.versions_association_name = options[:versions] || :versions
attr_accessor :paper_trail_event
if ::ActiveRecord::VERSION::MAJOR >= 4 # `has_many` syntax for specifying order uses a lambda in Rails 4
has_many self.versions_association_name,
lambda { order("#{PaperTrail.timestamp_field} ASC") },
:class_name => self.version_class_name, :as => :item
else
has_many self.versions_association_name,
:class_name => self.version_class_name,
:as => :item,
:order => "#{PaperTrail.timestamp_field} ASC"
end
options_on = Array(options[:on]) # so that a single symbol can be passed in without wrapping it in an `Array`
after_create :record_create, :if => :save_version? if options_on.empty? || options_on.include?(:create)
before_update :record_update, :if => :save_version? if options_on.empty? || options_on.include?(:update)
after_destroy :record_destroy, :if => :save_version? if options_on.empty? || options_on.include?(:destroy)
end
# Switches PaperTrail off for this class.
def paper_trail_off!
PaperTrail.enabled_for_model(self, false)
end
def paper_trail_off
warn "DEPRECATED: use `paper_trail_off!` instead of `paper_trail_off`. Support for `paper_trail_off` will be removed in PaperTrail 3.1"
self.paper_trail_off!
end
# Switches PaperTrail on for this class.
def paper_trail_on!
PaperTrail.enabled_for_model(self, true)
end
def paper_trail_on
warn "DEPRECATED: use `paper_trail_on!` instead of `paper_trail_on`. Support for `paper_trail_on` will be removed in PaperTrail 3.1"
self.paper_trail_on!
end
def paper_trail_enabled_for_model?
PaperTrail.enabled_for_model?(self)
end
def paper_trail_version_class
@paper_trail_version_class ||= version_class_name.constantize
end
# Used for Version#object attribute
def serialize_attributes_for_paper_trail(attributes)
# don't serialize before values before inserting into columns of type `JSON` on `PostgreSQL` databases
return attributes if self.paper_trail_version_class.object_col_is_json?
serialized_attributes.each do |key, coder|
if attributes.key?(key)
coder = PaperTrail::Serializers::YAML unless coder.respond_to?(:dump) # Fall back to YAML if `coder` has no `dump` method
attributes[key] = coder.dump(attributes[key])
end
end
end
def unserialize_attributes_for_paper_trail(attributes)
# don't serialize before values before inserting into columns of type `JSON` on `PostgreSQL` databases
return attributes if self.paper_trail_version_class.object_col_is_json?
serialized_attributes.each do |key, coder|
if attributes.key?(key)
coder = PaperTrail::Serializers::YAML unless coder.respond_to?(:dump)
attributes[key] = coder.load(attributes[key])
end
end
end
# Used for Version#object_changes attribute
def serialize_attribute_changes(changes)
# don't serialize before values before inserting into columns of type `JSON` on `PostgreSQL` databases
return changes if self.paper_trail_version_class.object_changes_col_is_json?
serialized_attributes.each do |key, coder|
if changes.key?(key)
coder = PaperTrail::Serializers::YAML unless coder.respond_to?(:dump) # Fall back to YAML if `coder` has no `dump` method
old_value, new_value = changes[key]
changes[key] = [coder.dump(old_value),
coder.dump(new_value)]
end
end
end
def unserialize_attribute_changes(changes)
# don't serialize before values before inserting into columns of type `JSON` on `PostgreSQL` databases
return changes if self.paper_trail_version_class.object_changes_col_is_json?
serialized_attributes.each do |key, coder|
if changes.key?(key)
coder = PaperTrail::Serializers::YAML unless coder.respond_to?(:dump)
old_value, new_value = changes[key]
changes[key] = [coder.load(old_value),
coder.load(new_value)]
end
end
end
end
# Wrap the following methods in a module so we can include them only in the
# ActiveRecord models that declare `has_paper_trail`.
module InstanceMethods
# Returns true if this instance is the current, live one;
# returns false if this instance came from a previous version.
def live?
@is_live ||= source_version.nil?
end
# Returns who put the object into its current state.
def originator
@originator ||= self.class.paper_trail_version_class.with_item_keys(self.class.base_class.name, id).last.try :whodunnit
end
# Returns the object (not a Version) as it was at the given timestamp.
def version_at(timestamp, reify_options={})
# Because a version stores how its object looked *before* the change,
# we need to look for the first version created *after* the timestamp.
v = send(self.class.versions_association_name).subsequent(timestamp).first
v ? v.reify(reify_options) : self
end
# Returns the objects (not Versions) as they were between the given times.
def versions_between(start_time, end_time, reify_options={})
versions = send(self.class.versions_association_name).between(start_time, end_time)
versions.collect { |version| version_at(version.send PaperTrail.timestamp_field) }
end
# Returns the object (not a Version) as it was most recently.
def previous_version
preceding_version = source_version ? source_version.previous : send(self.class.versions_association_name).last
preceding_version.reify if preceding_version
end
# Returns the object (not a Version) as it became next.
# NOTE: if self (the item) was not reified from a version, i.e. it is the
# "live" item, we return nil. Perhaps we should return self instead?
def next_version
subsequent_version = source_version.next
subsequent_version ? subsequent_version.reify : self.class.find(self.id)
rescue
nil
end
def paper_trail_enabled_for_model?
self.class.paper_trail_enabled_for_model?
end
# Executes the given method or block without creating a new version.
def without_versioning(method = nil)
paper_trail_was_enabled = self.paper_trail_enabled_for_model?
self.class.paper_trail_off!
method ? method.to_proc.call(self) : yield(self)
ensure
self.class.paper_trail_on! if paper_trail_was_enabled
end
# Temporarily overwrites the value of whodunnit and then executes the provided block.
def whodunnit(value)
raise ArgumentError, 'expected to receive a block' unless block_given?
current_whodunnit = PaperTrail.whodunnit
PaperTrail.whodunnit = value
yield self
ensure
PaperTrail.whodunnit = current_whodunnit
end
# Mimicks behavior of `touch` method from `ActiveRecord::Persistence`, but generates a version
#
# TODO: lookinto leveraging the `after_touch` callback from `ActiveRecord` to allow the
# regular `touch` method go generate a version as normal. May make sense to switch the `record_update`
# method to leverage an `after_update` callback anyways (likely for v3.1.0)
def touch_with_version(name = nil)
raise ActiveRecordError, "can not touch on a new record object" unless persisted?
attributes = timestamp_attributes_for_update_in_model
attributes << name if name
current_time = current_time_from_proper_timezone
attributes.each { |column| write_attribute(column, current_time) }
save!
end
private
def source_version
send self.class.version_association_name
end
def record_create
if paper_trail_switched_on?
data = {
:event => paper_trail_event || 'create',
:whodunnit => PaperTrail.whodunnit
}
if changed_notably? and self.class.paper_trail_version_class.column_names.include?('object_changes')
data[:object_changes] = self.class.paper_trail_version_class.object_changes_col_is_json? ? changes_for_paper_trail :
PaperTrail.serializer.dump(changes_for_paper_trail)
end
send(self.class.versions_association_name).create! merge_metadata(data)
end
end
def record_update
if paper_trail_switched_on? && changed_notably?
object_attrs = object_attrs_for_paper_trail(item_before_change)
data = {
:event => paper_trail_event || 'update',
:object => self.class.paper_trail_version_class.object_col_is_json? ? object_attrs : PaperTrail.serializer.dump(object_attrs),
:whodunnit => PaperTrail.whodunnit
}
if self.class.paper_trail_version_class.column_names.include?('object_changes')
data[:object_changes] = self.class.paper_trail_version_class.object_changes_col_is_json? ? changes_for_paper_trail :
PaperTrail.serializer.dump(changes_for_paper_trail)
end
send(self.class.versions_association_name).build merge_metadata(data)
end
end
def changes_for_paper_trail
self.changes.delete_if do |key, value|
!notably_changed.include?(key)
end.tap { |changes| self.class.serialize_attribute_changes(changes) }
end
def record_destroy
if paper_trail_switched_on? and not new_record?
object_attrs = object_attrs_for_paper_trail(item_before_change)
data = {
:item_id => self.id,
:item_type => self.class.base_class.name,
:event => paper_trail_event || 'destroy',
:object => self.class.paper_trail_version_class.object_col_is_json? ? object_attrs : PaperTrail.serializer.dump(object_attrs),
:whodunnit => PaperTrail.whodunnit
}
self.class.paper_trail_version_class.create merge_metadata(data)
send(self.class.versions_association_name).send :load_target
end
end
def merge_metadata(data)
# First we merge the model-level metadata in `meta`.
paper_trail_options[:meta].each do |k,v|
data[k] =
if v.respond_to?(:call)
v.call(self)
elsif v.is_a?(Symbol) && respond_to?(v)
# if it is an attribute that is changing, be sure to grab the current version
if has_attribute?(v) && send("#{v}_changed?".to_sym)
send("#{v}_was".to_sym)
else
send(v)
end
else
v
end
end
# Second we merge any extra data from the controller (if available).
data.merge(PaperTrail.controller_info || {})
end
def item_before_change
previous = self.dup
# `dup` clears timestamps so we add them back.
all_timestamp_attributes.each do |column|
previous[column] = send(column) if self.class.column_names.include?(column.to_s) and not send(column).nil?
end
previous.tap do |prev|
prev.id = id # `dup` clears the `id` so we add that back
changed_attributes.select { |k,v| self.class.column_names.include?(k) }.each { |attr, before| prev[attr] = before }
end
end
# returns hash of object attributes (with appropriate attributes serialized), ommitting attributes to be skipped
def object_attrs_for_paper_trail(object)
_attrs = object.attributes.except(*self.paper_trail_options[:skip]).tap do |attributes|
self.class.serialize_attributes_for_paper_trail(attributes)
end
end
def changed_notably?
notably_changed.any?
end
def notably_changed
only = self.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(self) }
end
only.empty? ? changed_and_not_ignored : (changed_and_not_ignored & only)
end
def changed_and_not_ignored
ignore = self.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(self) }
end
skip = self.paper_trail_options[:skip]
changed - ignore - skip
end
def paper_trail_switched_on?
PaperTrail.enabled? && PaperTrail.enabled_for_controller? && self.paper_trail_enabled_for_model?
end
def save_version?
if_condition = self.paper_trail_options[:if]
unless_condition = self.paper_trail_options[:unless]
(if_condition.blank? || if_condition.call(self)) && !unless_condition.try(:call, self)
end
end
end
end