shrine 2.19.3 → 3.6.0

data/doc/refile.md

@@ -1,17 +1,22 @@
-# Shrine for Refile Users
+---
+title: Upgrading from Refile
+---
 
 This guide is aimed at helping Refile users transition to Shrine, and it consists
 of three parts:
 
 1. Explanation of the key differences in design between Refile and Shrine
-2. Instructions how to migrate and existing app that uses Refile to Shrine
+2. Instructions how to migrate an existing app that uses Refile to Shrine
 3. Extensive reference of Refile's interface with Shrine equivalents
 
-## Uploaders
+## Overview
 
 Shrine borrows many great concepts from Refile: Refile's "backends" are here
-named "storages", it uses the same IO abstraction for uploading and representing
-uploaded files, similar attachment logic, and direct uploads are also supported.
+named "storages", it uses the same IO abstraction for uploading and
+representing uploaded files, similar attachment logic, and direct uploads are
+supported as well.
+
+### Uploader
 
 While in Refile you work with storages directly, Shrine uses *uploaders* which
 wrap storage uploads:
@@ -25,66 +30,27 @@ uploaded_file #=> #<Shrine::UploadedFile ...>
 uploaded_file.storage #=> #<Shrine::Storage::S3>
 ```
 
-This way Shrine can perform tasks like generating location, extracting
+This way, Shrine can perform tasks like generating location, extracting
 metadata, processing, and logging, which are all storage-agnostic, and leave
 storages to deal only with actual file storage. And these tasks can be
 configured differently depending on the types of files you're uploading:
 
 ```rb
 class ImageUploader < Shrine
-  add_metadata :exif do |io, context|
+  add_metadata :exif do |io|
     MiniMagick::Image.new(io).exif
   end
 end
 ```
 ```rb
 class VideoUploader < Shrine
-  add_metadata :duration do |io, context|
+  add_metadata :duration do |io|
     FFMPEG::Movie.new(io.path).duration
   end
 end
 ```
 
-### Processing
-
-Refile implements on-the-fly processing, serving all files through the Rack
-endpoint. However, it doesn't offer any abilities for processing on upload.
-Shrine, on the other hand, generates URLs to specific storages and offers
-processing on upload (like CarrierWave and Paperclip), but doesn't support
-on-the-fly processing.
-
-The reason for this decision is that an image server is a completely separate
-responsibility, and it's better to use any of the generic services for
-on-the-fly processing. Shrine already has integrations for many such services:
-[shrine-cloudinary], [shrine-imgix], and [shrine-uploadcare]. There is even
-an open-source solution, [Attache], which you can also use with Shrine.
-
-This is how you would process multiple versions in Shrine:
-
-```rb
-require "image_processing/mini_magick"
-
-class ImageUploader < Shrine
-  plugin :processing
-  plugin :versions
-
-  process(:store) do |io, context|
-    versions = { original: io } # retain original
-
-    io.download do |original|
-      pipeline = 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
-  end
-end
-```
-
-### URL
+#### URL
 
 While Refile serves all files through the Rack endpoint mounted in your app,
 Shrine serves files directly from storage services:
@@ -99,103 +65,113 @@ Refile.attachment_url(@photo, :image) #=> "/attachments/cache/50dfl833lfs0gfh.jp
 
 If you're using storage which don't expose files over URL (e.g. a database
 storage), or you want to secure your downloads, you can also serve files
-through your app using the download_endpoint plugin.
+through your app using the [`download_endpoint`][download_endpoint] plugin.
 
-## Attachments
+### Persistence
 
-While in Refile you configure attachments by passing options to `.attachment`,
-in Shrine you define all your uploading logic inside uploaders, and then
-generate an attachment module with that uploader which is included into the
-model:
+Refile persists the uploaded file location and metadata into individual
+columns:
+
+* `<attachment>_id`
+* `<attachment>_filename`
+* `<attachment>_content_type`
+* `<attachment>_size`
+
+Shrine, on the other hand, saves all uploaded file data into a single
+`<attachment>_data` column:
 
 ```rb
-class Photo < Sequel::Model
-  extend Shrine::Sequel::Attachment
-  attachment :image, destroy: false
-end
+{
+  "id": "path/to/image.jpg",
+  "storage": "store",
+  "metadata": {
+    "filename": "nature.jpg",
+    "size": 4739472,
+    "mime_type": "image/jpeg"
+  }
+}
 ```
-
 ```rb
-class ImageUploader < Shrine
-  plugin :sequel
-  plugin :keep_files, destroyed: true
-end
+photo.image.id          #=> "path/to/image.jpg"
+photo.image.storage_key #=> :store
+photo.image.metadata    #=> { "filename" => "...", "size" => ..., "mime_type" => "..." }
 
-class Photo < Sequel::Model
-  include ImageUploader::Attachment.new(:image)
-end
+photo.image.original_filename #=> "nature.jpg"
+photo.image.size              #=> 4739472
+photo.image.mime_type         #=> "image/jpeg"
 ```
 
-This way we can encapsulate all attachment logic inside a class and share it
-between different models.
+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.
 
-### Metadata
-
-Refile allows you to save additional metadata about uploaded files in additional
-columns, so you can define `<attachment>_filename`, `<attachment>_content_type`,
-or `<attachment>_size`.
+### Processing
 
-Shrine, on the other hand, saves all metadata into a single `<attachment>_data`
-column:
+Shrine provides on-the-fly processing via the
+[`derivation_endpoint`][derivation_endpoint] plugin:
 
 ```rb
-photo.image_data #=>
-# {
-#   "storage" => "store",
-#   "id" => "photo/1/image/0d9o8dk42.png",
-#   "metadata" => {
-#     "filename"  => "nature.png",
-#     "size"      => 49349138,
-#     "mime_type" => "image/png"
-#   }
-# }
+require "image_processing/mini_magick"
 
-photo.image.original_filename #=> "nature.png"
-photo.image.size              #=> 49349138
-photo.image.mime_type         #=> "image/png"
+class ImageUploader < Shrine
+  plugin :derivation_endpoint,
+    secret_key: "<YOUR SECRET KEY>",
+    prefix:     "derivations/image" # needs to match the mount point in routes
+
+  derivation :thumbnail do |file, width, height|
+    ImageProcessing::MiniMagick
+      .source(file)
+      .resize_to_limit!(width.to_i, height.to_i)
+  end
+end
+```
+```rb
+# config/routes.rb (Rails)
+Rails.application.routes.draw do
+  # ...
+  mount ImageUploader.derivation_endpoint => "/derivations/image"
+end
 ```
 
-By default "filename", "size" and "mime_type" is stored, but you can also store
-image dimensions, or define any other custom metadata. This also allow storages
-to add their own metadata.
+Shrine also support eager processing using the [`derivatives`][derivatives]
+plugin.
 
-### Validations
+### Validation
 
-In Refile you define validations by passing options to `.attachment`, while
-in Shrine you define validations on the instance-level, which allows them to
-be dynamic:
+In Refile, file validation is defined statically on attachment definition:
 
 ```rb
 class Photo < Sequel::Model
   attachment :image,
-    extension: %w[jpg jpeg png gif],
-    content_type: %w[image/jpeg image/png image/gif]
+    extension: %w[jpg jpeg png webp],
+    content_type: %w[image/jpeg image/png image/webp]
 end
 ```
 
+In Shrine, validation is performed on the instance-level, which allows you to
+make the validation conditional:
+
 ```rb
 class ImageUploader < Shrine
   plugin :validation_helpers
 
   Attacher.validate do
-    validate_extension_inclusion %w[jpg jpeg png gif]
-    validate_mime_type_inclusion %w[image/jpeg image/png image/gif]
-    validate_max_size 10*1024*1024 unless record.admin?
+    validate_max_size 10*1024*1024
+    validate_extension %w[jpg jpeg png webp]
+
+    if validate_mime_type %w[image/jpeg image/png image/webp]
+      validate_max_dimensions [5000, 5000]
+    end
   end
 end
 ```
 
 Refile extracts the MIME type from the file extension, which means it can
 easily be spoofed (just give a PHP file a `.jpg` extension). Shrine has the
-determine_mime_type plugin for determining MIME type from file *content*.
-
-### Multiple uploads
-
-Shrine doesn't have a built-in solution for accepting multiple uploads, but
-it's actually very easy to do manually, see the [demo app] on how you can do
-multiple uploads directly to S3.
+[`determine_mime_type`][determine_mime_type] plugin for determining MIME type
+from file *content*.
 
-## Direct uploads
+### Direct uploads
 
 Shrine borrows Refile's idea of direct uploads, and ships with
 `upload_endpoint` and `presign_endpoint` plugins which provide endpoints for
@@ -209,44 +185,68 @@ Shrine.plugin :upload_endpoint
 Shrine.presign_endpoint(:cache) # Rack app that generates presigns for specified storage
 ```
 
-Unlike Refile, Shrine doesn't ship with complete JavaScript which you can just
-include to make it work. However, [Uppy] is an excellent JavaScript file upload
-library that integrates wonderfully with Shrine, see the [demo app] for a
-complete example.
+While Refile ships with a plug-and-play JavaScript for direct uploads, Shrine
+instead adopts [Uppy], a modern and modular JavaScript file upload library that
+happens to integrate well with Shrine.
+
+### Multiple uploads
+
+Shrine doesn't have support for multiple uploads out-of-the-box like Refile
+does. Instead, you can implement them using a separate table with a one-to-many
+relationship to which the files will be attached. The [Multiple Files] guide
+explains this setup in more detail.
 
 ## Migrating from Refile
 
 You have an existing app using Refile and you want to transfer it to
-Shrine. Let's assume we have a `Photo` model with the "image" attachment. First
-we need to create the `image_data` column for Shrine:
+Shrine. Let's assume we have a `Photo` model with the "image" attachment.
+
+### 1. Add Shrine column
+
+First we need to create the `image_data` column for Shrine:
 
 ```rb
 add_column :photos, :image_data, :text
 ```
 
+### 2. Dual write
+
 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 Refile
 attachments:
 
 ```rb
+require "shrine"
+
+Shrine.storages = {
+  cache: ...,
+  store: ...,
+}
+
+Shrine.plugin :model
+
 module RefileShrineSynchronization
   def write_shrine_data(name)
-    if read_attribute("#{name}_id").present?
-      data = {
-        storage: :store,
-        id: send("#{name}_id"),
-        metadata: {
-          size: (send("#{name}_size") if respond_to?("#{name}_size")),
-          filename: (send("#{name}_filename") if respond_to?("#{name}_filename")),
-          mime_type: (send("#{name}_content_type") if respond_to?("#{name}_content_type")),
-        }
-      }
+    attacher = Shrine::Attacher.from_model(self, name)
 
-      write_attribute(:"#{name}_data", data.to_json)
+    if read_attribute("#{name}_id").present?
+      attacher.set shrine_file(name)
     else
-      write_attribute(:"#{name}_data", nil)
+      attacher.set nil
     end
   end
+
+  def shrine_file(name)
+    Shrine.uploaded_file(
+      storage:  :store,
+      id:       send("#{name}_id"),
+      metadata: {
+        "size"      => (send("#{name}_size") if respond_to?("#{name}_size")),
+        "filename"  => (send("#{name}_filename") if respond_to?("#{name}_filename")),
+        "mime_type" => (send("#{name}_content_type") if respond_to?("#{name}_content_type")),
+      }
+    )
+  end
 end
 ```
 ```rb
@@ -255,14 +255,18 @@ class Photo < ActiveRecord::Base
   include RefileShrineSynchronization
 
   before_save do
-    write_shrine_data(:image) if changes.key?(:image_id)
+    write_shrine_data(:image) if image_id_changed?
   end
 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 Refile attachments to `image_data`:
+synchronized with new attachments.
+
+### 3. Data migration
+
+Next step is to run a script which writes all existing Refile attachments to
+`image_data`:
 
 ```rb
 Photo.find_each do |photo|
@@ -271,9 +275,22 @@ Photo.find_each do |photo|
 end
 ```
 
+### 4. Rewrite code
+
 Now you should be able to rewrite your application so that it uses Shrine
-instead of Refile, using equivalent Shrine storages. For help with translating
-the code from Refile to Shrine, you can consult the reference below.
+instead of Refile (you can consult the reference in the next section). You can
+remove the `RefileShrineSynchronization` module as well.
+
+### 5. Remove Refile columns
+
+If everything is looking good, we can remove Refile columns:
+
+```rb
+remove_column :photos, :image_id
+remove_column :photos, :image_size
+remove_column :photos, :image_filename
+remove_column :photos, :image_content_type
+```
 
 ## Refile to Shrine direct mapping
 
@@ -293,8 +310,8 @@ Shrine.storages = {
 
 #### `.app`, `.mount_point`, `.automount`
 
-The `upload_endpoint` and `presign_endpoint` plugins provide methods for
-generating Rack apps, but you need to mount them explicitly:
+The Rack apps provided by the `*_endpoint` Shrine plugins are mounted
+explicitly:
 
 ```rb
 # config/routes.rb
@@ -306,8 +323,8 @@ end
 
 #### `.allow_uploads_to`
 
-The `Shrine.upload_endpoint` and `Shrine.presign_endpoint` require you to
-specify the storage that will be used.
+The `Shrine.upload_endpoint` and `Shrine.presign_endpoint` builders require you
+to specify the storage that will be used.
 
 #### `.logger`
 
@@ -318,10 +335,10 @@ Shrine.logger
 #### `.processors`, `.processor`
 
 ```rb
-class MyUploader < Shrine
-  plugin :processing
+class ImageUploader < Shrine
+  plugin :derivatives
 
-  process(:store) do |io, context|
+  derivation :thumbnail do |file, width, height|
     # ...
   end
 end
@@ -329,7 +346,7 @@ end
 
 #### `.types`
 
-In Shrine validations are done by calling `.validate` on the attacher class:
+Shrine defines validations on the uploader class level:
 
 ```rb
 class MyUploader < Shrine
@@ -341,42 +358,45 @@ class MyUploader < Shrine
 end
 ```
 
-#### `.extract_filename`, `.extract_content_type`
+#### `.extract_filename`
 
-In Shrine equivalents are (private) methods `Shrine#extract_filename` and
-`Shrine#extract_mime_type`.
+Shrine's equivalent is a `Shrine#extract_filename` private method. You can
+instead use the `Shrine#extract_metadata` public method.
 
-#### `.app_url`
+#### `.extract_content_type`
 
-You should use your framework to generate the URL to your mounted direct
-endpoint.
+The [`determine_mime_type`][determine_mime_type] plugin provides a
+`Shrine.determine_mime_type` method.
 
-#### `.attachment_url`, `.file_url`
+#### `.app_url`, `.upload_url`, `.attachment_upload_url`, `.presign_url`, `.attachment_presign_url`
 
-You can call `#url` on the uploaded file, or `#<name>_url` on the model.
-Additionally you can use the `download_endpoint` plugin.
+Shrine requires you to use your framework to generate URLs to mounted
+endpoints.
 
-#### `.upload_url`, `.attachment_upload_url`, `.presign_url`, `.attachment_presign_url`
+#### `.attachment_url`, `.file_url`
 
-These should be generated directly by you, it depends on where you've mounted
-the direct endpoint.
+You can call `#url` on the uploaded file, or `#<name>_url` on the model.
+Alternatively, you can use `#download_url` provided by the `download_endpoint`
+plugin.
 
 #### `.host`, `.cdn_host`, `.app_host`, `.allow_downloads_from`, `allow_origin`, `.content_max_age`
 
-Not needed since Shrine doesn't offer on-the-fly processing.
+These can be configured on individual `*_endpoint` plugins.
 
 #### `.secret_key`, `.token`, `.valid_token?`
 
-Not needed since Shrine doesn't offer on-the-fly processing.
+The secret key is required for the
+[`derivation_endpoint`][derivation_endpoint], but these methods are not
+exposed.
 
-### `attachment`
+### `Attachment`
 
 Shrine's equivalent to calling the attachment is including an attachment module
 of an uploader:
 
 ```rb
-class User
-  include ImageUploader::Attachment.new(:avatar)
+class Photo
+  include ImageUploader::Attachment(:image)
 end
 ```
 
@@ -390,8 +410,8 @@ class ImageUploader < Shrine
   plugin :validation_helpers
 
   Attacher.validate do
-    validate_extension_inclusion %w[jpg jpeg png]
-    validate_mime_type_inclusion %w[image/jpeg image/png]
+    validate_extension %w[jpg jpeg png]
+    validate_mime_type %w[image/jpeg image/png]
   end
 end
 ```
@@ -417,7 +437,7 @@ No equivalent currently exists in Shrine.
 
 ### `accepts_attachments_for`
 
-No equivalent in Shrine, but take a look at the "[Multiple Files]" guide.
+No equivalent in Shrine, but take a look at the [Multiple Files] guide.
 
 ### Form helpers
 
@@ -438,7 +458,7 @@ Shrine.plugin :cached_attachment_data
 ```
 ```rb
 form_for @user do |form|
-  form.hidden_field :profile_image, value: @user.cached_profile_image_data
+  form.hidden_field :profile_image, value: @user.cached_profile_image_data, id: nil
   form.file_field :profile_image
 end
 ```
@@ -455,7 +475,7 @@ Shrine.plugin :remove_attachment
 ```
 ```rb
 form_for @user do |form|
-  form.hidden_field :profile_image, value: @user.cached_profile_image_data
+  form.hidden_field :profile_image, value: @user.cached_profile_image_data, id: nil
   form.file_field :profile_image
   form.check_box :remove_profile_image
 end
@@ -471,18 +491,16 @@ Shrine.plugin :remote_url
 ```
 ```rb
 form_for @user do |form|
-  form.hidden_field :profile_image, value: @user.cached_profile_image_data
+  form.hidden_field :profile_image, value: @user.cached_profile_image_data, id: nil
   form.file_field :profile_image
   form.text_field :profile_image_remote_url
 end
 ```
 
-[shrine-cloudinary]: https://github.com/shrinerb/shrine-cloudinary
-[shrine-imgix]: https://github.com/shrinerb/shrine-imgix
-[shrine-uploadcare]: https://github.com/shrinerb/shrine-uploadcare
-[Attache]: https://github.com/choonkeat/attache
-[image_processing]: https://github.com/janko/image_processing
 [Uppy]: https://uppy.io
-[Direct Uploads to S3]: /doc/direct_s3.md#readme
-[demo app]: https://github.com/shrinerb/shrine/tree/master/demo
-[Multiple Files]: /doc/multiple_files.md#readme
+[derivation_endpoint]: https://shrinerb.com/docs/plugins/derivation_endpoint
+[download_endpoint]: https://shrinerb.com/docs/plugins/download_endpoint
+[derivatives]: https://shrinerb.com/docs/plugins/derivatives
+[metadata_attributes]: https://shrinerb.com/docs/plugins/metadata_attributes
+[determine_mime_type]: https://shrinerb.com/docs/plugins/determine_mime_type
+[Multiple Files]: https://shrinerb.com/docs/multiple-files

data/doc/release_notes/1.0.0.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 1.0.0
+---
+
 # Backwards compatibility
 
 * The `delete_invalid` plugin was removed, because it was unstable since next

data/doc/release_notes/1.1.0.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 1.1.0
+---
+
 # New plugins
 
 * The `download_endpoint` plugin has been added, which allows downloading files
@@ -39,11 +43,11 @@ plugin :keep_location, :cache => :store
 ```rb
 user = User.new
 user.avatar = image
-user.avatar.storage_key #=> "cache"
+user.avatar.storage_key #=> :cache
 user.avatar.id #=> "abc123.jpg"
 
 user.save
-user.avatar.storage_key #=> "store"
+user.avatar.storage_key #=> :store
 user.avatar.id #=> "abc123.jpg"
 ```
 

data/doc/release_notes/1.2.0.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 1.2.0
+---
+
 New features
 ============
 

data/doc/release_notes/1.3.0.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 1.3.0
+---
+
 New features
 ============
 

data/doc/release_notes/1.4.0.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 1.4.0
+---
+
 New features
 ============
 

data/doc/release_notes/1.4.1.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 1.4.1
+---
+
 Regressions
 ===========
 

data/doc/release_notes/1.4.2.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 1.4.2
+---
+
 Regressions
 ===========
 

data/doc/release_notes/2.0.0.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 2.0.0
+---
+
 Backwards compatibility
 =======================
 

data/doc/release_notes/2.0.1.md

@@ -1,3 +1,7 @@
+---
+title: Shrine 2.0.1
+---
+
 Regressions
 ===========