Paperclip Documentation

To prepare your database for ActiveStorage, follow these steps:

1. Add the mini_magick gem to your Gemfile.
2. Ensure config/application.rb requires the ActiveStorage engine:

require "active_storage/engine"

3. Run the installation command:

rails active_storage:install

# config/application.rb
require "active_storage/engine"

Add Paperclip to your Gemfile to use it in your application.

To use a specific version:

gem "paperclip", "~> 6.0.0"

To use the latest code from the master branch:

gem "paperclip", git: "git://github.com/thoughtbot/paperclip.git"

You can pass lambdas or Procs to styles and processors to determine configuration at runtime based on the specific model instance.

# Dynamic Styles based on instance state
class User < ActiveRecord::Base
  has_attached_file :avatar, styles: lambda { |attachment| { thumb: (attachment.instance.boss? ? "300x300>" : "100x100>") } }
end

# Dynamic Processors based on instance state
class User < ActiveRecord::Base
  has_attached_file :avatar, processors: lambda { |instance| instance.processors }
  attr_accessor :processors
end

You can implement custom processors for tasks like watermarking, compression, or encryption.

To create a processor:

1. Define the class within the Paperclip module.
2. Inherit from Paperclip::Processor.
3. Implement a make method that returns a File.

Files located in lib/paperclip or lib/paperclip_processors are automatically loaded. Use the :processors option in has_attached_file to specify them. Processors are executed in the order defined; each successive processor receives the output of the previous one and the same options hash from the :styles definition.

# Example of applying a custom processor
has_attached_file :scan, styles: { text: { quality: :better } },
                         processors: [:ocr]

When running tests in parallel, the default storage path can cause file collisions. Use ENV['TEST_ENV_NUMBER'] to create unique paths for each test process.

if ENV['PARALLEL_TEST_GROUPS']
  Paperclip::Attachment.default_options[:path] = ":rails_root/public/system/:rails_env/#{ENV['TEST_ENV_NUMBER'].to_i}/:class/:attachment/:id_partition/:filename"
else
  Paperclip::Attachment.default_options[:path] = ":rails_root/public/system/:rails_env/:class/:attachment/:id_partition/:filename"
end

To ensure attachments survive deployments, symlink the public/system directory in your config/deploy.rb:

set :linked_dirs, fetch(:linked_dirs, []).push('public/system')

You can also automate the generation of missing styles by adding a task to your Capistrano deployment flow that runs rake paperclip:refresh:missing_styles.

namespace :paperclip do
  desc "build missing paperclip styles"
  task :build_missing_styles do
    on roles(:app) do
      within release_path do
        with rails_env: fetch(:rails_env) do
          execute :rake, "paperclip:refresh:missing_styles"
        end
      end
    end
  end
end

after("deploy:compile_assets", "paperclip:build_missing_styles")

Since Paperclip stores metadata directly on the associated object's table and ActiveStorage uses active_storage_blobs and active_storage_attachments tables, you must write a migration to convert the data.

Depending on your database, use the appropriate command to retrieve the last inserted ID within your migration:

• Postgres: get_blob_id = 'LASTVAL()'
• MariaDB: get_blob_id = 'LAST_INSERT_ID()'
• SQLite: get_blob_id = 'LAST_INSERT_ROWID()'

Note: The migration provided in the documentation uses prepared statements for active_storage_blob_statement and active_storage_attachment_statement to ensure data integrity during the transfer.

Paperclip is deprecated. For new projects, use Rails' built-in ActiveStorage.

For existing projects using Paperclip, you have several options:

1. Migrate to ActiveStorage: Consult the official migration guide or use alternative tutorials like the one used by Doorkeeper.
2. Use a maintained fork: Use kt-paperclip, which is an ongoing fork of Paperclip maintained by Kreeti.

Note: The original Paperclip repository is no longer accepting pull requests (except for the migration guide) and issues are only used as a discussion forum.

If you have other validations that depend on the order of assignment, prevent the automatic assignment of the attachment during mass assignment (e.g., via book_params). Instead, assign the attachment manually after the model is initialized to ensure validations run in the correct sequence.

class Book < ActiveRecord::Base
  has_attached_file :document, styles: { thumbnail: "60x60#" }
  validates_attachment :document, content_type: "application/pdf"
  validates_something_else # Other validations that conflict with Paperclip's
end

class BooksController < ApplicationController
  def create
    @book = Book.new(book_params)
    @book.document = params[:book][:document]
    @book.save
    respond_with @book
  end

private

def book_params
    params.require(:book).permit(:title, :author)
  end
end

Paperclip supports three built-in storage adapters:

• File Storage: Default local filesystem storage.
• S3 Storage: Requires the aws-sdk-s3 gem.
• Fog Storage: Uses the Fog library.

To use S3, add gem 'aws-sdk-s3' to your Gemfile and specify storage: :s3 in has_attached_file.