paperclip 2.3.16 → 2.4.0

data/README.md

@@ -1,5 +1,4 @@
-Paperclip
-=========
+# Paperclip [![Build Status](https://secure.travis-ci.org/thoughtbot/paperclip.png?branch=master)](http://travis-ci.org/thoughtbot/paperclip)
 
 Paperclip is intended as an easy file attachment library for ActiveRecord. The
 intent behind it was to keep setup as easy as possible and to treat files as
@@ -26,13 +25,21 @@ 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`.
 
-Then, in your environment config file, let Paperclip know to look there by adding that 
+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.options[:command_path] = "/usr/local/bin/"
 
+If you're on Mac OSX, you'll want to run the following with Homebrew:
+
+    brew install imagemagick
+
+If you are dealing with pdf uploads or running the test suite, also run:
+
+    brew install gs
+
 Installation
 ------------
 
@@ -99,6 +106,11 @@ In your show view:
     <%= image_tag @user.avatar.url(:medium) %>
     <%= image_tag @user.avatar.url(:thumb) %>
 
+To detach a file, simply set the attribute to `nil`:
+
+    @user.avatar = nil
+    @user.save
+
 Usage
 -----
 
@@ -219,6 +231,130 @@ Paperclip has an interpolation called `:hash` for obfuscating filenames of publi
 
 [https://github.com/thoughtbot/paperclip/pull/416](https://github.com/thoughtbot/paperclip/pull/416)
 
+MD5 Checksum / Fingerprint
+-------
+
+A MD5 checksum of the original file assigned will be placed in the model if it
+has an attribute named fingerprint.  Following the user model migration example
+above, the migration would look like the following.
+
+    class AddAvatarFingerprintColumnToUser < ActiveRecord::Migration
+      def self.up
+        add_column :users, :avatar_fingerprint, :string
+      end
+
+      def self.down
+        remove_column :users, :avatar_fingerprint
+      end
+    end
+
+Custom Attachment Processors
+-------
+
+Custom attachment processors can be implemented and their only requirement is
+to inherit from `Paperclip::Processor` (see `lib/paperclip/processor.rb`).
+For example, when `:styles` are specified for an image attachment, the
+thumbnail processor (see `lib/paperclip/thumbnail.rb`) is loaded without having
+to specify it as a `:processor` parameter to `has_attached_file`.  When any
+other processor is defined it must be called out in the `:processors`
+parameter if it is to be applied to the attachment.  The thumbnail processor
+uses the imagemagick `convert` command to do the work of resizing image
+thumbnails.  It would be easy to create a custom processor that watermarks
+an image using imagemagick's `composite` command.  Following the
+implementation pattern of the thumbnail processor would be a way to implement a
+watermark processor.  All kinds of attachment processors can be created;
+a few utility examples would be compression and encryption processors.
+
+
+Dynamic Configuration
+---------------------
+
+Callable objects (labdas, Procs) can be used in a number of places for dynamic
+configuration throughout Paperclip.  This strategy exists in a number of
+components of the library but is most significant in the possibilities for
+allowing custom styles and processors to be applied for specific model
+instances, rather than applying defined styles and processors across all
+instances.
+
+Dynamic Styles:
+
+Imagine a user model that had different styles based on the role of the user.
+Perhaps some users are bosses (e.g. a User model instance responds to #boss?)
+and merit a bigger avatar thumbnail than regular users. The configuration to
+determine what style parameters are to be used based on the user role might
+look as follows where a boss will receive a `300x300` thumbnail otherwise a
+`100x100` thumbnail will be created.
+
+    class User < ActiveRecord::Base
+      has_attached_file :avatar, :styles => lambda { |attachment| { :thumb => (attachment.instance.boss? ? "300x300>" : "100x100>") }
+    end
+
+Dynamic Processors:
+
+Another contrived example is a user model that is aware of which file processors
+should be applied to it (beyond the implied `thumbnail` processor invoked when
+`:styles` are defined). Perhaps we have a watermark processor available and it is
+only used on the avatars of certain models.  The configuration for this might be
+where the instance is queried for which processors should be applied to it.
+Presumably some users might return `[:thumbnail, :watermark]` for its
+processors, where a defined `watermark` processor is invoked after the
+`thumbnail` processor already defined by Paperclip.
+
+    class User < ActiveRecord::Base
+      has_attached_file :avatar, :processors => lambda { |instance| instance.processors }
+      attr_accessor :watermark
+    end
+
+Deploy
+------
+
+Paperclip is aware of new attachment styles you have added in previous deploy. The only thing you should do after each deployment is to call
+`rake paperclip:refresh:missing_styles`.  It will store current attachment styles in `RAILS_ROOT/public/system/paperclip_attachments.yml`
+by default. You can change it by:
+
+    Paperclip.registered_attachments_styles_path = '/tmp/config/paperclip_attachments.yml'
+
+Here is an example for Capistrano:
+
+    namespace :deploy do
+      desc "build missing paperclip styles"
+      task :build_missing_paperclip_styles, :roles => :app do
+        run "cd #{release_path}; RAILS_ENV=production bundle exec rake paperclip:refresh:missing_styles"
+      end
+    end
+    
+    after("deploy:update_code", "deploy:build_missing_paperclip_styles")
+
+Now you don't have to remember to refresh thumbnails in production everytime you add new style.
+Unfortunately it does not work with dynamic styles - it just ignores them.
+
+If you already have working app and don't want `rake paperclip:refresh:missing_styles` to refresh old pictures, you need to tell
+Paperclip about existing styles. Simply create paperclip_attachments.yml file by hand. For example:
+
+    class User < ActiveRecord::Base
+      has_attached_file :avatar, :styles => {:thumb => 'x100', :croppable => '600x600>', :big => '1000x1000>'}
+    end
+  
+    class Book < ActiveRecord::Base
+      has_attached_file :cover, :styles => {:small => 'x100', :large => '1000x1000>'}
+      has_attached_file :sample, :styles => {:thumb => 'x100'}
+    end
+
+Then in `RAILS_ROOT/public/system/paperclip_attachments.yml`:
+
+    --- 
+    :User: 
+      :avatar: 
+      - :thumb
+      - :croppable
+      - :big
+    :Book: 
+      :cover: 
+      - :small
+      - :large
+      :sample: 
+      - :thumb
+
 Testing
 -------
 
@@ -233,7 +369,7 @@ If you'd like to contribute a feature or bugfix: Thanks! To make sure your
 fix/feature has a high chance of being included, please read the following
 guidelines:
 
-1. Ask on the mailing list[http://groups.google.com/group/paperclip-plugin], or 
+1. Ask on the mailing list[http://groups.google.com/group/paperclip-plugin], or
    post a new GitHub Issue[http://github.com/thoughtbot/paperclip/issues].
 2. Make sure there are tests! We will not accept any patch that is not tested.
    It's a rare time when explicit tests aren't needed. If you have questions

data/lib/paperclip.rb

@@ -39,7 +39,9 @@ require 'paperclip/style'
 require 'paperclip/attachment'
 require 'paperclip/storage'
 require 'paperclip/callback_compatibility'
+require 'paperclip/missing_attachment_styles'
 require 'paperclip/railtie'
+require 'logger'
 require 'cocaine'
 
 # The base module that gets included in ActiveRecord::Base. See the
@@ -91,7 +93,7 @@ module Paperclip
     # This method can log the command being run when
     # Paperclip.options[:log_command] is set to true (defaults to false). This
     # will only log if logging in general is set to true as well.
-    def run cmd, *params
+    def run(cmd, *params)
       if options[:image_magick_path]
         Paperclip.log("[DEPRECATION] :image_magick_path is deprecated and will be removed. Use :command_path instead")
       end
@@ -99,14 +101,16 @@ module Paperclip
       Cocaine::CommandLine.new(cmd, *params).run
     end
 
-    def processor name #:nodoc:
-      name = name.to_s.camelize
-      load_processor(name) unless Paperclip.const_defined?(name)
-      processor = Paperclip.const_get(name)
-      unless processor.ancestors.include?(Paperclip::Processor)
-        raise PaperclipError.new("Processor #{name} was not found")
+    def processor(name) #:nodoc:
+      @known_processors ||= {}
+      if @known_processors[name.to_s]
+        @known_processors[name.to_s]
+      else
+        name = name.to_s.camelize
+        load_processor(name) unless Paperclip.const_defined?(name)
+        processor = Paperclip.const_get(name)
+        @known_processors[name.to_s] = processor
       end
-      processor
     end
 
     def load_processor(name)
@@ -115,6 +119,23 @@ module Paperclip
       end
     end
 
+    def clear_processors!
+      @known_processors.try(:clear)
+    end
+
+    # You can add your own processor via the Paperclip configuration. Normally
+    # Paperclip will load all processors from the
+    # Rails.root/lib/paperclip_processors directory, but here you can add any
+    # existing class using this mechanism.
+    #
+    #   Paperclip.configure do |c|
+    #     c.register_processor :watermarker, WatermarkingProcessor.new
+    #   end
+    def register_processor(name, processor)
+      @known_processors ||= {}
+      @known_processors[name.to_s] = processor
+    end
+
     def each_instance_with_attachment(klass, name)
       class_for(klass).all.each do |instance|
         yield(instance) if instance.send(:"#{name}?")
@@ -128,7 +149,11 @@ module Paperclip
     end
 
     def logger #:nodoc:
-      defined?(ActiveRecord::Base) ? ActiveRecord::Base.logger : Rails.logger
+      @logger ||= options[:logger] || Logger.new(STDOUT)
+    end
+
+    def logger=(logger)
+      @logger = logger
     end
 
     def logging? #:nodoc:
@@ -264,9 +289,11 @@ module Paperclip
       end
 
       attachment_definitions[name] = {:validations => []}.merge(options)
+      Paperclip.classes_with_attachments << self
 
       after_save :save_attached_files
-      before_destroy :destroy_attached_files
+      before_destroy :prepare_for_destroy
+      after_destroy :destroy_attached_files
 
       define_paperclip_callbacks :post_process, :"#{name}_post_process"
 
@@ -328,7 +355,7 @@ module Paperclip
     #   be run is this lambda or method returns true.
     # * +unless+: Same as +if+ but validates if lambda or method returns false.
     def validates_attachment_presence name, options = {}
-      message = options[:message] || "must be set"
+      message = options[:message] || :empty
       validates_presence_of :"#{name}_file_name",
                             :message   => message,
                             :if        => options[:if],
@@ -402,10 +429,17 @@ module Paperclip
     def destroy_attached_files
       Paperclip.log("Deleting attachments.")
       each_attachment do |name, attachment|
-        attachment.send(:queue_existing_for_delete)
         attachment.send(:flush_deletes)
       end
     end
+
+    def prepare_for_destroy
+      Paperclip.log("Scheduling attachments for deletion.")
+      each_attachment do |name, attachment|
+        attachment.send(:queue_existing_for_delete)
+      end
+    end
+
   end
 
 end

data/lib/paperclip/attachment.rb

@@ -14,6 +14,7 @@ module Paperclip
         :only_process          => [],
         :processors            => [:thumbnail],
         :convert_options       => {},
+        :source_file_options   => {},
         :default_url           => "/:attachment/:style/missing.png",
         :default_style         => :original,
         :storage               => :filesystem,
@@ -26,12 +27,33 @@ module Paperclip
       }
     end
 
-    attr_reader :name, :instance, :default_style, :convert_options, :queued_for_write, :whiny, :options
+    attr_reader :name, :instance, :default_style, :convert_options, :queued_for_write, :whiny, :options, :source_file_options, :interpolator
     attr_accessor :post_processing
 
     # Creates an Attachment object. +name+ is the name of the attachment,
     # +instance+ is the ActiveRecord object instance it's attached to, and
     # +options+ is the same as the hash passed to +has_attached_file+.
+    #
+    # Options include:
+    #
+    #  +url+ - a relative URL of the attachment. This is interpolated using +interpolator+
+    #  +path+ - where on the filesystem to store the attachment. This is interpolated using +interpolator+
+    #  +styles+ - a hash of options for processing the attachment. See +has_attached_file+ for the details
+    #  +only_process+ - style args to be run through the post-processor. This defaults to the empty list
+    #  +default_url+ - a URL for the missing image
+    #  +default_style+ - the style to use when don't specify an argument to e.g. #url, #path
+    #  +storage+ - the storage mechanism. Defaults to :filesystem
+    #  +use_timestamp+ - whether to append an anti-caching timestamp to image URLs. Defaults to true
+    #  +whiny+, +whiny_thumbnails+ - whether to raise when thumbnailing fails
+    #  +use_default_time_zone+ - related to +use_timestamp+. Defaults to true
+    #  +hash_digest+ - a string representing a class that will be used to hash URLs for obfuscation
+    #  +hash_data+ - the relative URL for the hash data. This is interpolated using +interpolator+
+    #  +hash_secret+ - a secret passed to the +hash_digest+
+    #  +convert_options+ - flags passed to the +convert+ command for processing
+    #  +source_file_options+ - flags passed to the +convert+ command that controls how the file is read
+    #  +processors+ - classes that transform the attachment. Defaults to [:thumbnail]
+    #  +preserve_files+ - whether to keep files on the filesystem when deleting to clearing the attachment. Defaults to false
+    #  +interpolator+ - the object used to interpolate filenames and URLs. Defaults to Paperclip::Interpolations
     def initialize name, instance, options = {}
       @name              = name
       @instance          = instance
@@ -55,6 +77,7 @@ module Paperclip
       @hash_data             = options[:hash_data]
       @hash_secret           = options[:hash_secret]
       @convert_options       = options[:convert_options]
+      @source_file_options   = options[:source_file_options]
       @processors            = options[:processors]
       @preserve_files        = options[:preserve_files]
       @options               = options
@@ -63,6 +86,7 @@ module Paperclip
       @queued_for_write      = {}
       @errors                = {}
       @dirty                 = false
+      @interpolator          = (options[:interpolator] || Paperclip::Interpolations)
 
       initialize_storage
     end
@@ -111,7 +135,7 @@ module Paperclip
 
       @dirty = true
 
-      post_process(*@only_process) if @post_processing
+      post_process(*@only_process) if post_processing
 
       # Reset the file size if the original file was reprocessed.
       instance_write(:file_size,   @queued_for_write[:original].size.to_i)
@@ -136,7 +160,7 @@ module Paperclip
     # file is stored in the filesystem the path refers to the path of the file
     # on disk. If the file is stored in S3, the path is the "key" part of the
     # URL, and the :bucket option refers to the S3 bucket.
-    def path style_name = default_style
+    def path(style_name = default_style)
       original_filename.nil? ? nil : interpolate(@path, style_name)
     end
 
@@ -341,6 +365,15 @@ module Paperclip
       [ style_options, all_options ].compact.join(" ")
     end
 
+    def extra_source_file_options_for(style) #:nodoc:
+      all_options   = source_file_options[:all]
+      all_options   = all_options.call(instance)   if all_options.respond_to?(:call)
+      style_options = source_file_options[style]
+      style_options = style_options.call(instance) if style_options.respond_to?(:call)
+
+      [ style_options, all_options ].compact.join(" ")
+    end
+
     def post_process(*style_args) #:nodoc:
       return if @queued_for_write[:original].nil?
       instance.run_paperclip_callbacks(:post_process) do
@@ -366,8 +399,8 @@ module Paperclip
       end
     end
 
-    def interpolate pattern, style_name = default_style #:nodoc:
-      Paperclip::Interpolations.interpolate(pattern, self, style_name)
+    def interpolate(pattern, style_name = default_style) #:nodoc:
+      interpolator.interpolate(pattern, self, style_name)
     end
 
     def queue_existing_for_delete #:nodoc:
@@ -387,5 +420,13 @@ module Paperclip
       end
     end
 
+    # called by storage after the writes are flushed and before @queued_for_writes is cleared
+    def after_flush_writes
+      @queued_for_write.each do |style, file|
+        file.close unless file.closed?
+        file.unlink if file.respond_to?(:unlink) && file.path.present? && File.exist?(file.path)
+      end
+    end
+
   end
 end

data/lib/paperclip/interpolations.rb

@@ -94,6 +94,31 @@ module Paperclip
         File.extname(attachment.original_filename).gsub(/^\.+/, "")
     end
 
+    # Returns an extension based on the content type. e.g. "jpeg" for "image/jpeg".
+    # Each mime type generally has multiple extensions associated with it, so
+    # if the extension from teh original filename is one of these extensions,
+    # that extension is used, otherwise, the first in the list is used.
+    def content_type_extension attachment, style_name
+      mime_type = MIME::Types[attachment.content_type]
+      extensions_for_mime_type = unless mime_type.empty?
+        mime_type.first.extensions
+      else
+        []
+      end
+
+      original_extension = extension(attachment, style_name)
+      if extensions_for_mime_type.include? original_extension
+        original_extension
+      elsif !extensions_for_mime_type.empty?
+        extensions_for_mime_type.first
+      else
+        # It's possible, though unlikely, that the mime type is not in the
+        # database, so just use the part after the '/' in the mime type as the
+        # extension.
+        %r{/([^/]*)$}.match(attachment.content_type)[1]
+      end
+    end
+
     # Returns the id of the instance.
     def id attachment, style_name
       attachment.instance.id
@@ -118,7 +143,11 @@ module Paperclip
     # Returns the id of the instance in a split path form. e.g. returns
     # 000/001/234 for an id of 1234.
     def id_partition attachment, style_name
-      ("%09d" % attachment.instance.id).scan(/\d{3}/).join("/")
+      if (id = attachment.instance.id).is_a?(Integer)
+        ("%09d" % id).scan(/\d{3}/).join("/")
+      else
+        id.scan(/.{3}/).first(3).join("/")
+      end
     end
 
     # Returns the pluralized form of the attachment name. e.g.