shrine 2.19.4 → 3.4.0

data/doc/validation.md

@@ -1,20 +1,25 @@
-# File Validation
+---
+title: File Validation
+---
 
-Shrine allows validating assigned files based on their metadata. Validation
-code is defined inside a `Shrine::Attacher.validate` block:
+Shrine allows validating assigned files using the [`validation`][validation]
+plugin. Validation code is defined inside an `Attacher.validate` block:
 
+```rb
+Shrine.plugin :validation
+```
 ```rb
 class ImageUploader < Shrine
   Attacher.validate do
-    # validations
+    # ... perform validation ...
   end
 end
 ```
 
-The validation block is run when a file is assigned to an attachment attribute,
-afterwards the validation errors are stored in `Shrine::Attacher#errors`. ORM
-plugins like `sequel` and `activerecord` will automatically merge these
-validation errors into the `#errors` hash on the model instance.
+The validation block is run when a new file is assigned, and any validation
+errors are stored in `Shrine::Attacher#errors`. Persistence plugins like
+`sequel` and `activerecord` will automatically merge these validation errors
+into the `#errors` hash on the model instance.
 
 ```rb
 photo = Photo.new
@@ -23,57 +28,20 @@ photo.valid? #=> false
 photo.errors[:image] #=> [...]
 ```
 
-By default the invalid file will remain assigned to the attachment attribute,
-but you can have it automatically removed and deleted by loading the
-`remove_invalid` plugin.
-
-```rb
-Shrine.plugin :remove_invalid # remove and delete files that failed validation
-```
-
-The validation block is evaluated in the context of a `Shrine::Attacher`
-instance, so you have access to the original file and the record:
-
-```rb
-class ImageUploader < Shrine
-  Attacher.validate do
-    self   #=> #<Shrine::Attacher>
-
-    get    #=> #<Shrine::UploadedFile>
-    record #=> #<Photo>
-    name   #=> :image
-  end
-end
-```
+## Validation helpers
 
-You can use the attacher context to pass additional parameters you want to use
-for validation:
+The [`validation_helpers`][validation_helpers] plugin provides convenient
+validators for built-in metadata:
 
 ```rb
-photo.image_attacher.context[:foo] = "bar"
+Shrine.plugin :validation_helpers
 ```
 ```rb
 class ImageUploader < Shrine
   Attacher.validate do
-    context[:foo] #=> "bar"
-  end
-end
-```
-
-## Validation helpers
-
-The `validation_helpers` plugin provides helper methods for validating common
-metadata values:
-
-```rb
-class ImageUploader < Shrine
-  plugin :validation_helpers
-
-  Attacher.validate do
-    validate_min_size 1, message: "must not be empty"
-    validate_max_size 5*1024*1024, message: "is too large (max is 5 MB)"
-    validate_mime_type_inclusion %w[image/jpeg image/png image/tiff]
-    validate_extension_inclusion %w[jpg jpeg png tiff tif]
+    validate_size      1..5*1024*1024
+    validate_mime_type %w[image/jpeg image/png image/webp image/tiff]
+    validate_extension %w[jpg jpeg png webp tiff tif]
   end
 end
 ```
@@ -81,47 +49,31 @@ end
 Note that for secure MIME type validation it's recommended to also load
 `determine_mime_type` and `restore_cached_data` plugins.
 
-It's also easy to do conditional validations with these helper methods:
-
-```rb
-class ImageUploader < Shrine
-  plugin :validation_helpers
-
-  Attacher.validate do
-    # validate dimensions only of the attached file is an image
-    if validate_extension_inclusion %w[jpg jpeg png tiff tif]
-      validate_max_width 5000
-      validate_max_height 5000
-    end
-  end
-end
-```
-
-See the `validation_helpers` plugin documentation for more details.
+See the [`validation_helpers`][validation_helpers] plugin documentation for
+more details.
 
 ## Custom validations
 
-You might sometimes want to validate custom metadata, or in general do custom
-validation that the `validation_helpers` plugin does not provide. The
-`Shrine::Attacher.validate` block is evaluated at instance level, so you're
-free to write there any code you like and add validation errors onto the
-`Shrine::Attacher#errors` array.
-
-For example, if you're uploading images, you might want to validate that the
-image is processable using the [ImageProcessing] gem:
+You can also do your own custom validations:
 
 ```rb
-require "image_processing/mini_magick"
+# Gemfile
+gem "streamio-ffmpeg"
+```
+```rb
+require "streamio-ffmpeg"
 
-class ImageUploader < Shrine
-  plugin :validation_helpers
+class VideoUploader < Shrine
+  plugin :add_metadata
+
+  add_metadata :duration do |io|
+    movie = Shrine.with_file(io) { |file| FFMPEG::Movie.new(file.path) }
+    movie.duration
+  end
 
   Attacher.validate do
-    # validate dimensions only of the attached file is an image
-    if validate_mime_type_inclusion %w[image/jpeg image/png image/tiff]
-      get.download do |tempfile|
-        errors << "is corrupted or invalid" unless ImageProcessing::MiniMagick.valid_image?(tempfile)
-      end
+    if file.duration > 5*60*60
+      errors << "duration must not be longer than 5 hours"
     end
   end
 end
@@ -134,15 +86,27 @@ when defining more validations:
 
 ```rb
 class ApplicationUploader < Shrine
-  Attacher.validate { validate_max_size 5.megabytes }
+  Attacher.validate { validate_max_size 5*1024*1024 }
 end
-
+```
+```rb
 class ImageUploader < ApplicationUploader
   Attacher.validate do
-    super() # empty braces are required
-    validate_mime_type_inclusion %w[image/jpeg image/jpg image/png]
+    super() # empty parentheses are required
+    validate_mime_type %w[image/jpeg image/png image/webp]
   end
 end
 ```
 
-[ImageProcessing]: https://github.com/janko/image_processing
+## Removing invalid files
+
+By default, an invalid file will remain assigned after validation failed, but
+you can have it automatically removed and deleted by loading the
+`remove_invalid` plugin.
+
+```rb
+Shrine.plugin :remove_invalid # remove and delete files that failed validation
+```
+
+[validation]: https://shrinerb.com/docs/plugins/validation
+[validation_helpers]: https://shrinerb.com/docs/plugins/validation_helpers