Paperclip is Going Three-Point-Oh Nelly

The new version of your favorite file upload library, Paperclip 3.0.0, has been released earlier today. We changed a lot of internals to make Paperclip better. These changes lay the groundwork for the shiny, new features that will come in the future.

Goodbye, Rails 2.3.x and Ruby 1.8.7

Ruby 1.8.7 and Ruby on Rails 2.3.x are both reaching end of life now, so this is a good time to drop support for them. This let us remove some code and introduce a new validator syntax (below.)

If you’re still using Ruby on Rails 2.3.x or Ruby 1.8.7, you should lock Paperclip to version 2.x by doing this:

gem "paperclip", "~> 2.7"

In some rare case that there’s a critical bug in Paperclip 2.7.x, we’ll release a patch version under that minor version. However, you’re advised to upgrade to a newer version of Ruby and Rails as soon as you can.

Modularized Internals

We’re working to extract functionality into modules. We’re not done with this yet, and it is an ongoing process. If you’ve freedom patched Paperclip, you’ll need to look out for this as some of the methods might have new names or locations.

If you are developing a plugin for Paperclip—e.g. custom storage, a processor, or a validator—we would love to hear from you. We want to expose hooks to help you develop your plugin and reduce the risk of breaking things in the future.

Default attachment path has been changed

When you’re installing the new version of Paperclip, you’ll be greeted with this upgrading message:

##################################################
#  NOTE FOR UPGRADING FROM PRE-3.0 VERSION       #
##################################################

Paperclip 3.0 introduces a non-backward compatible change in your attachment
path. This will help to prevent attachment name clashes when you have
multiple attachments with the same name. If you didn't alter your
attachment's path and are using Paperclip's default, you'll have to add
`:path` and `:url` to your `has_attached_file` definition. For example:

    has_attached_file :avatar,
      :path => ":rails_root/public/system/:attachment/:id/:style/:filename",
      :url => "/system/:attachment/:id/:style/:filename"

Going forward, the default URL for your attachment will be /system/:class/:attachment/:id_partition/:style/:filename. This will prevent filename collisions and will reduce the number of files in a single directory.

Rails 3 Validators

All of the validators have been rewritten to take the full advantage of Rails 3. They’re now in their own Validator class, and can be passed into validates or validates_with like any other Active Model validator:

validates :avatar, :attachment_presence => true
validates_with AttachmentPresenceValidator, :attributes => :avatar

We are also introducing a validates_attachment method. This method is almost the same as the validates method except you can skip the :attachment_ prefix. We’ve found this helpful when defining multiple validators on a single attachment:

validates_attachment :avatar, :presence => true,
  :content_type => { :content_type => "image/jpg" },
  :size => { :in => 0..10.kilobytes }

Going forward

I would like to thank our contributors and all of the other users who are helping to make Paperclip better and better. Please give this new version a try. If you find a bug, please file an issue, or better, you can also help us fixing it.

We’re thrilled to introduce the new Paperclip, and we hope that you’ll like them.