shrine 2.19.4 → 3.4.0

data/doc/plugins/activerecord.md

@@ -1,93 +1,224 @@
-# Active Record
+---
+title: Active Record
+---
 
-The [`activerecord`][activerecord] plugin extends the "attachment" interface
-with support for ActiveRecord.
+The [`activerecord`][activerecord] plugin adds [Active Record] integration to
+the attachment interface. It is built on top of the [`model`][model] plugin.
 
 ```rb
-plugin :activerecord
+Shrine.plugin :activerecord
 ```
 
-## Callbacks
+## Attachment
 
-Now the attachment module will add additional callbacks to the model:
+Including a `Shrine::Attachment` module into an `ActiveRecord::Base` subclass
+will:
 
-* "before save" – Used by the `recache` plugin.
-* "after commit" (save) – Promotes the attachment, deletes replaced ones.
-* "after commit" (destroy) – Deletes the attachment.
+* add [model] attachment methods
+* add [validations](#validations) and [callbacks](#callbacks) to tie attachment
+  process to the record lifecycle
 
-Note that ActiveRecord versions 3.x and 4.x have errors automatically silenced
-in hooks, which can make debugging more difficult, so it's recommended that you
-enable errors:
+```rb
+class Photo < ActiveRecord::Base # has `image_data` column
+  include ImageUploader::Attachment(:image) # adds methods, callbacks & validations
+end
+```
+```rb
+photo = Photo.new
+
+photo.image = file # cache attachment
+
+photo.image      #=> #<Shrine::UploadedFile id="bc2e13.jpg" storage=:cache ...>
+photo.image_data #=> '{"id":"bc2e13.jpg","storage":"cache","metadata":{...}}'
+
+photo.save # persist, promote attachment, then persist again
+
+photo.image      #=> #<Shrine::UploadedFile id="397eca.jpg" storage=:store ...>
+photo.image_data #=> '{"id":"397eca.jpg","storage":"store","metadata":{...}}'
+
+photo.destroy # delete attachment
+
+photo.image.exists? #=> false
+```
+
+### Callbacks
+
+#### After Save
+
+After a record is saved and the transaction is committed, `Attacher#finalize`
+is called, which promotes cached file to permanent storage and deletes previous
+file if any.
 
 ```rb
-# This is the default in ActiveRecord 5
-ActiveRecord::Base.raise_in_transactional_callbacks = true
+photo = Photo.new
+
+photo.image = file
+photo.image.storage_key #=> :cache
+
+photo.save
+photo.image.storage_key #=> :store
+```
+
+#### After Destroy
+
+After a record is destroyed and the transaction is committed,
+`Attacher#destroy_attached` method is called, which deletes stored attached
+file if any.
+
+```rb
+photo = Photo.find(photo_id)
+photo.image #=> #<Shrine::UploadedFile>
+photo.image.exists? #=> true
+
+photo.destroy
+photo.image.exists? #=> false
 ```
 
-If you want to put promoting/deleting into a background job, see the
-`backgrounding` plugin.
+#### Caveats
 
-Since attaching first saves the record with a cached attachment, then saves
-again with a stored attachment, you can detect this in callbacks:
+Active Record currently has a [bug with transaction callbacks], so if you have
+any "after commit" callbacks, make sure to include Shrine's attachment module
+*after* they have all been defined.
+
+#### Overriding callbacks
+
+You can override any of the following attacher methods to modify callback
+behaviour:
+
+* `Attacher#activerecord_before_save`
+* `Attacher#activerecord_after_save`
+* `Attacher#activerecord_after_destroy`
 
 ```rb
-class User < ActiveRecord::Base
-  include ImageUploader::Attachment.new(:avatar)
-
-  before_save do
-    if avatar_data_changed? && avatar_attacher.cached?
-      # cached
-    elsif avatar_data_changed? && avatar_attacher.stored?
-      # promoted
-    end
+class Shrine::Attacher
+  def activerecord_after_save
+    super
+    # ...
   end
 end
 ```
 
-Note that ActiveRecord currently has a [bug with transaction callbacks], so if
-you have any "after commit" callbacks, make sure to include Shrine's attachment
-module *after* they have all been defined.
+#### Skipping Callbacks
 
-If you don't want the attachment module to add any callbacks to the model, and
-would instead prefer to call these actions manually, you can disable callbacks:
+If you don't want the attachment module to add any callbacks to your model, you
+can set `:callbacks` to `false`:
 
 ```rb
 plugin :activerecord, callbacks: false
 ```
 
-## Validations
+### Validations
 
-Additionally, any Shrine validation errors will be added to ActiveRecord's
-errors upon validation. Note that Shrine validation messages don't have to be
-strings, they can also be symbols or symbols and options, which allows them to
-be internationalized together with other ActiveRecord validation messages.
+If you're using the [`validation`][validation] plugin, the attachment module
+will automatically merge attacher errors with model errors.
 
 ```rb
-class MyUploader < Shrine
+class ImageUploader < Shrine
   plugin :validation_helpers
 
   Attacher.validate do
-    validate_max_size 256 * 1024**2, message: ->(max) { [:max_size, max: max] }
+    validate_max_size 10 * 1024 * 1024
   end
 end
 ```
+```rb
+photo = Photo.new
+photo.image = file
+photo.valid?
+photo.errors #=> { image: ["size must not be greater than 10.0 MB"] }
+```
+
+#### Attachment Presence
 
-If you want to validate presence of the attachment, you can do it directly on
-the model.
+If you want to validate presence of the attachment, you can use Active Record's
+presence validator:
 
 ```rb
-class User < ActiveRecord::Base
-  include ImageUploader::Attachment.new(:avatar)
-  validates_presence_of :avatar
+class Photo < ActiveRecord::Base
+  include ImageUploader::Attachment(:image)
+
+  validates_presence_of :image
 end
 ```
 
+#### I18n
+
+If you want Active Record to translate attacher error messages, you can use
+symbols or arrays of symbols and options for validation errors:
+
+```rb
+class ImageUploader < Shrine
+  plugin :validation_helpers
+
+  Attacher.validate do
+    validate_max_size 10 * 1024 * 1024, message: -> (max) { [:too_large, max: max] }
+    validate_mime_type %w[image/jpeg image/png], message: :not_image
+  end
+end
+```
+```yml
+en:
+  activerecord:
+    errors:
+      models:
+        photo:
+          attributes:
+            image:
+              max_size: "must not be larger than %{max_size} bytes"
+              not_image: "must be a common image format"
+```
+
+#### Skipping Validations
+
 If don't want the attachment module to merge file validations errors into
-model errors, you can disable it:
+model errors, you can set `:validations` to `false`:
 
 ```rb
 plugin :activerecord, validations: false
 ```
 
-[activerecord]: /lib/shrine/plugins/activerecord.rb
+## Attacher
+
+You can also use `Shrine::Attacher` directly (with or without the
+`Shrine::Attachment` module):
+
+```rb
+class Photo < ActiveRecord::Base # has `image_data` column
+end
+```
+```rb
+photo    = Photo.new
+attacher = ImageUploader::Attacher.from_model(photo, :image)
+
+attacher.assign(file) # cache
+
+attacher.file    #=> #<Shrine::UploadedFile id="bc2e13.jpg" storage=:cache ...>
+photo.image_data #=> '{"id":"bc2e13.jpg","storage":"cache","metadata":{...}}'
+
+photo.save        # persist
+attacher.finalize # promote
+photo.save        # persist
+
+attacher.file    #=> #<Shrine::UploadedFile id="397eca.jpg" storage=:store ...>
+photo.image_data #=> '{"id":"397eca.jpg","storage":"store","metadata":{...}}'
+```
+
+### Persistence
+
+The following persistence methods are added to `Shrine::Attacher`:
+
+| Method                    | Description                                                            |
+| :-----                    | :----------                                                            |
+| `Attacher#atomic_promote` | calls `Attacher#promote` and persists if the attachment hasn't changed |
+| `Attacher#atomic_persist` | saves changes if the attachment hasn't changed                         |
+| `Attacher#persist`        | saves any changes to the underlying record                             |
+
+See [persistence] docs for more details.
+
+[activerecord]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/activerecord.rb
+[Active Record]: https://guides.rubyonrails.org/active_record_basics.html
+[model]: https://shrinerb.com/docs/plugins/model
+[callbacks]: https://guides.rubyonrails.org/active_record_callbacks.html
 [bug with transaction callbacks]: https://github.com/rails/rails/issues/14493
+[validation]: https://shrinerb.com/docs/plugins/validation
+[persistence]: https://shrinerb.com/docs/plugins/persistence

data/doc/plugins/add_metadata.md

@@ -1,75 +1,155 @@
-# Add Metadata
+---
+title: Add Metadata
+---
 
-The [`add_metadata`][add_metadata] plugin provides a convenient method for
-extracting and adding custom metadata values.
+The [`add_metadata`][add_metadata] plugin allows adding custom metadata to
+uploaded files.
 
 ```rb
-plugin :add_metadata
+Shrine.plugin :add_metadata
+```
+
+## Metadata block
+
+The `Shrine.add_metadata` method allows you to register a block that will get
+executed on upload, where you can return custom metadata:
+
+```rb
+require "pdf-reader" # https://github.com/yob/pdf-reader
 
-add_metadata :exif do |io, context|
-  begin
-    Exif::Data.new(io).to_h
-  rescue Exif::NotReadable # not a valid image
-    {}
+class PdfUploader < Shrine
+  add_metadata :page_count do |io|
+    reader = PDF::Reader.new(io)
+    reader.page_count
   end
 end
 ```
 
-The above will add "exif" to the metadata hash, and also create the `#exif`
-reader method on Shrine::UploadedFile.
+The above will add `page_count` key to the metadata hash, and also create the
+`#page_count` reader method on the `Shrine::UploadedFile`.
 
 ```rb
-image.metadata["exif"]
+uploaded_file.metadata["page_count"] #=> 30
 # or
-image.exif
+uploaded_file.page_count #=> 30
+```
+
+### Skipping nil values
+
+By default, if your block returns `nil` then the `nil` value will be stored into
+metadata. If you do not want to store anything when your block returns nil, you
+can use the `skip_nil: true` option:
+
+```rb
+class PdfUploader < Shrine
+  add_metadata :pages, skip_nil: true do |io|
+    if is_pdf?(io)
+      reader = PDF::Reader.new(io)
+      reader.page_count
+    else
+      # If this is not a PDF, then the pages metadata will not be stored
+      nil
+    end
+  end
+end
 ```
 
+### Multiple values
+
 You can also extract multiple metadata values at once, by using `add_metadata`
 without an argument and returning a hash of metadata.
 
 ```rb
-add_metadata do |io, context|
-  begin
-    data = Exif::Data.new(io)
-  rescue Exif::NotReadable # not a valid image
-    next {}
+require "exif" # https://github.com/tonytonyjan/exif
+
+class ImageUploader < Shrine
+  add_metadata do |io|
+    begin
+      data = Exif::Data.new(io)
+    rescue Exif::NotReadable # not a valid image
+      next {}
+    end
+
+    { "date_time"     => data.date_time,
+      "flash"         => data.flash,
+      "focal_length"  => data.focal_length,
+      "exposure_time" => data.exposure_time }
   end
-
-  { date_time:     data.date_time,
-    flash:         data.flash,
-    focal_length:  data.focal_length,
-    exposure_time: data.exposure_time }
 end
 ```
+```rb
+uploaded_file.metadata #=>
+# {
+#   ...
+#   "date_time" => "2019:07:20 16:16:08",
+#   "flash" => 16,
+#   "focal_length" => 26/1,
+#   "exposure_time" => 1/500,
+# }
+```
 
 In this case Shrine won't automatically create reader methods for the extracted
-metadata on Shrine::UploadedFile, but you can create them via
-`#metadata_method`.
+metadata, but you can create them via `Shrine.metadata_method`:
 
 ```rb
-metadata_method :date_time, :flash
+class ImageUploader < Shrine
+  # ...
+  metadata_method :date_time, :flash
+end
 ```
+```rb
+uploaded_file.date_time #=> "2019:07:20 16:16:08"
+uploaded_file.flash     #=> 16
+```
+
+### Ensuring file
 
 The `io` might not always be a file object, so if you're using an analyzer
 which requires the source file to be on disk, you can use `Shrine.with_file` to
 ensure you have a file object.
 
 ```rb
-add_metadata do |io, context|
-  movie = Shrine.with_file(io) { |file| FFMPEG::Movie.new(file.path) }
+require "streamio-ffmpeg" # https://github.com/streamio/streamio-ffmpeg
+
+class VideoUploader < Shrine
+  add_metadata do |io|
+    movie = Shrine.with_file(io) do |file|
+      FFMPEG::Movie.new(file.path)
+    end
+
+    { "duration"   => movie.duration,
+      "bitrate"    => movie.bitrate,
+      "resolution" => movie.resolution,
+      "frame_rate" => movie.frame_rate }
+  end
+end
+```
+
+### Uploader options
+
+Uploader options are also yielded to the block, you can access them for more
+context:
 
-  { "duration"   => movie.duration,
-    "bitrate"    => movie.bitrate,
-    "resolution" => movie.resolution,
-    "frame_rate" => movie.frame_rate }
+```rb
+add_metadata do |io, **options|
+  options #=>
+  # {
+  #   record:   #<Photo>,
+  #   name:     :image,
+  #   action:   :store,
+  #   metadata: { ... },
+  #   ...
+  # }
 end
 ```
 
-Any previously extracted metadata can be accessed via `context[:metadata]`:
+#### Metadata
+
+The `:metadata` option holds metadata that was extracted so far:
 
 ```rb
-add_metadata :foo do |io, context|
-  context[:metadata] #=>
+add_metadata :foo do |io, metadata:, **|
+  metadata #=>
   # {
   #   "size"      => 239823,
   #   "filename"  => "nature.jpg",
@@ -79,8 +159,8 @@ add_metadata :foo do |io, context|
   "foo"
 end
 
-add_metadata :bar do |io, context|
-  context[:metadata] #=>
+add_metadata :bar do |io, metadata:, **|
+  metadata #=>
   # {
   #   "size"      => 239823,
   #   "filename"  => "nature.jpg",
@@ -92,4 +172,25 @@ add_metadata :bar do |io, context|
 end
 ```
 
-[add_metadata]: /lib/shrine/plugins/add_metadata.rb
+## Updating metadata
+
+If you just wish to add some custom metadata to existing uploads, you can do it
+with `UploadedFile#add_metadata` (and write the changes back to the model):
+
+```rb
+attacher.file.add_metadata("foo" => "bar")
+attacher.write # write changes to the model attribute
+
+attacher.file.metadata #=> { ..., "foo" => "bar" }
+```
+
+You can also use the `Attacher#add_metadata` shorthand, which also takes care
+of syncing the model:
+
+```rb
+attacher.add_metadata("foo" => "bar")
+
+attacher.file.metadata #=> { ..., "foo" => "bar" }
+```
+
+[add_metadata]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/add_metadata.rb