shrine 2.19.4 → 3.4.0

data/doc/paperclip.md

@@ -1,15 +1,60 @@
-# Shrine for Paperclip Users
+---
+title: Upgrading from Paperclip
+---
 
 This guide is aimed at helping Paperclip users transition to Shrine, and it
 consists of three parts:
 
 1. Explanation of the key differences in design between Paperclip and Shrine
-2. Instructions how to migrate and existing app that uses Paperclip to Shrine
+2. Instructions how to migrate an existing app that uses Paperclip to Shrine
 3. Extensive reference of Paperclip's interface with Shrine equivalents
 
-## Storages
+## Overview
 
-In Paperclip the storage is configure inside the global options:
+### Uploader
+
+In Paperclip, the attachment logic is configured directly inside Active Record
+models:
+
+```rb
+class Photo < ActiveRecord::Base
+  has_attached_file :image,
+    preserve_files: true,
+    default_url:    "/images/:style/missing.png"
+
+  validated_attachment_content_type :image, content_type: "image/jpeg"
+end
+```
+
+Shrine takes a more object-oriented approach, by encapsulating attachment logic
+in "uploader" classes:
+
+```rb
+class ImageUploader < Shrine
+  plugin :keep_files
+  plugin :default_url
+  plugin :validation_helpers
+
+  Attacher.default_url do |derivative: nil, **|
+    "/images/#{derivative}/missing.png" if derivative
+  end
+
+  Attacher.validate do
+    validate_mime_type %w[image/jpeg]
+  end
+end
+```
+```rb
+class Photo < ActiveRecord::Base
+  include ImageUploader::Attachment(:image)
+end
+```
+
+### Storage
+
+Paperclip storage is configured together with other attachment options. Also,
+the storage implementations themselves are mixed into the attachment class,
+which couples them to the attachment flow.
 
 ```rb
 class Photo < ActiveRecord::Base
@@ -24,7 +69,8 @@ class Photo < ActiveRecord::Base
 end
 ```
 
-In contrast, a Shrine storage is just a class which you configure individually:
+Shrine storage objects are configured separately and are decoupled from
+attachment:
 
 ```rb
 Shrine.storages[:store] = Shrine::Storage::S3.new(
@@ -35,10 +81,8 @@ Shrine.storages[:store] = Shrine::Storage::S3.new(
 )
 ```
 
-Paperclip doesn't have a concept of "temporary" storage, so it cannot retain
-uploaded files in case of validation errors, and [direct S3 uploads] cannot be
-implemented in a safe way. Shrine uses separate "temporary" and "permanent"
-storage for attaching files:
+Shrine also has a concept of "temporary" storage, which enables retaining
+uploaded files in case of validation errors and [direct uploads].
 
 ```rb
 Shrine.storages = {
@@ -47,42 +91,79 @@ Shrine.storages = {
 }
 ```
 
-## Uploaders
+### Persistence
+
+When using Paperclip, the attached file data will be persisted into several
+columns:
+
+* `<name>_file_name`
+* `<name>_content_type`
+* `<name>_file_size`
+* `<name>_updated_at`
+* `<name>_created_at` (optional)
+* `<name>_fingerprint` (optional)
 
-While in Paperclip you define all your uploading logic inside your models,
-Shrine takes a more object-oriented approach and lets you define uploading logic
-inside "uploader" classes:
+In contrast, Shrine uses a single `<name>_data` column to store data in JSON
+format:
 
 ```rb
-class Photo < ActiveRecord::Base
-  has_attached_file :image
-end
+{
+  "id": "path/to/image.jpg",
+  "storage": "store",
+  "metadata": {
+    "filename": "nature.jpg",
+    "size": 4739472,
+    "mime_type": "image/jpeg"
+  }
+}
 ```
-
 ```rb
-class ImageUploader < Shrine
-  # ...
-end
+photo.image.id          #=> "path/to/image.jpg"
+photo.image.storage_key #=> :store
+photo.image.metadata    #=> { "filename" => "...", "size" => ..., "mime_type" => "..." }
 
-class Photo < ActiveRecord::Base
-  include ImageUploader::Attachment.new(:image)
-end
+photo.image.original_filename #=> "nature.jpg"
+photo.image.size              #=> 4739472
+photo.image.mime_type         #=> "image/jpeg"
 ```
 
-Among other things, this allows you to use uploader classes standalone, which
-gives you more power:
+This column can be queried if it's made a JSON column. Alternatively, you can
+use the [`metadata_attributes`][metadata_attributes] plugin to save metadata
+into separate columns.
+
+#### ORM
+
+While Paperclip works only with Active Record, Shrine is designed to integrate
+with any persistence library (there are integrations for [Active
+Record][activerecord], [Sequel][sequel], [ROM][rom], [Hanami][hanami] and
+[Mongoid][mongoid]), and can also be used standalone:
 
 ```rb
-uploaded_file = ImageUploader.upload(File.open("nature.jpg"), :store)
-uploaded_file     #=> #<Shrine::UploadedFile>
-uploaded_file.url #=> "https://my-bucket.s3.amazonaws.com/store/kfds0lg9rer.jpg"
+attacher = ImageUploader::Attacher.new
+attacher.attach File.open("nature.jpg")
+attacher.file #=> #<Shrine::UploadedFile id="f4ba5bdbf366ef0b.jpg" ...>
+attacher.url  #=> "https://my-bucket.s3.amazonaws.com/f4ba5bdbf366ef0b.jpg"
+attacher.data #=> { "id" => "f4ba5bdbf366ef0b.jpg", "storage" => "store", "metadata" => { ... } }
 ```
 
+#### Location
+
+Paperclip persists only the filename of the uploaded file, and recalculates the
+full location dynamically based on location configuration. This can be
+dangerous, because if some component of the location happens to change, all
+existing links might become invalid.
+
+To avoid this, Shrine persists the full location on attachment, and uses it
+when generating file URL. So, even if you change how file locations are
+generated, existing files that are on old locations will still remain
+accessible.
+
 ### Processing
 
-In contrast to Paperclip's static options, in Shrine you define and perform
-processing on instance-level. The result of processing can be a single file
-or a hash of versions:
+In Shrine, processing is defined and performed on the instance level, which
+gives you more control. You're also not coupled to ImageMagick, e.g. you can
+use [libvips] instead (both integrations are provided by the [image_processing]
+gem).
 
 ```rb
 class Photo < ActiveRecord::Base
@@ -99,47 +180,65 @@ end
 require "image_processing/mini_magick"
 
 class ImageUploader < Shrine
-  plugin :processing
-  plugin :versions
-
-  process(:store) do |io, context|
-    versions = { original: io } # retain original
+  plugin :derivatives
 
-    io.download do |original|
-      pipeline = ImageProcessing::MiniMagick.source(original)
+  Attacher.derivatives do |original|
+    magick = ImageProcessing::MiniMagick.source(original)
 
-      versions[:large]  = pipeline.resize_to_limit!(800, 800)
-      versions[:medium] = pipeline.resize_to_limit!(500, 500)
-      versions[:small]  = pipeline.resize_to_limit!(300, 300)
-    end
-
-    versions # return the hash of processed files
+    {
+      large:  magick.resize_to_limit!(800, 800),
+      medium: magick.resize_to_limit!(500, 500),
+      small:  magick.resize_to_limit!(300, 300),
+    }
   end
 end
 ```
 
-This allows you to fully optimize processing, because you can easily specify
-which files are processed from which, and even add parallelization.
+Shrine is agnostic as to how you're performing your processing, so you can
+easily use any other processing tools. You can also combine different
+processors for different versions.
+
+#### Retrieving versions
+
+When retrieving versions, Paperclip returns a list of declared styles which
+may or may not have been generated. In contrast, Shrine persists data of
+uploaded processed files into the database (including any extracted metadata),
+which then becomes the source of truth on which versions have been generated.
+
+```rb
+photo.image              #=> #<Shrine::UploadedFile id="original.jpg" ...>
+photo.image_derivatives  #=> {}
+
+photo.image_derivatives! # triggers processing
+photo.image_derivatives  #=>
+# {
+#   large: #<Shrine::UploadedFile id="large.jpg" metadata={"size"=>873232, ...} ...>,
+#   medium: #<Shrine::UploadedFile id="medium.jpg" metadata={"size"=>94823, ...} ...>,
+#   small: #<Shrine::UploadedFile id="small.jpg" metadata={"size"=>37322, ...} ...>,
+# }
+```
 
 #### Reprocessing versions
 
 Shrine doesn't have a built-in way of regenerating versions, because that has
-to be written and optimized differently depending on whether you're adding or
-removing a version, what ORM are you using, how many records there are in the
-database etc. The [Reprocessing versions] guide provides some useful tips on
-this task.
+to be written and optimized differently depending on what versions have changed
+which persistence library you're using, how many records there are in the table
+etc.
+
+However, there is an extensive guide for [Managing Derivatives], which provides
+instructions on how to make these changes safely and with zero downtime.
 
-### Validations
+### Validation
 
-Validations are also defined inside the uploader on the instance-level, which
-allows you to do conditional validations:
+File validation in Shrine is also instance-level, which allows using
+conditionals:
 
 ```rb
 class Photo < ActiveRecord::Base
   has_attached_file :image
   validates_attachment :image,
-    content_type: {content_type: %w[image/jpeg image/png image/gif]},
-    size: {in: 0..10.megabytes}
+    size: { in: 0..10.megabytes },
+    content_type: { content_type: %w[image/jpeg image/png image/webp] }
 end
 ```
 
@@ -148,151 +247,83 @@ class ImageUploader < Shrine
   plugin :validation_helpers
 
   Attacher.validate do
-    validate_mime_type_inclusion %w[image/jpeg image/gif image/png]
-    validate_max_size 10*1024*1024 unless record.admin?
+    validate_max_size 10*1024*1024
+
+    if validate_mime_type %w[image/jpeg image/png image/webp]
+      validate_max_dimensions [5000, 5000]
+    end
   end
 end
 ```
 
-#### MIME type spoofing
-
-Paperclip detects MIME type spoofing, in the way that it extracts the MIME type
-from file contents using the `file` command and MimeMagic, compares it to the
-value that the `mime-types` gem determined from file extension, and raises a
-validation error if these two values mismatch.
-
-However, this turned out to be very problematic, leading to a lot of valid
-files being classified as "spoofed", because of the differences of MIME
-type databases between the `mime-types` gem, `file` command, and MimeMagic.
+#### Custom metadata
 
-Shrine takes a different approach here. By default it will extract MIME
-type from file extension, but it has a plugin for determining MIME type from
-file contents, which by default uses the `file` command:
+With Shrine you can also extract and validate any custom metadata:
 
 ```rb
-Shrine.plugin :determine_mime_type
-```
+class VideoUploader < Shrine
+  plugin :add_metadata
+  plugin :validation
 
-However, it doesn't try to compare this value with the one from file extension,
-it just means that now this value will be used for your MIME type validations.
-With this approach you can still prevent malicious files from being attached,
-but without the possibility of false negatives.
-
-### Logging
-
-In Paperclip you enable logging by setting `Paperclip.options[:log] = true`,
-however, this only logs ImageMagick commands. Shrine has full logging support,
-which measures processing, uploading and deleting individually:
+  add_metadata :duration do |io|
+    FFMPEG::Movie.new(io.path).duration
+  end
 
-```rb
-Shrine.plugin :instrumentation
-```
-```
-Metadata (32ms) – {:storage=>:store, :io=>StringIO, :uploader=>Shrine}
-Upload (1523ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1700b4", :io=>StringIO, :upload_options=>{}, :uploader=>Shrine}
-Exists (755ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1700b4", :uploader=>Shrine}
-Download (1002ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1700b4", :download_options=>{}, :uploader=>Shrine}
-Delete (700ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1700b4", :uploader=>Shrine}
+  Attacher.validate do
+    if file.duration > 5*60*60
+      errors << "must not be longer than 5 hours"
+    end
+  end
+end
 ```
 
-## Attachments
-
-While Paperclip is designed to only integrate with ActiveRecord, Shrine is
-designed to be completely generic and integrate with any ORM. It ships with
-plugins for ActiveRecord and Sequel:
+#### MIME type spoofing
 
-```rb
-Shrine.plugin :activerecord # if you're using ActiveRecord
-Shrine.plugin :sequel       # if you're using Sequel
-```
+Paperclip attempts to detect MIME type spoofing, which turned out to be
+unreliable due to differences in MIME type databases between different ruby
+libraries.
 
-Instead of giving you class methods for defining attachments, in Shrine you
-generate attachment modules which you simply include in your models, which
-gives your models similar set of methods that Paperclip gives:
+Shrine on the other hand simply allows you to determine MIME type from file
+content, which you can then validate.
 
 ```rb
-class Photo < Sequel::Model
-  include ImageUploader::Attachment.new(:image)
-end
+Shrine.plugin :determine_mime_type, analyzer: :marcel
 ```
-
-### Attachment column
-
-Unlike in Paperclip which requires you to have 4 `<attachment>_*` columns, in
-Shrine you only need to have a single `<attachment>_data` text column (in the
-above case `image_data`), and all information will be stored there.
-
 ```rb
-photo.image_data #=>
-# {
-#   "storage" => "store",
-#   "id" => "photo/1/image/0d9o8dk42.png",
-#   "metadata" => {
-#     "filename"  => "nature.png",
-#     "size"      => 49349138,
-#     "mime_type" => "image/png"
-#   }
-# }
-
-photo.image.original_filename #=> "nature.png"
-photo.image.size              #=> 49349138
-photo.image.mime_type         #=> "image/png"
+file = uploader.upload StringIO.new("<?php ... ?>")
+file.mime_type #=> "application/x-php"
 ```
 
-Unlike Paperclip, Shrine will store this information for each processed
-version, making them first-class citizens:
-
-```rb
-photo.image[:original]       #=> #<Shrine::UploadedFile>
-photo.image[:original].width #=> 800
-
-photo.image[:thumb]          #=> #<Shrine::UploadedFile>
-photo.image[:thumb].width    #=> 300
-```
+## Migrating from Paperclip
 
-Also, since Paperclip stores only the filename, it has to recalculate the full
-location each time it wants to generate the URL. That makes it really difficult
-to move files to a new location, because changing how the location is generated
-will now cause incorrect URLs to be generated for all existing files. Shrine
-calculates the whole location only once and saves it to the column.
+You have an existing app using Paperclip and you want to transfer it to Shrine.
+Let's assume we have a `Photo` model with the "image" attachment.
 
-### Hooks/Callbacks
+### 1. Add Shrine column
 
-Shrine's `hooks` plugin provides callbacks for Shrine, so to get Paperclip's
-`(before|after)_post_process`, you can override `#before_process` and
-`#after_process` methods:
+First we need to create the `image_data` column for Shrine:
 
 ```rb
-class ImageUploader < Shrine
-  plugin :hooks
-
-  def before_process(io, context)
-    # ...
-    super
-  end
-
-  def after_process(io, context)
-    super
-    # ...
-  end
-end
+add_column :photos, :image_data, :text
 ```
 
-## Migrating from Paperclip
+### 2. Dual write
 
-You have an existing app using Paperclip and you want to transfer it to Shrine.
-First we need to make new uploads write to the `<attachment>_data` column.
-Let's assume we have a `Photo` model with the "image" attachment:
+Next, we need to make new Paperclip attachments write to the `image_data`
+column. This can be done by including the below module to all models that have
+Paperclip attachments:
 
 ```rb
-add_column :photos, :image_data, :text
-```
+require "shrine"
 
-Afterwards we need to make new uploads write to the `image_data` column. This
-can be done by including the below module to all models that have Paperclip
-attachments:
+Shrine.storages = {
+  cache: ...,
+  store: ...,
+}
+
+Shrine.plugin :model
+Shrine.plugin :derivatives
 
-```rb
 module PaperclipShrineSynchronization
   def self.included(model)
     model.before_save do
@@ -304,49 +335,62 @@ module PaperclipShrineSynchronization
 
   def write_shrine_data(name)
     attachment = send(name)
+    attacher   = Shrine::Attacher.from_model(self, name)
 
     if attachment.size.present?
-      data = attachment_to_shrine_data(attachment)
+      attacher.set shrine_file(attachment)
 
-      if attachment.styles.any?
-        data = {original: data}
-        attachment.styles.each do |name, style|
-          data[name] = style_to_shrine_data(style)
-        end
+      attachment.styles.each do |style_name, style|
+        attacher.merge_derivatives(style_name => shrine_file(style))
       end
-
-      write_attribute(:"#{name}_data", data.to_json)
     else
-      write_attribute(:"#{name}_data", nil)
+      attacher.set nil
     end
   end
 
   private
 
-  # If you'll be using a `:prefix` on your Shrine storage, or you're storing
-  # files on the filesystem, make sure to subtract the appropriate part
-  # from the path assigned to `:id`.
-  def attachment_to_shrine_data(attachment)
-    {
-      storage: :store,
-      id: attachment.path,
+  def shrine_file(object)
+    if object.is_a?(Paperclip::Attachment)
+      shrine_attachment_file(object)
+    else
+      shrine_style_file(object)
+    end
+  end
+
+  def shrine_attachment_file(attachment)
+    location = attachment.path
+    # if you're storing files on disk, make sure to subtract the absolute path
+    location = location.sub(%r{^#{storage.prefix}/}, "") if storage.prefix
+
+    Shrine.uploaded_file(
+      storage:  :store,
+      id:       location,
       metadata: {
-        size: attachment.size,
-        filename: attachment.original_filename,
-        mime_type: attachment.content_type,
+        "size"      => attachment.size,
+        "filename"  => attachment.original_filename,
+        "mime_type" => attachment.content_type,
       }
-    }
+    )
   end
 
   # If you'll be using a `:prefix` on your Shrine storage, or you're storing
   # files on the filesystem, make sure to subtract the appropriate part
   # from the path assigned to `:id`.
-  def style_to_shrine_data(style)
-    {
-      storage: :store,
-      id: style.attachment.path(style.name),
-      metadata: {}
-    }
+  def shrine_style_file(style)
+    location = style.attachment.path(style.name)
+    # if you're storing files on disk, make sure to subtract the absolute path
+    location = location.sub(%r{^#{storage.prefix}/}, "") if storage.prefix
+
+    Shrine.uploaded_file(
+      storage:  :store,
+      id:       location,
+      metadata: {},
+    )
+  end
+
+  def storage
+    Shrine.storages[:store]
   end
 end
 ```
@@ -358,34 +402,35 @@ end
 ```
 
 After you deploy this code, the `image_data` column should now be successfully
-synchronized with new attachments.  Next step is to run a script which writes
-all existing Paperclip attachments to `image_data`:
+synchronized with new attachments.
+
+### 3. Data migration
+
+Next step is to run a script which writes all existing Paperclip attachments to
+`image_data`:
 
 ```rb
 Photo.find_each do |photo|
-  Paperclip::AttachmentRegistry.each_definition do |klass, name, options|
-    photo.write_shrine_data(name) if klass == Photo
-  end
+  photo.write_shrine_data(:image)
   photo.save!
 end
 ```
 
+### 4. Rewrite code
+
 Now you should be able to rewrite your application so that it uses Shrine
-instead of Paperclip, using equivalent Shrine storages. For help with
-translating the code from Paperclip to Shrine, you can consult the reference
-below.
+instead of Paperclip (you can consult the reference in the next section). You
+can remove the `PaperclipShrineSynchronization` module as well.
 
-You'll notice that Shrine metadata will be absent from the migrated files' data
-(specifically versions). You can run a script that will fill in any missing
-metadata defined in your Shrine uploader:
+### 5. Remove Paperclip columns
 
-```rb
-Shrine.plugin :refresh_metadata
+If everything is looking good, we can remove Paperclip columns:
 
-Photo.find_each do |photo|
-  attachment = ImageUploader.uploaded_file(photo.image, &:refresh_metadata!)
-  photo.update(image_data: attachment.to_json)
-end
+```rb
+remove_column :photos, :image_file_name
+remove_column :photos, :image_file_size
+remove_column :photos, :image_content_type
+remove_column :photos, :image_updated_at
 ```
 
 ## Paperclip to Shrine direct mapping
@@ -396,8 +441,8 @@ As mentioned above, Shrine's equivalent of `has_attached_file` is including
 an attachment module:
 
 ```rb
-class User < Sequel::Model
-  include ImageUploader::Attachment.new(:avatar) # adds `avatar`, `avatar=` and `avatar_url` methods
+class Photo < Sequel::Model
+  include ImageUploader::Attachment(:image) # adds `image`, `image=` and `image_url` methods
 end
 ```
 
@@ -420,8 +465,23 @@ You can change that for a specific uploader with the `default_storage` plugin.
 
 #### `:styles`, `:processors`, `:convert_options`
 
-As explained in the "Processing" section, processing is done by overriding the
-`Shrine#process` method.
+Processing is defined by using the `derivatives` plugin:
+
+```rb
+class ImageUploader < Shrine
+  plugin :derivatives
+
+  Attacher.derivatives do |original|
+    magick = ImageProcessing::MiniMagick.source(original)
+
+    {
+      large:  magick.resize_to_limit!(800, 800),
+      medium: magick.resize_to_limit!(500, 500),
+      small:  magick.resize_to_limit!(300, 300),
+    }
+  end
+end
+```
 
 #### `:default_url`
 
@@ -431,8 +491,8 @@ For default URLs you can use the `default_url` plugin:
 class ImageUploader < Shrine
   plugin :default_url
 
-  Attacher.default_url do |options|
-    "/attachments/#{name}/default.jpg"
+  Attacher.default_url do |derivative: nil, **|
+    "/images/placeholders/#{derivative || "original"}.jpg"
   end
 end
 ```
@@ -443,7 +503,7 @@ Shrine provides a `keep_files` plugin which allows you to keep files that would
 otherwise be deleted:
 
 ```rb
-Shrine.plugin :keep_files, destroyed: true
+Shrine.plugin :keep_files
 ```
 
 #### `:path`, `:url`, `:interpolator`, `:url_generator`
@@ -460,38 +520,108 @@ Alternatively, if you want to generate locations yourself you can override the
 
 ```rb
 class ImageUploader < Shrine
-  def generate_location(io, context)
-    # ...
+  def generate_location(io, record: nil, name: nil, **)
+    [ storage_key,
+      record && record.class.name.underscore,
+      record && record.id,
+      super,
+      io.original_filename ].compact.join("/")
   end
 end
 ```
+```
+cache/user/123/2feff8c724e7ce17/nature.jpg
+store/user/456/7f99669fde1e01fc/kitten.jpg
+...
+```
 
 #### `:validate_media_type`
 
 Shrine has this functionality in the `determine_mime_type` plugin.
 
+### `validates_attachment`
+
+#### `:presence`
+
+For presence validation you can use your ORM's presence validator:
+
+```rb
+class Photo < ActiveRecord::Base
+  include ImageUploader::Attachment(:image)
+  validates_presence_of :image
+end
+```
+
+#### `:content_type`
+
+You can do MIME type validation with Shrine's `validation_helpers` plugin:
+
+```rb
+class ImageUploader < Shrine
+  plugin :validation_helpers
+
+  Attacher.validate do
+    validate_mime_type %w[image/jpeg image/png image/webp]
+  end
+end
+```
+
+Make sure to also load the `determine_mime_type` plugin to detect MIME type
+from file content.
+
+```rb
+# Gemfile
+gem "mimemagic"
+```
+```rb
+Shrine.plugin :determine_mime_type, analyzer: -> (io, analyzers) do
+  analyzers[:mimemagic].call(io) || analyzers[:file].call(io)
+end
+```
+
+#### `:size`
+
+You can do filesize validation with Shrine's `validation_helpers` plugin:
+
+```rb
+class ImageUploader < Shrine
+  plugin :validation_helpers
+
+  Attacher.validate do
+    validate_max_size 10*1024*1024
+  end
+end
+```
+
 ### `Paperclip::Attachment`
 
 This section explains the equivalent of Paperclip attachment's methods, in
 Shrine this is an instance of `Shrine::UploadedFile`.
 
-#### `#url`, `#styles`
+#### `#url`
+
+In Shrine you can generate URLs with `#<name>_url`:
+
+```rb
+photo.image_url         #=> "https://example.com/path/to/original.jpg"
+photo.image_url(:large) #=> "https://example.com/path/to/large.jpg"
+```
+
+#### `#styles`
 
-If you're generating versions in Shrine, the attachment will be a hash of
-uploaded files:
+In Shrine you can use `#<name>_derivatives` to retrieve a list of versions:
 
 ```rb
-user.avatar.class #=> Hash
-user.avatar #=>
+photo.image_derivatives #=>
 # {
 #   small:  #<Shrine::UploadedFile>,
 #   medium: #<Shrine::UploadedFile>,
 #   large:  #<Shrine::UploadedFile>,
 # }
 
-user.avatar[:small].url #=> "..."
+photo.image_derivatives[:small] #=> #<Shrine::UploadedFile>
 # or
-user.avatar_url(:small) #=> "..."
+photo.image(:small) #=> #<Shrine::UploadedFile>
 ```
 
 #### `#path`
@@ -500,17 +630,17 @@ Shrine doesn't have this because storages are abstract and this would be
 specific to the filesystem, but the closest is probably `#id`:
 
 ```rb
-user.avatar.id #=> "users/342/avatar/398543qjfdsf.jpg"
+photo.image.id #=> "photo/342/image/398543qjfdsf.jpg"
 ```
 
 #### `#reprocess!`
 
-Shrine doesn't have an equivalent to this, but the [Reprocessing versions]
+Shrine doesn't have an equivalent to this, but the [Managing Derivatives]
 guide provides some useful tips on how to do this.
 
 ### `Paperclip::Storage::S3`
 
-The built-in [`Shrine::Storage::S3`] storage is a direct replacement for
+The built-in [`Shrine::Storage::S3`][S3] storage is a direct replacement for
 `Paperclip::Storage::S3`.
 
 #### `:s3_credentials`, `:s3_region`, `:bucket`
@@ -527,43 +657,28 @@ Shrine::Storage::S3.new(
 )
 ```
 
-#### `:s3_headers`
-
-The object data can be configured via the `:upload_options` hash:
-
-```rb
-Shrine::Storage::S3.new(upload_options: {content_disposition: "attachment"}, **options)
-```
-
-You can use the `upload_options` plugin to set upload options dynamically.
-
-#### `:s3_permissions`
-
-The object permissions can be configured with the `:acl` upload option:
-
-```rb
-Shrine::Storage::S3.new(upload_options: {acl: "private"}, **options)
-```
-
-You can use the `upload_options` plugin to set upload options dynamically.
-
-#### `:s3_metadata`
+#### `:s3_headers`, `:s3_permissions`, `:s3_metadata`
 
-The object metadata can be configured with the `:metadata` upload option:
+These can be configured via the `:upload_options` option:
 
 ```rb
-Shrine::Storage::S3.new(upload_options: {metadata: {"key" => "value"}}, **options)
+Shrine::Storage::S3.new(
+  upload_options: {
+    content_disposition: "attachment",         # headers
+    acl:                 "private",            # permissions
+    metadata:            { "key" => "value" }, # metadata
+  },
+  **options
+)
 ```
 
-You can use the `upload_options` plugin to set upload options dynamically.
-
 #### `:s3_protocol`, `:s3_host_alias`, `:s3_host_name`
 
 The `#url` method accepts a `:host` option for specifying a CDN host. You can
-use the `default_url_options` plugin to set it by default:
+use the `url_options` plugin to set it by default:
 
 ```rb
-Shrine.plugin :default_url_options, store: {host: "http://abc123.cloudfront.net"}
+Shrine.plugin :url_options, store: { host: "http://abc123.cloudfront.net" }
 ```
 
 #### `:path`
@@ -580,7 +695,14 @@ s3.upload(io, "object/destination/path")
 The Shrine storage has no replacement for the `:url` Paperclip option, and it
 isn't needed.
 
-[file]: http://linux.die.net/man/1/file
-[Reprocessing versions]: /doc/regenerating_versions.md#readme
-[direct S3 uploads]: /doc/direct_s3.md#readme
-[`Shrine::Storage::S3`]: /doc/storage/s3.md#readme
+[metadata_attributes]: https://shrinerb.com/docs/plugins/metadata_attributes
+[Managing Derivatives]: https://shrinerb.com/docs/changing-derivatives
+[direct uploads]: https://shrinerb.com/docs/getting-started#direct-uploads
+[S3]: https://shrinerb.com/docs/storage/s3
+[image_processing]: https://github.com/janko/image_processing
+[libvips]: http://libvips.github.io/libvips/
+[activerecord]: https://shrinerb.com/docs/plugins/activerecord
+[sequel]: https://shrinerb.com/docs/plugins/sequel
+[rom]: https://github.com/shrinerb/shrine-rom
+[hanami]: https://github.com/katafrakt/hanami-shrine
+[mongoid]: https://github.com/shrinerb/shrine-mongoid