kt-paperclip 7.3.0 → 8.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 213cd04cf7f631853227e9c3fc6d6a38733f3c278907497e1f8e3c2e7a98bac8
-  data.tar.gz: 01aec044e7eff086cef50fab323730f617fd455e4ba70ffb99a58d099a4ffde5
+  metadata.gz: 71b12469bab65eb2861d1170c154ecf1a08f6a0591806096f3d49f598f4ec115
+  data.tar.gz: 12efe7db20633834994b3b1836cc697ff21dbf1bd37851346d1bd5e0961aa045
 SHA512:
-  metadata.gz: a7e922d52efbde590030651a7cbdca2087aa3c163d6cc498273e9ca57ce5c2b371b44601ccb9e825ee196f1197689438cb91cfca240b6361f259650ea63e5d03
-  data.tar.gz: 412ef55d0817f23247e52859d1b39cb1358f55bfd8c8d67cb16df376b42cc2926611b938004d6cec95d7a211895702cb279721322c1ac16e235af954a6f1f40e
+  metadata.gz: 6db416b89eaa01127e3b8eb7ac7615a19d840a236ea114be4814675d61765fa53f25e25b351b5d9438badf06ab3a20ec036565a418f47dbbcd97563d96e0f91f
+  data.tar.gz: 8aa390b628e9926d17c9de71e0dfe861fe2197762fff916064e1b61bd18fda5e3d2f6eda291d4e208e36ecb2fa3fc98ca366e5a28c479f7dde00b02736be2765

data/README.md

@@ -90,76 +90,44 @@ Requirements
 
 ### Ruby and Rails
 
-Paperclip now requires Ruby version **>= 2.3** and Rails version **>= 4.2**
+Paperclip now requires Ruby version **>= 2.7** and Rails version **>= 5.2**
 (only if you're going to use Paperclip with Ruby on Rails).
 
-### Image Processor
+### ImageMagick Image Processor
 
-[ImageMagick](http://www.imagemagick.org) must be installed and Paperclip must have access to it. To ensure
-that it does, on your command line, run `which convert` (one of the ImageMagick
-utilities). This will give you the path where that utility is installed. For
-example, it might return `/usr/local/bin/convert`.
+[ImageMagick](http://www.imagemagick.org) must be installed and Paperclip must have access to it.
+Refer to ImageMagick's [installations instructions](https://imagemagick.org/download/).
+ImageMagick 7 is the latest version. As of April 2026, some package managers such as `apt`
+still install ImageMagick 6.
 
-Then, in your environment config file, let Paperclip know to look there by adding that
-directory to its path.
-
-In development mode, you might add this line to `config/environments/development.rb)`:
+Paperclip supports both ImageMagick versions 6 and 7, and will auto-detect your version.
+You may enforce a specific version in an initializer such as `config/initializers/paperclip.rb`:
 
 ```ruby
-Paperclip.options[:command_path] = "/usr/local/bin/"
+Paperclip.options[:imagemagick_version] = "7"
 ```
 
-If you're on Mac OS X, you'll want to run the following with [Homebrew](http://www.brew.sh):
-
-    brew install imagemagick
-
-If you are dealing with pdf uploads or running the test suite, you'll also need
-to install GhostScript. On Mac OS X, you can also install that using Homebrew:
-
-    brew install gs
-
-If you are on Ubuntu (or any Debian base Linux distribution), you'll want to run
-the following with apt-get:
-
-    sudo apt-get install imagemagick -y
-
-### `file`
-
-The Unix [`file` command](https://en.wikipedia.org/wiki/File_(command)) is required for content-type checking.
-This utility isn't available in Windows, but comes bundled with Ruby [Devkit](https://github.com/oneclick/rubyinstaller/wiki/Development-Kit),
-so Windows users must make sure that the devkit is installed and added to the system `PATH`.
-
-**Manual Installation**
-
-If you're using Windows 7+ as a development environment, you may need to install the `file.exe` application manually. The `file spoofing` system in Paperclip 4+ relies on this; if you don't have it working, you'll receive `Validation failed: Upload file has an extension that does not match its contents.` errors.
-
-To manually install, you should perform the following:
+Please ensure ImageMagick is in your environment path, or alternatively set
+the path manually in an initializer:
 
-> **Download & install `file` from [this URL](http://gnuwin32.sourceforge.net/packages/file.htm)**
-
-To test, you can use the image below:
-![untitled](https://cloud.githubusercontent.com/assets/1104431/4524452/a1f8cce4-4d44-11e4-872e-17adb96f79c9.png)
-
-Next, you need to integrate with your environment - preferably through the `PATH` variable, or by changing your `config/environments/development.rb` file
-
-**PATH**
-
-    1. Click "Start"
-    2. On "Computer", right-click and select "Properties"
-    3. In Properties, select "Advanced System Settings"
-    4. Click the "Environment Variables" button
-    5. Locate the "PATH" var - at the end, add the path to your newly installed `file.exe` (typically `C:\Program Files (x86)\GnuWin32\bin`)
-    6. Restart any CMD shells you have open & see if it works
+```ruby
+Paperclip.options[:imagemagick_path] = "/usr/local/bin/"
+```
 
-OR
+### Optional: Unix `file` Command
 
-**Environment**
+Paperclip uses the [Marcel gem](https://github.com/rails/marcel) to detect file content types.
+If Marcel cannot detect the type, the [Unix `file` command](https://en.wikipedia.org/wiki/File_(command))
+is used as an optional fallback. To use it, ensure `file` is in your environment path,
+or alternatively set its path manually in an initializer:
 
-    1. Open `config/environments/development.rb`
-    2. Add the following line: `Paperclip.options[:command_path] = 'C:\Program Files (x86)\GnuWin32\bin'`
-    3. Restart your Rails server
+```ruby
+Paperclip.options[:file_command_path] = "/usr/local/bin/"
+```
 
-Either of these methods will give your Rails setup access to the `file.exe` functionality, thus providing the ability to check the contents of a file (fixing the spoofing problem)
+Windows users should install the `file` utility via the Ruby Installer for Windows'
+[DevKit](https://github.com/oneclick/rubyinstaller/wiki/Development-Kit), or alternatively,
+by installing [MSYS2](https://www.msys2.org/) which provides Unix utilities for Windows.
 
 ---
 
@@ -171,7 +139,7 @@ Paperclip is distributed as a gem, which is how it should be used in your app.
 Include the gem in your Gemfile:
 
 ```ruby
-gem "kt-paperclip", "~> 6.4", ">= 6.4.1"
+gem "kt-paperclip", "~> 8.0"
 ```
 
 Or, if you want to get the latest, you can get master from the main paperclip repository:
@@ -407,8 +375,10 @@ validates_attachment :avatar,
   content_type: ["image/jpeg", "image/gif", "image/png"]
 ```
 
-`Paperclip::ContentTypeDetector` will attempt to match a file's extension to an
-inferred content_type, regardless of the actual contents of the file.
+`Paperclip::ContentTypeDetector` uses the file's extension as a hint when the contents alone are
+ambiguous, so the stored `content_type` is not by itself proof of what a file contains. The check
+that ignores the filename entirely is `validates_media_type_spoof_detection` (see Security
+Validations below); use it alongside your `content_type` validation.
 
 ### Duplicate error messages
 
@@ -476,17 +446,26 @@ being uploaded as JPEGs, but will not prevent GIFs from being uploaded with a
 `.jpg` extension. This validation will only add validation errors to the form. It
 will not cause errors to be raised.
 
+The type is detected from the file's contents only, using magic-number detection plus the Unix
+`file` utility. The filename is never consulted. Where `file` is unavailable the check falls back
+to magic-number detection alone, which cannot identify text-based formats; content it cannot
+identify at all is accepted rather than rejected.
+
 This can sometimes cause false validation errors in applications that use custom
 file extensions. In these cases you may wish to add your custom extension to the
 list of content type mappings by creating `config/initializers/paperclip.rb`:
 
 ```ruby
-# Allow ".foo" as an extension for files with the MIME type "text/plain".
+# Allow ".foo" as an extension for files whose contents are detected as "text/plain".
 Paperclip.options[:content_type_mappings] = {
   foo: %w(text/plain)
 }
 ```
 
+The value is the type the *contents* detect as (what `file -b --mime` reports), not the type you
+would like the extension to mean. Text-based formats such as SVG and CSV are the usual reason to
+need one.
+
 ---
 
 Defaults

data/lib/generators/paperclip/paperclip_generator.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "rails/generators/active_record"
 
 class PaperclipGenerator < ActiveRecord::Generators::Base
@@ -31,6 +33,6 @@ class PaperclipGenerator < ActiveRecord::Generators::Base
   end
 
   def migration_version
-    "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]" if Rails.version.first.to_i > 4
+    "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
   end
 end

data/lib/kt-paperclip.rb

@@ -1 +1,3 @@
+# frozen_string_literal: true
+
 require "paperclip"

data/lib/paperclip/attachment.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "uri"
 require "paperclip/url_generator"
 require "active_support/deprecation"

data/lib/paperclip/attachment_registry.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "singleton"
 
 module Paperclip

data/lib/paperclip/callbacks.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Paperclip
   module Callbacks
     def self.included(base)
@@ -9,14 +11,15 @@ module Paperclip
       def define_paperclip_callbacks(*callbacks)
         define_callbacks(*[callbacks, { terminator: hasta_la_vista_baby }].flatten)
         callbacks.each do |callback|
-          eval <<-end_callbacks
-            def before_#{callback}(*args, &blk)
+          class_eval(<<~RUBY, __FILE__, __LINE__ + 1)
+            def self.before_#{callback}(*args, &blk)
               set_callback(:#{callback}, :before, *args, &blk)
             end
-            def after_#{callback}(*args, &blk)
+
+            def self.after_#{callback}(*args, &blk)
               set_callback(:#{callback}, :after, *args, &blk)
             end
-          end_callbacks
+          RUBY
         end
       end
 

data/lib/paperclip/commands/imagemagick/geometry_parser.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Paperclip
+  module Commands
+    module ImageMagick
+      module GeometryParser
+        extend self
+
+        FORMAT = /\b(\d*)x?(\d*)\b(?:,(\d?))?(@>|>@|[><#@%^!])?/i.freeze
+
+        # Runs `magick identify` and returns a Paperclip::Geometry
+        def detect(file)
+          parse(fetch(file))
+        end
+        alias_method :from_file, :detect
+
+        # Parses a "WxH,O" string into a Paperclip::Geometry
+        def parse(string)
+          return unless (match = string&.strip&.match(FORMAT))
+
+          Paperclip::Geometry.new(
+            width: match[1],
+            height: match[2],
+            orientation: match[3],
+            modifier: match[4]
+          )
+        end
+
+        private
+
+        def fetch(file)
+          filepath = path(file)
+          raise_error("Cannot find the geometry of a file with a blank name") if filepath.blank?
+
+          str = Paperclip::Commands::ImageMagick.identify(
+            "-format '%wx%h,#{orientation}' :file",
+            { file: "#{filepath}[0]" },
+            { swallow_stderr: true }
+          ).presence
+
+          raise_error unless str
+
+          str
+        rescue Terrapin::ExitStatusError
+          raise_error
+        end
+
+        def path(file)
+          file.respond_to?(:path) ? file.path : file
+        end
+
+        def orientation
+          Paperclip.options[:use_exif_orientation] ? "%[exif:orientation]" : "1"
+        end
+
+        def raise_error(message = nil)
+          message ||= "Could not identify image size"
+          raise Errors::NotIdentifiedByImageMagickError.new(message)
+        end
+      end
+    end
+  end
+end

data/lib/paperclip/commands/imagemagick/version_detector.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Paperclip
+  module Commands
+    module ImageMagick
+      module VersionDetector
+        extend self
+
+        # Returns 6, 7, or nil (not installed)
+        def detected_version
+          return @detected_version if defined?(@detected_version)
+
+          @detected_version = detect
+        end
+
+        private
+
+        def detect
+          return 7 if valid?("magick")
+          return 6 if valid?("convert")
+
+          nil
+        end
+
+        def valid?(command)
+          run(command).to_s.include?("ImageMagick")
+        end
+
+        def run(command)
+          Paperclip::Commands::Runner.run(command, path, "-version", {}, swallow_stderr: true)
+        rescue Terrapin::CommandLineError
+          nil
+        end
+
+        def path
+          Paperclip::Commands::ImageMagick.imagemagick_path
+        end
+      end
+    end
+  end
+end

data/lib/paperclip/commands/imagemagick.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Paperclip
+  module Commands
+    module ImageMagick
+      extend self
+
+      def convert(arguments = nil, interpolation_values = {}, local_options = {})
+        run(convert_command, imagemagick_path, arguments, interpolation_values, local_options)
+      end
+
+      def identify(arguments = nil, interpolation_values = {}, local_options = {})
+        run(identify_command, imagemagick_path, arguments, interpolation_values, local_options)
+      end
+
+      def imagemagick_path
+        Paperclip.options[:imagemagick_path]
+      end
+
+      private
+
+      def run(command, path = nil, arguments = nil, interpolation_values = {}, local_options = {})
+        Runner.run(command, path || imagemagick_path, arguments, interpolation_values, local_options)
+      rescue Terrapin::CommandNotFoundError
+        raise Errors::CommandNotFoundError.new("Could not run the `#{command}` command. Please install ImageMagick.")
+      end
+
+      # Returns true if ImageMagick 7 is in use (either detected or forced via config)
+      def magick_command?
+        version = Paperclip.options[:imagemagick_version]&.to_i ||
+                  VersionDetector.detected_version
+        !version.nil? && version >= 7
+      end
+
+      def convert_command
+        magick_command? ? "magick" : "convert"
+      end
+
+      def identify_command
+        magick_command? ? "magick identify" : "identify"
+      end
+    end
+  end
+end

data/lib/paperclip/commands/runner.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Paperclip
+  module Commands
+    module Runner
+      extend self
+
+      def run(command, path = nil, arguments = nil, interpolation_values = {}, local_options = {})
+        if Paperclip.logging? && (Paperclip.options[:log_command] || local_options[:log_command])
+          local_options = local_options.merge(logger: Paperclip.logger)
+        end
+
+        binary = resolve_binary(command, path)
+
+        Terrapin::CommandLine.new(binary, arguments, local_options)
+                             .run(interpolation_values)
+      end
+
+      private
+
+      def resolve_binary(command, path)
+        # @deprecated +Paperclip.options[:command_path]+ will be removed in Paperclip 8.0
+        path ||= Paperclip.options[:command_path]
+        return command unless path
+
+        # command may be multi-word (e.g. "magick identify")
+        words = command.split(" ", 2)
+        candidate = File.join(path, words[0])
+        if File.executable?(candidate)
+          words[0] = candidate
+          words.join(" ")
+        else
+          command
+        end
+      end
+    end
+  end
+end

data/lib/paperclip/commands/unix_file.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Paperclip
+  module Commands
+    module UnixFile
+      extend self
+
+      # Returns a normalized content type value, otherwise nil.
+      def detect_content_type(file)
+        type = run_file_command(file)
+        return if type.blank? || type.match(/\(.*?\)/)
+
+        type.split(/[:;\s]+/)[0].strip
+      rescue Terrapin::CommandLineError => e
+        Paperclip.log("Error while determining content type: #{e}")
+        nil
+      end
+
+      private
+
+      def run_file_command(file)
+        Runner.run("file", Paperclip.options[:file_command_path], "-b --mime :file", { file: file })
+      rescue Terrapin::CommandLineError
+        nil
+      end
+    end
+  end
+end

data/lib/paperclip/content_type_detector.rb

@@ -1,22 +1,25 @@
+# frozen_string_literal: true
+
 module Paperclip
+  # The content-type detection strategy is as follows:
+  #
+  # 1. Blank/Empty files: If there's no filepath or the file is empty,
+  #    provide a sensible default (application/octet-stream or inode/x-empty)
+  #
+  # 2. Calculated match: Return the first result that is found by both the
+  #    Marcel gem (or `file` command) and MIME::Types.
+  #
+  # 3. Standard types: Return the first standard (without an x- prefix) entry
+  #    in MIME::Types
+  #
+  # 4. Experimental types: If there were no standard types in MIME::Types
+  #    list, try to return the first experimental one
+  #
+  # 5. Raw `file` command: Just use the output of Marcel (or `file` command),
+  #    cached from step 2.
+  #
+  # 6. If nothing found, return a sensible default.
   class ContentTypeDetector
-    # The content-type detection strategy is as follows:
-    #
-    # 1. Blank/Empty files: If there's no filepath or the file is empty,
-    #    provide a sensible default (application/octet-stream or inode/x-empty)
-    #
-    # 2. Calculated match: Return the first result that is found by both the
-    #    `file` command and MIME::Types.
-    #
-    # 3. Standard types: Return the first standard (without an x- prefix) entry
-    #    in MIME::Types
-    #
-    # 4. Experimental types: If there were no standard types in MIME::Types
-    #    list, try to return the first experimental one
-    #
-    # 5. Raw `file` command: Just use the output of the `file` command raw, or
-    #    a sensible default. This is cached from Step 2.
-
     EMPTY_TYPE = "inode/x-empty"
     SENSIBLE_DEFAULT = "application/octet-stream"
 
@@ -25,15 +28,15 @@ module Paperclip
     end
 
     # Returns a String describing the file's content type
-    def detect
+    def detect(default = SENSIBLE_DEFAULT)
       if blank_name?
-        SENSIBLE_DEFAULT
+        default
       elsif empty_file?
         EMPTY_TYPE
       elsif calculated_type_matches.any?
         calculated_type_matches.first
       else
-        type_from_file_contents || SENSIBLE_DEFAULT
+        type_from_file_contents || default
       end.to_s
     end
 
@@ -60,26 +63,22 @@ module Paperclip
     end
 
     def type_from_file_contents
-      type_from_marcel || type_from_file_command
+      return @type_from_file_contents if defined?(@type_from_file_contents)
+
+      @type_from_file_contents = type_from_marcel || type_from_file_command
     rescue Errno::ENOENT => e
       Paperclip.log("Error while determining content type: #{e}")
-      SENSIBLE_DEFAULT
+      @type_from_file_contents = nil
     end
 
     def type_from_marcel
-      return @type_from_marcel if defined? @type_from_marcel
-
-      @type_from_marcel = Marcel::MimeType.for Pathname.new(@filepath),
-                                               name: @filepath
-      # Marcel::MineType returns 'application/octet-stream' if it can't find
-      # a valid type.
-      @type_from_marcel = nil if @type_from_marcel == SENSIBLE_DEFAULT
-      @type_from_marcel
+      type = Marcel::MimeType.for(Pathname.new(@filepath), name: @filepath)
+      # Marcel::MineType returns 'application/octet-stream' if it can't find a valid type.
+      type == SENSIBLE_DEFAULT ? nil : type
     end
 
     def type_from_file_command
-      @type_from_file_command ||=
-        FileCommandContentTypeDetector.new(@filepath).detect
+      Commands::UnixFile.detect_content_type(@filepath)
     end
   end
 end

data/lib/paperclip/errors.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Paperclip
   # A base error class for Paperclip. Most of the error that will be thrown
   # from Paperclip will inherits from this class.

data/lib/paperclip/file_command_content_type_detector.rb

@@ -1,28 +1,27 @@
+# frozen_string_literal: true
+
 module Paperclip
+  # @deprecated Will be removed in Paperclip 8.0. Use +Paperclip::ContentTypeDetector+ instead.
   class FileCommandContentTypeDetector
+    # @deprecated Will be removed in Paperclip 8.0.
     SENSIBLE_DEFAULT = "application/octet-stream"
 
+    # @deprecated Will be removed in Paperclip 8.0. Use +Paperclip::ContentTypeDetector+ instead.
     def initialize(filename)
+      warn_deprecation
       @filename = filename
     end
 
+    # @deprecated Will be removed in Paperclip 8.0. Use +Paperclip::ContentTypeDetector+ instead.
     def detect
-      type_from_file_command
+      warn_deprecation
+      Paperclip::Commands::UnixFile.detect_content_type(@filename) || SENSIBLE_DEFAULT
     end
 
     private
 
-    def type_from_file_command
-      # On BSDs, `file` doesn't give a result code of 1 if the file doesn't exist.
-      type = begin
-               Paperclip.run("file", "-b --mime :file", file: @filename)
-             rescue Terrapin::CommandLineError => e
-               Paperclip.log("Error while determining content type: #{e}")
-               SENSIBLE_DEFAULT
-             end
-
-      type = SENSIBLE_DEFAULT if type.nil? || type.match(/\(.*?\)/)
-      type.split(/[:;\s]+/)[0]
+    def warn_deprecation
+      Paperclip.deprecator.warn("Paperclip::FileCommandContentTypeDetector has been replaced by Paperclip::ContentTypeDetector.")
     end
   end
 end

data/lib/paperclip/filename_cleaner.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Paperclip
   class FilenameCleaner
     def initialize(invalid_character_regex)

data/lib/paperclip/geometry.rb

@@ -1,35 +1,42 @@
+# frozen_string_literal: true
+
 module Paperclip
   # Defines the geometry of an image.
   class Geometry
-    attr_accessor :height, :width, :modifier
+    attr_accessor :height, :width, :modifier, :orientation
 
     EXIF_ROTATED_ORIENTATION_VALUES = [5, 6, 7, 8].freeze
 
     # Gives a Geometry representing the given height and width
-    def initialize(width = nil, height = nil, modifier = nil)
+    def initialize(width = nil, height = nil, modifier = nil, orientation = nil)
       if width.is_a?(Hash)
         options = width
         @height = options[:height].to_f
         @width = options[:width].to_f
-        @modifier = options[:modifier]
+        @modifier = options[:modifier].presence
         @orientation = options[:orientation].to_i
       else
         @height = height.to_f
         @width  = width.to_f
-        @modifier = modifier
+        @modifier = modifier.presence
+        @orientation = orientation.to_i
       end
     end
 
     # Extracts the Geometry from a file (or path to a file)
+    #
+    # @deprecated Will be removed in Paperclip 8.0.
     def self.from_file(file)
-      GeometryDetector.new(file).make
+      Commands::ImageMagick::GeometryParser.from_file(file)
     end
 
     # Extracts the Geometry from a "WxH,O" string
     # Where W is the width, H is the height,
     # and O is the EXIF orientation
+    #
+    # @deprecated Will be removed in Paperclip 8.0.
     def self.parse(string)
-      GeometryParser.new(string).make
+      Commands::ImageMagick::GeometryParser.parse(string)
     end
 
     # Swaps the height and width if necessary
@@ -72,13 +79,21 @@ module Paperclip
 
     # Returns the width and height in a format suitable to be passed to Geometry.parse
     def to_s
-      s = String.new
+      s = +""
       s << width.to_i.to_s if width > 0
       s << "x#{height.to_i}" if height > 0
       s << modifier.to_s
       s
     end
 
+    def ==(other)
+      other.is_a?(Geometry) &&
+        width == other.width &&
+        height == other.height &&
+        modifier == other.modifier &&
+        orientation == other.orientation
+    end
+
     # Same as to_s
     def inspect
       to_s