shrine 3.0.0.rc → 3.0.0

data/doc/plugins/validation_helpers.md

@@ -1,4 +1,6 @@
-# Validation Helpers
+---
+title: Validation Helpers
+---
 
 The [`validation_helpers`][validation_helpers] plugin provides helper methods
 for validating attached files based on extracted metadata.
@@ -7,8 +9,9 @@ for validating attached files based on extracted metadata.
 plugin :validation_helpers
 
 Attacher.validate do
-  validate_mime_type_inclusion %w[image/jpeg image/png image/gif]
-  validate_max_size 5*1024*1024 if record.guest?
+  validate_mime_type %w[image/jpeg image/png image/webp]
+  validate_max_size 5*1024*1024
+  # ...
 end
 ```
 
@@ -38,8 +41,8 @@ accept a list of MIME types, and validate that the `mime_type` metadata value
 is/is not a member of that list.
 
 ```rb
-validate_mime_type_inclusion %w[image/jpeg image/png image/gif] # file must be a JPEG, PNG or a GIF image
-validate_mime_type_exclusion %w[application/x-php]              # file must not be a PHP script
+validate_mime_type_inclusion %w[image/jpeg image/png image/webp] # file must be a JPEG, PNG or a WEBP image
+validate_mime_type_exclusion %w[application/x-php]               # file must not be a PHP script
 ```
 
 Instead of `#validate_mime_type_inclusion` you can also use just
@@ -52,8 +55,8 @@ accept a list of file extensions, and validate that the `filename` metadata
 value extension is/is not a member of that list.
 
 ```rb
-validate_extension_inclusion %w[jpg jpeg png gif] # file must have .jpg, .jpeg, .png, or .gif extension
-validate_extension_exclusion %w[php]              # file must not have a .php extension
+validate_extension_inclusion %w[jpg jpeg png webp] # file must have .jpg, .jpeg, .png, or .webp extension
+validate_extension_exclusion %w[php]               # file must not have a .php extension
 ```
 
 Instead of `#validate_extension_inclusion` you can also use just
@@ -132,7 +135,7 @@ easily do conditional validation:
 
 ```rb
 Attacher.validate do
-  if validate_mime_type_inclusion %w[image/jpeg image/png image/gif]
+  if validate_mime_type_inclusion %w[image/jpeg image/png image/webp]
     validate_max_width 2000
     validate_max_height 2000
   end
@@ -166,8 +169,8 @@ If you would like to change the error message inline, you can pass the
 
 ```rb
 Attacher.validate do
-  validate_mime_type %w[image/jpeg image/png image/gif], message: "must be JPEG, PNG or GIF"
+  validate_mime_type %w[image/jpeg image/png image/webp], message: "must be JPEG, PNG or WEBP"
 end
 ```
 
-[validation_helpers]: /lib/shrine/plugins/validation_helpers.rb
+[validation_helpers]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/validation_helpers.rb

data/doc/plugins/versions.md

@@ -1,4 +1,6 @@
-# Versions
+---
+title: Versions
+---
 
 The [`versions`][versions] plugin enables your uploader to deal with versions,
 by allowing you to return a Hash of files when processing.
@@ -170,11 +172,5 @@ Attacher.default_url do |options|
 end
 ```
 
-## Re-create Versions
-
-If you want to re-create a single or all versions, refer to the [reprocessing
-versions] guide for details.
-
-[versions]: /lib/shrine/plugins/versions.rb
-[reprocessing versions]: /doc/regenerating_versions.md#readme
+[versions]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/versions.rb
 [image_processing]: https://github.com/janko/image_processing

data/doc/processing.md

@@ -1,4 +1,6 @@
-# File Processing
+---
+title: File Processing
+---
 
 Shrine allows you to process attached files up front or on-the-fly. For
 example, if your app is accepting image uploads, you can generate a predefined
@@ -53,14 +55,14 @@ class ImageUploader < Shrine
 end
 ```
 ```rb
-photo = Photo.new
+photo = Photo.new(image: file)
 photo.image_derivatives! # calls derivatives processor
 photo.save
 ```
 
 After the processed files are uploaded, their data is saved into the
 `<attachment>_data` column. You can then retrieve the derivatives as
-[`Shrine::UploadedFile`][uploaded file] objects:
+[`Shrine::UploadedFile`] objects:
 
 ```rb
 photo.image(:large)            #=> #<Shrine::UploadedFile ...>
@@ -69,6 +71,21 @@ photo.image(:large).size       #=> 5825949
 photo.image(:large).mime_type  #=> "image/jpeg"
 ```
 
+### Automatic processing
+
+If you would like derivatives to be automatically created with promotion, you
+can override `Attacher#promote` for call `Attacher#create_derivatives` before
+promotion:
+
+```rb
+class Shrine::Attacher
+  def promote(*)
+    create_derivatives
+    super
+  end
+end
+```
+
 ### Backgrounding
 
 Since file processing can be time consuming, it's recommended to move it into a
@@ -341,7 +358,7 @@ to be confused with the [image_optim] gem):
 
 ```rb
 # Gemfile
-gem "down", "~> 4.4"
+gem "down", "~> 5.0"
 gem "http", "~> 4.0"
 ```
 
@@ -406,13 +423,14 @@ photo.image_url(width: 100, height: 100, crop: :fit)
 [Why is libvips quick]: https://github.com/libvips/libvips/wiki/Why-is-libvips-quick
 [ImageOptim.com]: https://imageoptim.com/api
 [streamio-ffmpeg]: https://github.com/streamio/streamio-ffmpeg
-[Managing Derivatives]: /doc/changing_derivatives.md#readme
+[Managing Derivatives]: https://shrinerb.com/docs/changing-derivatives
 [Cloudinary]: https://cloudinary.com
 [shrine-cloudinary]: https://github.com/shrinerb/shrine-cloudinary
-[backgrounding]: /doc/plugins/backgrounding.md#readme
+[backgrounding]: https://shrinerb.com/docs/plugins/backgrounding
 [ruby-vips]: https://github.com/libvips/ruby-vips
 [MiniMagick]: https://github.com/minimagick/minimagick
-[derivation_endpoint]: /doc/plugins/derivation_endpoint.md#readme
-[derivation_endpoint performance]: /doc/plugins/derivation_endpoint.md#performance
-[derivatives]: /doc/plugins/derivatives.md#readme
+[derivation_endpoint]: https://shrinerb.com/docs/plugins/derivation_endpoint
+[derivation_endpoint performance]: https://shrinerb.com/docs/plugins/derivation_endpoint#performance
+[derivatives]: https://shrinerb.com/docs/plugins/derivatives
 [concurrent-ruby]: https://github.com/ruby-concurrency/concurrent-ruby
+[image_optim]: https://github.com/toy/image_optim

data/doc/refile.md

@@ -1,4 +1,6 @@
-# Shrine for Refile Users
+---
+title: Shrine for Refile Users
+---
 
 This guide is aimed at helping Refile users transition to Shrine, and it consists
 of three parts:
@@ -7,11 +9,14 @@ of three parts:
 2. Instructions how to migrate and 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,7 +30,7 @@ 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:
@@ -45,38 +50,7 @@ class VideoUploader < Shrine
 end
 ```
 
-### Processing
-
-Shrine provides on-the-fly processing via the
-[`derivation_endpoint`][derivation_endpoint] plugin:
-
-```rb
-# config/routes.rb (Rails)
-Rails.application.routes.draw do
-  # ...
-  mount ImageUploader.derivation_endpoint => "/derivations/image"
-end
-```
-```rb
-require "image_processing/mini_magick"
-
-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
-```
-
-Shrine also support processing up front using the [`derivatives`][derivatives]
-plugin.
-
-### URL
+#### URL
 
 While Refile serves all files through the Rack endpoint mounted in your app,
 Shrine serves files directly from storage services:
@@ -93,100 +67,111 @@ 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`][download_endpoint] plugin.
 
-## Attachments
+### Persistence
+
+Refile persists the uploaded file location and metadata into individual
+columns:
+
+* `<attachment>_id`
+* `<attachment>_filename`
+* `<attachment>_content_type`
+* `<attachment>_size`
 
-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:
+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
-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(: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.
-
-### Metadata
+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.
 
-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"
-#   }
-# }
+# config/routes.rb (Rails)
+Rails.application.routes.draw do
+  # ...
+  mount ImageUploader.derivation_endpoint => "/derivations/image"
+end
+```
+```rb
+require "image_processing/mini_magick"
+
+class ImageUploader < Shrine
+  plugin :derivation_endpoint,
+    secret_key: "<YOUR SECRET KEY>",
+    prefix:     "derivations/image" # needs to match the mount point in routes
 
-photo.image.original_filename #=> "nature.png"
-photo.image.size              #=> 49349138
-photo.image.mime_type         #=> "image/png"
+  derivation :thumbnail do |file, width, height|
+    ImageProcessing::MiniMagick
+      .source(file)
+      .resize_to_limit!(width.to_i, height.to_i)
+  end
+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 processing up front 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 %w[jpg jpeg png gif]
-    validate_mime_type %w[image/jpeg image/png image/gif]
     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
@@ -200,10 +185,16 @@ 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
 
@@ -260,7 +251,7 @@ 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
 ```
@@ -298,8 +289,7 @@ Shrine.storages = {
 
 #### `.app`, `.mount_point`, `.automount`
 
-The `upload_endpoint`, `presign_endpoint`, and `derivation_endpoint` plugins
-provide methods for generating Rack apps, but you need to mount them
+The Rack apps provided by the `*_endpoint` Shrine plugins are mounted
 explicitly:
 
 ```rb
@@ -312,8 +302,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`
 
@@ -335,7 +325,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
@@ -347,35 +337,38 @@ 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:
@@ -423,7 +416,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
 
@@ -483,11 +476,10 @@ form_for @user do |form|
 end
 ```
 
-[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]: /doc/plugins/derivation_endpoint.md#readme
-[download_endpoint]: /doc/plugins/download_endpoint.md#readme
-[derivatives]: /doc/plugins/derivatives.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