DelayedPaperclip lets you process your Paperclip attachments in a background task with ActiveJob, DelayedJob, Resque or Sidekiq.
The most common use case for Paperclip is to easily attach image files to ActiveRecord models. Most of the time these image files will have multiple styles and will need to be resized when they are created. This is usually a pretty slow operation and should be handled in a background task.
I’m sure that everyone knows this, this gem just makes it easy to do.
Install the gem:
gem install delayed_paperclip
Or even better, add it to your Gemfile.
source "https://rubygems.org"
gem 'delayed_paperclip'
Dependencies:
- Paperclip
- DJ, Resque or Sidekiq
In your model:
classUser < ActiveRecord::Basehas_attached_file:avatar,styles: {medium: "300x300>",thumb: "100x100>"}process_in_background:avatarendUse your Paperclip attachment just like always in controllers and views.
To select between using Resque or Delayed::Job, just install and configure your choice properly within your application, and delayed_paperclip will do the rest. It will detect which library is loaded and make a decision about which sort of job to enqueue at that time.
Active Job will take precedence over any other installed library. Since it is installed as a dependency with Rails 4.2.1 this might cause some confusion, so make sure that Active Job is configured to use the correct queue adapter:
moduleYourAppclassApplication < Rails::Application# Other code...config.active_job.queue_adapter=:resque# Or :delayed_job or :sidekiqendendResque adapter is deprecated. Please use ActiveJob one.
Make sure that you have Resque up and running. The jobs will be
dispatched to the :paperclip queue, so you can correctly
dispatch your worker. Configure resque and your workers exactly as you
would otherwise.
DelayedJob adapter is deprecated. Please use ActiveJob one.
Just make sure that you have DJ up and running.
Sidekiq adapter is deprecated. Please use ActiveJob one.
Make sure that Sidekiq is running and listening to the
paperclip queue, either by adding it to your
sidekiq.yml config file under - queues: or by
passing the command line argument -q paperclip to Sidekiq.
In the default setup, when you upload an image for the first time and try to display it before the job has been completed, Paperclip will be none the wiser and output the url of the image which is yet to be processed, which will result in a broken image link being displayed on the page.
To have the missing image url be outputted by paperclip while the image is being processed, all you need to do is add a
#{attachment_name}_processing column to the specific model you want
to enable this feature for. This feature gracefully degrades and will not affect models which do not have the column added to them.
classAddAvatarProcessingToUser < ActiveRecord::Migrationdefself.upadd_column:users,:avatar_processing,:booleanenddefself.downremove_column:users,:avatar_processingendend@user=User.new(avatar: File.new(...))@user.save@user.avatar.url#=> "/images/original/missing.png"Delayed::Worker.new.work_off@user.reload@user.avatar.url#=> "/system/images/3/original/IMG_2772.JPG?1267562148"This is useful if you have a difference between missing images and images currently being processed.
classUser < ActiveRecord::Basehas_attached_file:avatarprocess_in_background:avatar,processing_image_url: "/images/:style/processing.jpg"end@user=User.new(avatar: File.new(...))@user.save@user.avatar.url#=> "/images/original/processing.png"Delayed::Worker.new.work_off@user.reload@user.avatar.url#=> "/system/images/3/original/IMG_2772.JPG?1267562148"You can also define a custom logic for processing_image_url, for
example to display the original
picture while specific formats are being processed.
classItem < ActiveRecord::Basehas_attached_file:photoprocess_in_background:photo,processing_image_url: :processing_image_fallbackdefprocessing_image_fallbackoptions=photo.optionsoptions[:interpolator].interpolate(options[:url],photo,:original)endendIf you define the #{attachment_name}_processing column, but set the
url_with_processing option to false, this opens up other options (other than modifying the url that paperclip returns) for giving feedback to the user while the image is processing. This is useful for advanced situations, for example when dealing with caching systems.
Note especially the method #processing? which passes through the value of the boolean created via migration.
classUser < ActiveRecord::Basehas_attached_file:avatarprocess_in_background:avatar,url_with_processing: falseend@user=User.new(avatar: File.new(...))@user.save@user.avatar.url#=> "/system/images/3/original/IMG_2772.JPG?1267562148"@user.avatar.processing?#=> trueDelayed::Worker.new.work_off@user.reload@user.avatar.url#=> "/system/images/3/original/IMG_2772.JPG?1267562148"@user.avatar.processing?#=> falseThis is useful if you don’t want the background job to reprocess all styles.
classUser < ActiveRecord::Basehas_attached_file:avatar,styles: {small: "25x25#",medium: "50x50#"}process_in_background:avatar,only_process: [:small]endLike paperclip, you could also supply a lambda function to define
only_process dynamically.
classUser < ActiveRecord::Basehas_attached_file:avatar,styles: {small: "25x25#",medium: "50x50#"}process_in_background:avatar,only_process: lambda{ |a| a.instance.small_supported? ? [:small,:large] : [:large]}endYou can process some styles in the foreground and some in the background
by setting only_process on both has_attached_file and
process_in_background.
classUser < ActiveRecord::Basehas_attached_file:avatar,styles: {small: "25x25#",medium: "50x50#"},only_process: [:small]process_in_background:avatar,only_process: [:medium]endThis is useful if you don’t want the background job. It accepts
individual styles to. Take note, normal reprocess! does not accept styles as arguments anymore. It will delegate to DelayedPaperclip and
reprocess all styles.
classUser < ActiveRecord::Basehas_attached_file:avatar,styles: {small: "25x25#",medium: "50x50#"}process_in_background:avatarend@user.avatar.url#=> "/system/images/3/original/IMG_2772.JPG?1267562148"@user.avatar.reprocess_without_delay!(:medium)You can set queue name for background job. By default it's called "paperclip". You can set it by changing global default options or by:
classUser < ActiveRecord::Basehas_attached_file:avatarprocess_in_background:avatar,queue: "default"endGlobal defaults for all delayed_paperclip instances in your app can be
defined by changing the DelayedPaperclip.options Hash, this can be useful for setting a default ‘processing image,’ so you won’t have to define it in every process_in_background definition.
If you’re using Rails you can define a Hash with default options in
config/application.rb or in any of the config/environments/*.rb files on config.delayed_paperclip_defaults, these will get merged into DelayedPaperclip.options as your Rails app boots. An example:
moduleYourAppclassApplication < Rails::Application# Other code...config.delayed_paperclip_defaults={url_with_processing: true,processing_image_url: 'custom_processing.png'}endendThis library works no matter what kind of post-processing you are doing with Paperclip.
If you are using custom post-processing processors like this:
# ...has_attached_file:avatar,styles: {thumb: '100x100>'},processors: [:rotator]process_in_background:avatardefrotate!# ...avatar.reprocess!# ...end# ......you may encounter an issue where your post-processors are ignored
(more info).
In order to avoid this use reprocess_without_delay!
# ...defrotate!# ...avatar.reprocess_without_delay!# ...end# ...Yes.
Checkout out CONTRIBUTING. Run specs with:
# Rspec on all versions
bundle exec appraisal install
bundle exec appraisal rake
# Rspec on latest stable gems
bundle exec rake
# Rspec on specific rails version
bundle exec appraisal 5.0 rake