shrine 2.4.1 → 2.5.0

data/lib/shrine/plugins/default_url.rb

@@ -3,20 +3,40 @@ class Shrine
     # The `default_url` plugin allows setting the URL which will be returned when
     # the attachment is missing.
     #
-    #     plugin :default_url do |context|
-    #       "/#{context[:name]}/missing.jpg"
+    #     plugin :default_url
+    #
+    #     Attacher.default_url do |options|
+    #       "/#{name}/missing.jpg"
     #     end
     #
-    # The default URL gets triggered when calling `<attachment>_url` on the
-    # model:
+    # `Attacher#url` returns the default URL when attachment is missing. Any
+    # passed in URL options will be present in the `options` hash.
+    #
+    #     attacher.url #=> "/avatar/missing.jpg"
+    #     # or
+    #     user.avatar_url #=> "/avatar/missing.jpg"
     #
-    #     user.avatar     #=> nil
-    #     user.avatar_url # "/avatar/missing.jpg"
+    # The default URL block is evaluated in the context of an instance of
+    # `Shrine::Attacher`.
     #
-    # Any additional URL options will be present in the `context` hash.
+    #     Attacher.default_url do |options|
+    #       self #=> #<Shrine::Attacher>
+    #
+    #       name   #=> :avatar
+    #       record #=> #<User>
+    #     end
     module DefaultUrl
       def self.configure(uploader, &block)
-        uploader.opts[:default_url] = block if block
+        if block
+          uploader.opts[:default_url] = block
+          warn "Passing a block to default_url Shrine plugin is deprecated and will probably be removed in future versions of Shrine. Use `Attacher.default_url { ... }` instead."
+        end
+      end
+
+      module AttacherClassMethods
+        def default_url(&block)
+          shrine_class.opts[:default_url_block] = block
+        end
       end
 
       module AttacherMethods
@@ -28,12 +48,14 @@ class Shrine
 
         def default_url(**options)
           if default_url_block
-            default_url_block.call(context.merge(options){|k,old,new|old})
+            instance_exec(options, &default_url_block)
+          elsif shrine_class.opts[:default_url]
+            shrine_class.opts[:default_url].call(context.merge(options){|k,old,new|old})
           end
         end
 
         def default_url_block
-          shrine_class.opts[:default_url]
+          shrine_class.opts[:default_url_block]
         end
       end
     end

data/lib/shrine/plugins/direct_upload.rb

@@ -251,7 +251,9 @@ class Shrine
           if presign_location
             presign_location.call(request)
           else
-            uploader.send(:generate_uid, nil) + request.params["extension"].to_s
+            extension = request.params["extension"]
+            extension.prepend(".") if extension && !extension.start_with?('.')
+            uploader.send(:generate_uid, nil) + extension.to_s
           end
         end
 

data/lib/shrine/plugins/processing.rb

@@ -1,7 +1,25 @@
 class Shrine
   module Plugins
-    # The `processing` plugin allows you to declaratively define file processing
-    # for specified actions.
+    # Shrine uploaders can define the `#process` method, which will get called
+    # whenever a file is uploaded. It is given the original file, and is
+    # expected to return the processed files.
+    #
+    #     def process(io, context)
+    #       # you can process the original file `io` and return processed file(s)
+    #     end
+    #
+    # However, when handling files as attachments, the same file is uploaded
+    # to temporary and permanent storage. Since we only want to apply the same
+    # processing once, we need to branch based on the context.
+    #
+    #     def process(io, context)
+    #       if context[:action] == :store # promote phase
+    #         # ...
+    #       end
+    #     end
+    #
+    # The `processing` plugin simplifies this by allowing us to declaratively
+    # define file processing for specified actions.
     #
     #     plugin :processing
     #
@@ -9,27 +27,28 @@ class Shrine
     #       # ...
     #     end
     #
-    # The `io` is the original file, while the `context` contains some
-    # additional information about the upload. The result of the processing
-    # block should be an IO-like object, which will continue being uploaded
-    # instead of the original.
+    # An example of resizing an image using the [image_processing] library:
     #
-    # The declarations are additive and inherited, so for the same action you
+    #     include ImageProcessing::MiniMagick
+    #
+    #     process(:store) do |io, context|
+    #       resize_to_limit!(io.download, 800, 800)
+    #     end
+    #
+    # The declarations are additive and inheritable, so for the same action you
     # can declare multiple blocks, and they will be performed in the same order,
-    # where output from previous will be input to next. You can return `nil`
-    # in any block to signal that no processing was performed and that the
-    # original file should be used.
+    # with output from previous block being the input to next.
     #
-    # The `.process` call is just a shorthand for
+    # You can manually trigger the defined processing via the uploader, you
+    # just need to specify `:action` to the name of your processing block:
     #
-    #     def process(io, context)
-    #       if context[:action] == :store
-    #         # ...
-    #       end
-    #     end
+    #     uploader.upload(file, action: :store)  # process and upload
+    #     uploader.process(file, action: :store) # only process
     #
     # If you want the result of processing to be multiple files, use the
     # `versions` plugin.
+    #
+    # [image_processing]: https://github.com/janko-m/image_processing
     module Processing
       def self.configure(uploader)
         uploader.opts[:processing] = {}

data/lib/shrine/plugins/rack_file.rb

@@ -2,43 +2,76 @@ require "forwardable"
 
 class Shrine
   module Plugins
-    # The `rack_file` plugin enables models to accept Rack file hashes as
-    # attachments.
+    # The `rack_file` plugin enables uploaders to accept Rack uploaded file
+    # hashes for uploading.
     #
-    #     rack_file #=>
+    #     plugin :rack_file
+    #
+    # When a file is uploaded to your Rack application using the
+    # `multipart/form-data` parameter encoding, Rack converts the uploaded file
+    # to a hash.
+    #
+    #     params[:file] #=>
     #     # {
+    #     #   name: "file"
     #     #   filename: "cats.png",
     #     #   type: "image/png",
     #     #   tempfile: #<Tempfile:/var/folders/3n/3asd/-Tmp-/RackMultipart201-1476-nfw2-0>,
     #     #   head: "Content-Disposition: form-data; ...",
     #     # }
-    #     user.avatar = rack_file
-    #     user.avatar.original_filename #=> "cats.png"
-    #     user.avatar.mime_type         #=> "image/png"
     #
-    # Internally the plugin wraps the Rack file hash into an IO-like object,
-    # and this is what is passed to `Shrine#upload`.
+    # Since Shrine only accepts IO objects, you would normally need to fetch
+    # the `:tempfile` object and pass it directly. This plugin enables the
+    # uploader and attacher to accept the Rack uploaded file hash as a whole,
+    # which is then internally converted into an IO object.
     #
-    #     plugin :rack_file
+    #     uploader.upload(params[:file])
+    #     # or
+    #     attacher.assign(params[:file])
+    #     # or
+    #     user.avatar = params[:file]
     #
-    # Note that this plugin is not needed in Rails applications, because Rails
+    # This especially convenient when doing mass attribute assignment with
+    # request parameters. It will also copy the received file information into
+    # metadata.
+    #
+    #     uploaded_file = uploader.upload(params[:file])
+    #     uploaded_file.original_filename #=> "cats.png"
+    #     uploaded_file.mime_type         #=> "image/png"
+    #
+    # Note that this plugin is not needed in Rails applications, as Rails
     # already wraps Rack uploaded files in `ActionDispatch::Http::UploadedFile`.
     module RackFile
-      module AttacherMethods
-        # Checks whether a file is a Rack file hash, and in that case wraps the
-        # hash in an IO-like object.
-        def assign(value)
-          if value.is_a?(Hash) && rack_file?(value)
-            assign(UploadedFile.new(value))
-          else
-            super
-          end
+      module InstanceMethods
+        # If `io` is a Rack uploaded file hash, converts it to an IO-like
+        # object and calls `super`.
+        def upload(io, context = {})
+          super(convert_rack_file(io), context)
+        end
+
+        # If `io` is a Rack uploaded file hash, converts it to an IO-like
+        # object and calls `super`.
+        def store(io, context = {})
+          super(convert_rack_file(io), context)
         end
 
         private
 
-        def rack_file?(hash)
-          hash.key?(:tempfile)
+        # If given a Rack uploaded file hash, returns a
+        # `Shrine::Plugins::RackFile::UploadedFile` IO-like object wrapping that
+        # hash, otherwise returns the value unchanged.
+        def convert_rack_file(value)
+          if rack_file?(value)
+            UploadedFile.new(value)
+          else
+            value
+          end
+        end
+
+        # Returns whether a given value is a Rack uploaded file hash, by
+        # checking whether it's a hash with `:tempfile` and `:name` keys.
+        def rack_file?(value)
+          value.is_a?(Hash) && value.key?(:tempfile) && value.key?(:name)
         end
       end
 

data/lib/shrine/plugins/remove_invalid.rb

@@ -13,6 +13,7 @@ class Shrine
           if errors.any? && cached?
             _delete(get, action: :validate)
             _set(@old)
+            remove_instance_variable(:@old)
           end
         end
       end

data/lib/shrine/plugins/store_dimensions.rb

@@ -5,13 +5,18 @@ class Shrine
     #
     #     plugin :store_dimensions
     #
-    # You can access the dimensions through `#width` and `#height` methods:
+    # It adds "width" and "height" metadata values to Shrine::UploadedFile,
+    # and creates `#width`, `#height` and `#dimensions` reader methods.
     #
-    #     uploader = Shrine.new(:store)
-    #     uploaded_file = uploader.upload(File.open("image.jpg"))
+    #     image = uploader.upload(file)
     #
-    #     uploaded_file.width  #=> 300
-    #     uploaded_file.height #=> 500
+    #     image.metadata["width"]  #=> 300
+    #     image.metadata["height"] #=> 500
+    #     # or
+    #     image.width  #=> 300
+    #     image.height #=> 500
+    #     # or
+    #     image.dimensions #=> [300, 500]
     #
     # The fastimage gem has built-in protection against [image bombs]. However,
     # if for some reason it doesn't suit your needs, you can provide a custom
@@ -77,6 +82,10 @@ class Shrine
         def height
           Integer(metadata["height"]) if metadata["height"]
         end
+
+        def dimensions
+          [width, height] if width || height
+        end
       end
     end
 

data/lib/shrine/plugins/upload_options.rb

@@ -15,6 +15,11 @@ class Shrine
     #         {acl: "private"}
     #       end
     #     end
+    #
+    # If you're uploading the file directly, you can also pass `:upload_options`
+    # to the uploader.
+    #
+    #     uploader.upload(file, upload_options: {acl: "public-read"})
     module UploadOptions
       def self.configure(uploader, options = {})
         uploader.opts[:upload_options] = (uploader.opts[:upload_options] || {}).merge(options)

data/lib/shrine/plugins/validation_helpers.rb

@@ -3,19 +3,25 @@ class Shrine
     # The `validation_helpers` plugin provides helper methods for validating
     # attached files.
     #
-    #     class ImageUploader < Shrine
-    #       plugin :validation_helpers
+    #     plugin :validation_helpers
     #
-    #       Attacher.validate do
-    #         validat_mime_type_inclusion %w[image/jpeg image/png image/gif]
-    #         validate_max_size 5*1024*1024 if record.guest?
-    #       end
+    #     Attacher.validate do
+    #       validat_mime_type_inclusion %w[image/jpeg image/png image/gif]
+    #       validate_max_size 5*1024*1024 if record.guest?
     #     end
     #
     # The validation methods are instance-level, the `Attacher.validate` block
     # is evaluated in context of an instance of `Shrine::Attacher`, so you can
     # easily do conditional validation.
     #
+    # The validation methods return whether the validation succeeded, allowing
+    # you to do conditional validation.
+    #
+    #     if validate_mime_type_inclusion %w[image/jpeg image/png image/gif]
+    #       validate_max_width 2000
+    #       validate_max_height 2000
+    #     end
+    #
     # If you would like to change default validation error messages, you can
     # pass in the `:default_messages` option to the plugin:
     #
@@ -58,52 +64,40 @@ class Shrine
       module AttacherMethods
         # Validates that the file is not larger than `max`.
         def validate_max_size(max, message: nil)
-          if get.size > max
-            errors << error_message(:max_size, message, max)
-          end
+          get.size <= max or add_error(:max_size, message, max) && false
         end
 
         # Validates that the file is not smaller than `min`.
         def validate_min_size(min, message: nil)
-          if get.size < min
-            errors << error_message(:min_size, message, min)
-          end
+          get.size >= min or add_error(:min_size, message, min) && false
         end
 
         # Validates that the file is not wider than `max`. Requires the
         # `store_dimensions` plugin.
         def validate_max_width(max, message: nil)
           raise Error, ":store_dimensions plugin is required" if !get.respond_to?(:width)
-          if get.width && get.width > max
-            errors << error_message(:max_width, message, max)
-          end
+          get.width <= max or add_error(:max_width, message, max) && false if get.width
         end
 
         # Validates that the file is not narrower than `min`. Requires the
         # `store_dimensions` plugin.
         def validate_min_width(min, message: nil)
           raise Error, ":store_dimensions plugin is required" if !get.respond_to?(:width)
-          if get.width && get.width < min
-            errors << error_message(:min_width, message, min)
-          end
+          get.width >= min or add_error(:min_width, message, min) && false if get.width
         end
 
         # Validates that the file is not taller than `max`. Requires the
         # `store_dimensions` plugin.
         def validate_max_height(max, message: nil)
           raise Error, ":store_dimensions plugin is required" if !get.respond_to?(:height)
-          if get.height && get.height > max
-            errors << error_message(:max_height, message, max)
-          end
+          get.height <= max or add_error(:max_height, message, max) && false if get.height
         end
 
         # Validates that the file is not shorter than `min`. Requires the
         # `store_dimensions` plugin.
         def validate_min_height(min, message: nil)
           raise Error, ":store_dimensions plugin is required" if !get.respond_to?(:height)
-          if get.height && get.height < min
-            errors << error_message(:min_height, message, min)
-          end
+          get.height >= min or add_error(:min_height, message, min) && false if get.height
         end
 
         # Validates that the MIME type is in the `whitelist`. The whitelist is
@@ -111,9 +105,8 @@ class Shrine
         #
         #     validate_mime_type_inclusion ["audio/mp3", /\Avideo/]
         def validate_mime_type_inclusion(whitelist, message: nil)
-          if whitelist.none? { |mime_type| regex(mime_type) =~ get.mime_type.to_s }
-            errors << error_message(:mime_type_inclusion, message, whitelist)
-          end
+          whitelist.any? { |mime_type| regex(mime_type) =~ get.mime_type.to_s } \
+            or add_error(:mime_type_inclusion, message, whitelist) && false
         end
 
         # Validates that the MIME type is not in the `blacklist`. The blacklist
@@ -121,9 +114,8 @@ class Shrine
         #
         #     validate_mime_type_exclusion ["image/gif", /\Aaudio/]
         def validate_mime_type_exclusion(blacklist, message: nil)
-          if blacklist.any? { |mime_type| regex(mime_type) =~ get.mime_type.to_s }
-            errors << error_message(:mime_type_exclusion, message, blacklist)
-          end
+          blacklist.none? { |mime_type| regex(mime_type) =~ get.mime_type.to_s } \
+            or add_error(:mime_type_exclusion, message, blacklist) && false
         end
 
         # Validates that the extension is in the `whitelist`. The whitelist
@@ -131,9 +123,8 @@ class Shrine
         #
         #     validate_extension_inclusion [/\Ajpe?g\z/i]
         def validate_extension_inclusion(whitelist, message: nil)
-          if whitelist.none? { |extension| regex(extension) =~ get.extension.to_s }
-            errors << error_message(:extension_inclusion, message, whitelist)
-          end
+          whitelist.any? { |extension| regex(extension) =~ get.extension.to_s } \
+            or add_error(:extension_inclusion, message, whitelist) && false
         end
 
         # Validates that the extension is not in the `blacklist`. The blacklist
@@ -141,16 +132,20 @@ class Shrine
         #
         #     validate_extension_exclusion ["mov", /\Amp/i]
         def validate_extension_exclusion(blacklist, message: nil)
-          if blacklist.any? { |extension| regex(extension) =~ get.extension.to_s }
-            errors << error_message(:extension_exclusion, message, blacklist)
-          end
+          blacklist.none? { |extension| regex(extension) =~ get.extension.to_s } \
+            or add_error(:extension_exclusion, message, blacklist) && false
         end
 
         private
 
         # Converts a string to a regex.
         def regex(value)
-          value.is_a?(Regexp) ? value : /\A#{Regexp.escape(value)}\z/
+          value.is_a?(Regexp) ? value : /\A#{Regexp.escape(value)}\z/i
+        end
+
+        # Generates an error message and appends it to errors array.
+        def add_error(*args)
+          errors << error_message(*args)
         end
 
         # Returns the direct message if given, otherwise uses the default error