shrine 0.9.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 21c82440698540e29ee787915b4bbdf9c3289f72
-  data.tar.gz: 70e3d33cd286ed3911df5d130b3f72f67c16e571
+  metadata.gz: 583eed751bfa6c1ae0ad5d9495509091563a8c02
+  data.tar.gz: 9c82a62a10a45df20f3f4d9422066beb705cfa39
 SHA512:
-  metadata.gz: 349f0b0bfd9c3f96e752a99e1e126c15adac5071130a0804407bd6990d76a831cb68ea86f8dd72888cf04891b4623cf61d0bd4ec5ce5eaf9e1401cea1c7c4c72
-  data.tar.gz: 2ba7dca90b8e1730a8fa2d303ad2750bd2d96c0d5cf52770486c912b85c63ff0c04ec4c60c48ad780a97ff5711b1da5a24d7ad9e28e381decd24b546c66ebbbd
+  metadata.gz: 68e093c6b118b379383305bfede12fd5710342c82c6b66040661be744d6995a723147f3b426b0d8afc03009c35d3b21a529232822e9232d2c25531d831fd973b
+  data.tar.gz: 41fabbd7fa515c3eb992bbbf5205fd924d502c64ec6f430d053ef135512e2476797435a5a4642fd066ea9bd8ba0b375455317a6bc54aaabcf24b557841b98de1

data/README.md

@@ -2,12 +2,15 @@
 
 Shrine is a toolkit for file uploads in Ruby applications.
 
+If you're new, you're encouraged to read the [introductory blog post] which
+explains the motivation behind Shrine.
+
 ## Resources
 
 * Documentation: [shrinerb.com](http://shrinerb.com)
 * Source: [github.com/janko-m/shrine](https://github.com/janko-m/shrine)
 * Bugs: [github.com/janko-m/shrine/issues](https://github.com/janko-m/shrine/issues)
-* Discussion: [groups.google.com/group/ruby-shrine](https://groups.google.com/forum/#!forum/ruby-shrine)
+* Help & Dicussion: [groups.google.com/group/ruby-shrine](https://groups.google.com/forum/#!forum/ruby-shrine)
 
 ## Installation
 
@@ -15,7 +18,7 @@ Shrine is a toolkit for file uploads in Ruby applications.
 gem "shrine"
 ```
 
-Shrine has been tested on MRI 2.1, MRI 2.2 and JRuby.
+Shrine has been tested on MRI 2.1, MRI 2.2, JRuby and Rubinius.
 
 ## Basics
 
@@ -31,7 +34,7 @@ uploader = Shrine.new(:file_system)
 
 uploaded_file = uploader.upload(File.open("avatar.jpg"))
 uploaded_file      #=> #<Shrine::UploadedFile>
-uploaded_file.url  #=> "uploads/9260ea09d8effd.jpg"
+uploaded_file.url  #=> "/uploads/9260ea09d8effd.jpg"
 uploaded_file.data #=>
 # {
 #   "storage"  => "file_system",
@@ -55,32 +58,39 @@ to be an actual IO, it's enough that it responds to these 5 methods:
 `#read(*args)`, `#size`, `#eof?`, `#rewind` and `#close`.
 `ActionDispatch::Http::UploadedFile` is one such object.
 
-Now that we've uploaded the file to the underlying storage, we can download it:
+The returned `Shrine::UploadedFile` represents the file that has been uploaded,
+and we can do a lot with it:
 
 ```rb
-file = uploaded_file.download
-file #=> #<Tempfile:/var/folders/k7/6zx6dx6x7ys3rv3srh0nyfj00000gn/T/20151004-74201-1t2jacf>
+uploaded_file.url      #=> "/uploads/938kjsdf932.jpg"
+uploaded_file.read     #=> "..."
+uploaded_file.exists?  #=> true
+uploaded_file.download #=> #<Tempfile:/var/folders/k7/6zx6dx6x7ys3rv3srh0nyfj00000gn/T/20151004-74201-1t2jacf>
+uploaded_file.metadata #=> {...}
 ```
 
-When we're done, we can delete the file:
+To read about the metadata that is stored with the uploaded file, see the
+[metadata](#metadata) section. Once you're done with the file, you can delete
+it.
 
 ```rb
-uploader.delete(uploaded_file)
-uploaded_file.exists? #=> false
+uploaded_file.delete
 ```
 
 ## Attachment
 
-In web applications, instead of managing files directly, we want to treat them
-as "attachments" to models and to tie them to the lifecycle of records. Shrine
-does this by generating and including "attachment" modules.
+In web applications, instead of managing files directly, we rather want to
+treat them as "attachments" to models and to tie them to the lifecycle of
+records. In Shrine we do this by generating and including "attachment" modules.
 
 Firstly we need to assign the special `:cache` and `:store` storages:
 
 ```rb
+require "shrine/storage/file_system"
+
 Shrine.storages = {
-  cache: Shrine::Storage::FileSystem.new(Dir.tmpdir),
-  store: Shrine::Storage::FileSystem.new("public", subdirectory: "uploads"),
+  cache: Shrine::Storage::FileSystem.new("public", subdirectory: "uploads/cache"),
+  store: Shrine::Storage::FileSystem.new("public", subdirectory: "uploads/store"),
 }
 ```
 
@@ -89,7 +99,7 @@ uploading:
 
 ```rb
 class ImageUploader < Shrine
-  # here goes your uploading logic
+  # logic for uploading images
 end
 ```
 
@@ -111,12 +121,7 @@ user = User.new
 user.avatar = File.open("avatar.jpg") # uploads the file to `:cache`
 user.avatar      #=> #<Shrine::UploadedFile>
 user.avatar_url  #=> "/uploads/9260ea09d8effd.jpg"
-user.avatar_data #=>
-# {
-#   "storage"  => "cache",
-#   "id"       => "9260ea09d8effd.jpg",
-#   "metadata" => {...},
-# }
+user.avatar_data #=> "{\"storage\":\"cache\",\"id\":\"9260ea09d8effd.jpg\",\"metadata\":{...}}"
 ```
 
 The attachment module has added `#avatar`, `#avatar=` and `#avatar_url`
@@ -124,11 +129,11 @@ methods to our User. This is what's happening:
 
 ```rb
 Shrine[:avatar] #=> #<Shrine::Attachment(avatar)>
-Shrine[:avatar].class #=> Module
-Shrine[:avatar].instance_methods #=> [:avatar=, :avatar, :avatar_url, ...]
+Shrine[:avatar].is_a?(Module) #=> true
+Shrine[:avatar].instance_methods #=> [:avatar=, :avatar, :avatar_url, :avatar_attacher]
 
 Shrine[:document] #=> #<Shrine::Attachment(document)>
-Shrine[:document].instance_methods #=> [:document=, :document, :document_url, ...]
+Shrine[:document].instance_methods #=> [:document=, :document, :document_url, :document_attacher]
 
 # If you prefer to be more explicit, you can use the expanded forms
 Shrine.attachment(:avatar)
@@ -147,7 +152,7 @@ Sequel and ActiveRecord ORMs. Shrine uses the "\<attachment\>\_data" column
 for storing attachments, so you'll need to add it in a migration:
 
 ```rb
-add_column :users, :avatar_data, :text
+add_column :users, :avatar_data, :text # or a "jsonb" column if you need querying
 ```
 ```rb
 Shrine.plugin :sequel
@@ -188,7 +193,7 @@ Shrine comes with a `direct_upload` plugin which provides an endpoint
 (implemented in [Roda]) that can be used for AJAX uploads.
 
 ```rb
-Shrine.plugin :direct_upload # Exposes a Roda endpoint
+Shrine.plugin :direct_upload # Provides a Roda endpoint
 ```
 ```rb
 Rails.application.routes.draw do
@@ -196,9 +201,17 @@ Rails.application.routes.draw do
   mount ImageUploader.direct_endpoint => "/attachments/images"
 end
 ```
-```sh
-$ curl -F "file=@/path/to/avatar.jpg" localhost:3000/attachments/images/cache/avatar
-# {"id":"43kewit94.jpg","storage":"cache","metadata":{...}}
+```rb
+# POST /attachments/images/cache/avatar
+{
+  "id": "43kewit94.jpg",
+  "storage": "cache",
+  "metadata": {
+    "size": 384393,
+    "filename": "nature.jpg",
+    "mime_type": "image/jpeg"
+  }
+}
 ```
 
 There are many great JavaScript libraries for AJAX file uploads, for example
@@ -212,8 +225,10 @@ $('[type="file"]').fileupload({
 });
 ```
 
-This plugin also provides a route for direct S3 uploads. See the [example app]
-for how you can do multiple uploads directly to S3.
+This is an oversimplified implementation without any UX, it's just to show you
+how easy it is. The `direct_upload` plugin also provides a route for direct S3
+uploads, see the [example app] for how you can do multiple uploads directly to
+S3.
 
 ## Processing
 
@@ -237,9 +252,9 @@ assigned and saved, an "upload" actually happens two times. First the file is
 `:store` on save.
 
 Ok, now how do we do the actual processing? Well, Shrine actually doesn't ship
-with any image processing functionality, because that is a generic problem that
-belongs in a separate gem. So, I created the [image_processing] gem which you
-can use with Shrine:
+with any file processing functionality, because that is a generic problem that
+belongs in a separate gem. If the type of files you're uploading are images, I
+created the [image_processing] gem which you can use with Shrine:
 
 ```rb
 require "image_processing/mini_magick"
@@ -249,7 +264,7 @@ class ImageUploader < Shrine
 
   def process(io, context)
     if context[:phase] == :store
-      process_to_limit!(io.download, 700, 700)
+      resize_to_limit(io.download, 700, 700)
     end
   end
 end
@@ -266,9 +281,9 @@ storing the original file.
 
 ### Versions
 
-Often you'll want to store various thumbnails alongside your original image.
-For that you just need to load the `versions` plugin, and now in `#process`
-you can return a Hash of versions:
+If you're uploading images, often you'll want to store various thumbnails
+alongside your original image. For that you just need to load the `versions`
+plugin, and now in `#process` you can return a Hash of versions:
 
 ```rb
 require "image_processing/mini_magick"
@@ -279,9 +294,9 @@ class ImageUploader < Shrine
 
   def process(io, context)
     if context[:phase] == :store
-      size_700 = process_to_limit!(io.download, 700, 700)
-      size_500 = process_to_limit!(size_700,    500, 500)
-      size_300 = process_to_limit!(size_500,    300, 300)
+      size_700 = resize_to_limit(io.download, 700, 700)
+      size_500 = resize_to_limit(size_700,    500, 500)
+      size_300 = resize_to_limit(size_500,    300, 300)
 
       {large: size_700, medium: size_500, small: size_300}
     end
@@ -299,12 +314,6 @@ Now when you access the stored attachment, a Hash of versions will be returned
 instead:
 
 ```rb
-user.avatar #=>
-# {
-#   large:  #<Shrine::UploadedFile>,
-#   medium: #<Shrine::UploadedFile>,
-#   small:  #<Shrine::UploadedFile>,
-# }
 user.avatar.class #=> Hash
 
 # With the store_dimensions plugin
@@ -355,13 +364,14 @@ Validations are registered by calling `Shrine::Attacher.validate`, and are best
 done with the `validation_helpers` plugin:
 
 ```rb
-class ImageUploader < Shrine
+class DocumentUploader < Shrine
   plugin :validation_helpers
 
   Attacher.validate do
     # Evaluated inside an instance of Shrine::Attacher.
     if record.guest?
-      validate_max_size 2*1024*1024, message: "is too large (max is 2 MB)"
+      validate_max_size 10*1024*1024, message: "is too large (max is 10 MB)"
+      validate_mime_type_inclusion ["application/pdf"]
     end
   end
 end
@@ -369,9 +379,9 @@ end
 
 ```rb
 user = User.new
-user.avatar = File.open("big_image.jpg")
+user.resume = File.open("resume.pdf")
 user.valid? #=> false
-user.errors.to_hash #=> {avatar: ["is too large (max is 2 MB)"]}
+user.errors.to_hash #=> {resume: ["is too large (max is 2 MB)"]}
 ```
 
 ## Metadata
@@ -404,11 +414,11 @@ browser sets solely based on the extension of the uploaded file. This means
 that by default Shrine's "mime_type" is *not* guaranteed to hold the actual
 MIME type of the file.
 
-To help with that Shrine provides the `extract_mime_type` plugin, which by
-deafult uses the UNIX [file] utility to determine the actual MIME type:
+To help with that Shrine provides the `determine_mime_type` plugin, which by
+default uses the UNIX [file] utility to determine the actual MIME type:
 
 ```rb
-Shrine.plugin :extract_mime_type
+Shrine.plugin :determine_mime_type
 ```
 ```rb
 user = User.create(avatar: File.open("image.mp4")) # image with a .mp4 extension
@@ -417,8 +427,8 @@ user.avatar.mime_type #=> "image/png"
 
 ### Dimensions
 
-Shrine ships with the `store_dimensions` plugin which extracts dimensions
-using the [fastimage] gem.
+If you're uploading images and you want to store dimensions, you can use the
+`store_dimensions` plugin which extracts dimensions using the [fastimage] gem.
 
 ```rb
 ImageUploader.plugin :store_dimensions
@@ -463,7 +473,7 @@ end
 ## Locations
 
 By default files will all be put in the same folder. If you want that each
-record has its own directory, you can use the `pretty_location` plugin:
+attachment has its own directory, you can use the `pretty_location` plugin:
 
 ```rb
 Shrine.plugin :pretty_location
@@ -576,14 +586,14 @@ In combination with direct upload for caching, this provides a completely
 seamless user experience. First the user ansynchronosuly caches the file and
 hopefully sees a nice progress bar. After this is finishes and user submits the
 form, promoting will be kicked off into a background job, and the record will
-be saved with the cached image. If your cache is public (e.g. in the "public"
+be saved with the cached file If your cache is public (e.g. in the "public"
 folder), the end user will immediately see their uploaded file, because the URL
 will point to the cached version.
 
 In the meanwhile, what `#promote` does is it uploads the cached file `:store`,
 and writes the stored file to the column. When the record gets saved, the URL
 will switch from filesystem to S3, but the user won't even notice that
-something happened, because they will still see the same image.
+something happened, because they will still see the same file.
 
 ### Generality
 
@@ -661,3 +671,4 @@ The gem is available as open source under the terms of the [MIT License].
 [MIT License]: http://opensource.org/licenses/MIT
 [example app]: https://github.com/janko-m/shrine-example
 [ships with over 25 plugins]: http://shrinerb.com#plugins
+[introductory blog post]: http://twin.github.io/introducing-shrine/

data/doc/carrierwave.md

@@ -0,0 +1,436 @@
+# Shrine for CarrierWave Users
+
+This guide is aimed at helping CarrierWave users transition to Shrine. We will
+first generally mention what are the key differences. Afterwards there is an
+extensive reference of CarrierWave's interface and what is the equivalent in
+Shrine.
+
+## Uploaders
+
+Shrine has a concept of uploaders similar to CarrierWave's, but instead of
+inheriting from `CarrierWave::Uploader::Base`, you inherit from `Shrine`
+directly:
+
+```rb
+class ImageUploader < Shrine
+  # ...
+end
+```
+
+While in CarrierWave you choose a storages for uploaders directly, in Shrine
+you first register storages globally (under a symbol name), and then you
+instantiate uploaders with a specific storage.
+
+```rb
+require "shrine/storage/file_system"
+
+Shrine.storages = {
+  cache: Shrine::Storage::FileSystem.new("public", subdirectory: "uploads/cache"),
+  store: Shrine::Storage::FileSystem.new("public", subdirectory: "uploads/store"),
+}
+```
+```rb
+cache_uploader = Shrine.new(:cache)
+store_uploader = Shrine.new(:store)
+```
+
+CarrierWave uses symbols for referencing storages (`:file`, `:fog`, ...), but
+in Shrine you instantiate storages directly. This makes storages much more
+flexible, because this way they can have their own options that are specific to
+them.
+
+### Processing
+
+In Shrine processing is done instance-level in the `#process` method. To
+generate versions, you simply return a hash, and also load the `versions`
+plugin to make your uploader recognize versions:
+
+```rb
+require "image_processing/mini_magick" # part of the "image_processing" gem
+
+class ImageUploader < Shrine
+  include ImageProcessing::MiniMagick
+  plugin :versions, names: [:small, :medium, :large]
+
+  def process(io, context)
+    if context[:phase] == :store
+      thumb = resize_to_limit(io.download, 300, 300)
+      {original: io, thumb: thumb}
+    end
+  end
+end
+```
+
+## Attachments
+
+Like CarrierWave, Shrine also provides integrations with ORMs, it ships with
+plugins for both Sequel and ActiveRecord (but it can also be used with simple
+PORO models).
+
+```rb
+Shrine.plugin :sequel       # If you're using Sequel
+Shrine.plugin :activerecord # If you're using ActiveRecord
+```
+
+Instead of giving you class methods for "mounting" uploaders, in Shrine you
+generate "attachment modules" which you include in your models:
+
+```rb
+class User < Sequel::Model
+  include ImageUploader[:avatar] # adds `avatar`, `avatar=` and `avatar_url` methods
+end
+```
+
+You models are required to have the `<attachment>_data` column, in the above
+case `avatar_data`. It contains the storage and location of the file, as well
+as additional metadata.
+
+### Multiple uploads
+
+Shrine doesn't have support for multiple uploads like CarrierWave does, instead
+it expects that you will implement multiple uploads yourself using a separate
+model. This is a good thing, because the implementation is specific to the ORM
+you're using, and it's analogous to how you would implement adding items to any
+dynamic one-to-many relationship. Take a look at the [example app] which
+demonstrates how easy it is to implement multiple uploads.
+
+## CarrierWave to Shrine direct mapping
+
+### `CarrierWave::Uploader::Base`
+
+#### `.storage`
+
+When using models, by default all storages use `:cache` for cache, and `:store`
+for store. If you want to change that, you can use the `default_storage`
+plugin:
+
+```rb
+Shrine.storages[:dropbox] = Shrine::Storage::Dropbox.new(*args)
+```
+
+```rb
+class ImageUploader
+  plugin :default_storage, store: :dropbox
+end
+```
+
+#### `.process`, `.version`
+
+As explained in the "Processing" section, processing is done by overriding the
+`Shrine#process` method.
+
+#### `.before`, `.after`
+
+In Shrine you can get callbacks by loading the `hooks` plugin. Unlike
+CarrierWave, and much like Sequel, Shrine implements callbacks by overriding
+instance methods:
+
+```rb
+class ImageUploader < Shrine
+  plugin :hooks
+
+  def after_upload(io, context)
+    super
+    # do something
+  end
+end
+```
+
+#### `#store!`, `#cache!`
+
+In Shrine you store and cache files by instantiating it with a corresponding
+storage, and calling `#upload`:
+
+```rb
+ImageUploader.new(:cache).upload(file)
+ImageUploader.new(:store).upload(file)
+```
+
+Note that in Shrine you cannot pass in a path to the file, you always have to
+pass an IO-like object, which is required to respond to: `#read(*args)`,
+`#size`, `#eof?`, `#rewind` and `#close`.
+
+#### `#retrieve_from_store!` and `#retrieve_from_cache!`
+
+In Shrine you simply call `#download` on the uploaded file:
+
+```rb
+uploaded_file = ImageUploader.new(:store).upload(file)
+uploaded_file.download #=> #<Tempfile>
+```
+
+#### `#url`
+
+In Shrine you call `#url` on uploaded files:
+
+```rb
+user.avatar #=> #<Shrine::UploadedFile>
+user.avatar.url #=> "/uploads/398454ujedfggf.jpg"
+```
+
+#### `#identifier`
+
+This method corresponds to `#original_filename` on the uploaded file:
+
+```rb
+user.avatar #=> #<Shrine::UploadedFile>
+user.avatar.original_filename #=> "avatar.jpg"
+```
+
+#### `#store_dir`, `#cache_dir`
+
+Shrine here provides a `#generate_location` method, which is triggered for all
+storages:
+
+```rb
+class ImageUploader < Shrine
+  def generate_location(io, context)
+    case storage_key
+    when :cache then "..."
+    when :store then "..."
+    end
+  end
+end
+```
+
+The `context` variable holds the additional data, like the attacment name and
+the record instance. You might also want to use the `pretty_location` plugin
+for automatically generating an organized folder structure.
+
+#### `#default_url`
+
+Similarly to CarrierWave, you also provide default URLs be overriding the
+method:
+
+```rb
+class ImageUploader < Shrine
+  def default_url(context)
+    # ...
+  end
+end
+```
+
+The `context` variable holds the name of the attachment, record instance and
+in some cases the `:version`.
+
+#### `#extension_white_list`, `#extension_black_list`
+
+In Shrine extension whitelisting/blacklisting is a part of validations, and is
+provided by the `validation_helpers` plugin:
+
+```rb
+class ImageUploader < Shrine
+  plugin :validation_helpers
+
+  Attacher.validate do
+    validate_extension_inclusion [/jpe?g/, 'png'] # whitelist
+    validate_extension_exclusion ['php']          # blacklist
+  end
+end
+```
+
+#### `#blacklist_mime_type_pattern`, `#whitelist_mime_type_pattern`
+
+In Shrine MIME type whitelisting/blacklisting is part of validations, and is
+provided by the `validation_helpers` plugin:
+
+```rb
+class ImageUploader < Shrine
+  plugin :validation_helpers
+
+  Attacher.validate do
+    validate_mime_type_inclusion [/image/] # whitelist
+    validate_mime_type_exclusion [/video/] # blacklist
+  end
+end
+```
+
+#### `#size_range`
+
+In Shrine file size validations are typically done using the
+`validation_helpers` plugin:
+
+
+```rb
+class ImageUploader < Shrine
+  plugin :validation_helpers
+
+  Attacher.validate do
+    validate_min_size 0
+    validate_max_size 5*1024*1024 # 5 MB
+  end
+end
+```
+
+#### `#recreate_versions!`
+
+Shrine doesn't provide an automatic mechanism for recreating versions, because
+that is very individual for different situations. For example, sometimes you want to
+regenerate all versions and sometimes just one. However, I wrote a guide
+"[Regenerating versions]" that should help you out with that.
+
+### Models
+
+The only thing that Shrine requires from your models is a `<attachment>_data`
+column (e.g. if your attachment is "avatar", you need the `avatar_data` column).
+
+#### `.mount_uploader`
+
+In Shrine you make include attachment modules directly:
+
+```rb
+Shrine.plugin :sequel
+```
+```rb
+class User < Sequel::Model
+  include ImageUploader[:avatar]
+end
+```
+
+#### `#<attachment>=`
+
+The attachment module adds an attachment setter:
+
+```rb
+user.avatar = File.open("avatar.jpg")
+```
+
+Note that unlike CarrierWave, you cannot pass in file paths, the input needs to
+be an IO-like object.
+
+#### `#<attachment>`
+
+CarrierWave returns the uploader, but Shrine returns a `Shrine::UploadedFile`,
+a representation of the file uploaded to the storage:
+
+```rb
+user.avatar #=> #<Shrine::UploadedFile>
+user.avatar.methods #=> [:url, :download, :read, :exists?, :delete, ...]
+```
+
+If attachment is missing, nil is returned.
+
+#### `#<attachment>_url`
+
+This method is simply a shorthand for "if attachment is present, call `#url`
+on it, otherwise return nil":
+
+```rb
+user.avatar_url #=> nil
+user.avatar = File.open("avatar.jpg")
+user.avatar_url #=> "/uploads/ksdf934rt.jpg"
+```
+
+The `versions` plugin extends this method to also accept a version name as the
+argument (`user.avatar_url(:thumb)`).
+
+#### `#<attachment>_cache`
+
+Shrine doesn't provide this method, instead it expects to recieve the
+attachment through the accessor, you can assign it `<attachment>_data`:
+
+```erb
+<%= form_for @user do |f| %>
+  <%= f.hidden_field :avatar, value: @user.avatar_data %>
+  <%= f.file_field :avatar %>
+<% end %>
+```
+
+You might also want to look at the `cached_attachment_data` plugin.
+
+#### `#remote_<attachment>_url`
+
+In Shrine this method is provided by the `remote_url` plugin.
+
+#### `#remove_<attachment>`
+
+In Shrine this method is provided by the `remove_attachment` plugin.
+
+### Configuration
+
+This section walks through various configuration options in CarrierWave, and
+shows what are Shrine's equivalents.
+
+#### `root`, `base_path`, `permissions`, `directory_permissions`
+
+In Shrine these are configured on the FileSystem storage directly.
+
+#### `storage`, `storage_engines`
+
+As mentioned before, in Shrine you register storages through `Shrine.storages`,
+and the attachment storages will automatically be `:cache` and `:store`, but
+you can change this with the `default_storage` plugin.
+
+#### `fog_*`
+
+These options will be set on the soon-to-be-released Fog storage for Shrine.
+
+#### `delete_tmp_file_after_storage`, `remove_previously_stored_file_after_update`
+
+By default Shrine deletes cached and replaced files, but you can choose to keep
+those files by loading the `keep_files` plugin:
+
+```rb
+Shrine.plugin :keep_files, cached: true, replaced: true
+```
+
+#### `move_to_cache`, `move_to_store`
+
+Shrine brings this functionality through the `moving` plugin.
+
+```rb
+Shrine.plugin :moving, storages: [:cache]
+```
+
+#### `validate_integrity`, `ignore_integrity_errors`
+
+Shrine does this with validation, which are best done with the
+`validation_helpers` plugin:
+
+```rb
+class ImageUploader < Shrine
+  plugin :validation_helpers
+
+  Attacher.validate do
+    # Evaluated inside an instance of Shrine::Attacher.
+    if record.guest?
+      validate_max_size 2*1024*1024, message: "is too large (max is 2 MB)"
+      validate_mime_type_inclusion ["image/jpg", "image/png", "image/gif"]
+    end
+  end
+end
+```
+
+#### `validate_download`, `ignore_download_errors`
+
+Shrine's `remote_url` plugin always rescues download errors and transforms
+them to validation errors.
+
+#### `validate_processing`, `ignore_processing_errors`
+
+Shrine doesn't offer any built-in ways of rescuing processing errors, because
+it completely depends on how you do your processing. You can easily add your
+own rescuing:
+
+```rb
+class ImageUploader < Shrine
+  def process(io, context)
+    # processing
+  rescue SomeProcessingError
+    # handling
+  end
+end
+```
+
+#### `enable_processing`
+
+You can just do conditionals inside if `Shrine#process`.
+
+#### `ensure_multipart_form`
+
+No equivalent, it depends on your application whether you need the form to be
+multipart or not.
+
+[image_processing]: https://github.com/janko-m/image_processing
+[example app]: https://github.com/janko-m/shrine-example
+[Regenerating versions]: http://shrinerb.com/rdoc/files/doc/regenerating_versions_md.html