Branch: master
Find file Copy path
132 lines (115 sloc) 5.71 KB
# frozen_string_literal: true
require "ostruct"
# Image blobs can have variants that are the result of a set of transformations applied to the original.
# These variants are used to create thumbnails, fixed-size avatars, or any other derivative image from the
# original.
# Variants rely on {ImageProcessing}[] gem for the actual transformations
# of the file, so you must add <tt>gem "image_processing"</tt> to your Gemfile if you wish to use variants. By
# default, images will be processed with {ImageMagick}[] using the
# {MiniMagick}[] gem, but you can also switch to the
# {libvips}[] processor operated by the {ruby-vips}[]
# gem).
# Rails.application.config.active_storage.variant_processor
# # => :mini_magick
# Rails.application.config.active_storage.variant_processor = :vips
# # => :vips
# Note that to create a variant it's necessary to download the entire blob file from the service. Because of this process,
# you also want to be considerate about when the variant is actually processed. You shouldn't be processing variants inline
# in a template, for example. Delay the processing to an on-demand controller, like the one provided in
# ActiveStorage::RepresentationsController.
# To refer to such a delayed on-demand variant, simply link to the variant through the resolved route provided
# by Active Storage like so:
# <%= image_tag Current.user.avatar.variant(resize_to_limit: [100, 100]) %>
# This will create a URL for that specific blob with that specific variant, which the ActiveStorage::RepresentationsController
# can then produce on-demand.
# When you do want to actually produce the variant needed, call +processed+. This will check that the variant
# has already been processed and uploaded to the service, and, if so, just return that. Otherwise it will perform
# the transformations, upload the variant to the service, and return itself again. Example:
# avatar.variant(resize_to_limit: [100, 100]).processed.service_url
# This will create and process a variant of the avatar blob that's constrained to a height and width of 100.
# Then it'll upload said variant to the service according to a derivative key of the blob and the transformations.
# You can combine any number of ImageMagick/libvips operations into a variant, as well as any macros provided by the
# ImageProcessing gem (such as +resize_to_limit+):
# avatar.variant(resize_to_limit: [800, 800], monochrome: true, rotate: "-90")
# Visit the following links for a list of available ImageProcessing commands and ImageMagick/libvips operations:
# * {ImageProcessing::MiniMagick}[]
# * {ImageMagick reference}[]
# * {ImageProcessing::Vips}[]
# * {ruby-vips reference}[]
class ActiveStorage::Variant
WEB_IMAGE_CONTENT_TYPES = %w[ image/png image/jpeg image/jpg image/gif ]
attr_reader :blob, :variation
delegate :service, to: :blob
def initialize(blob, variation_or_variation_key)
@blob, @variation = blob, ActiveStorage::Variation.wrap(variation_or_variation_key)
# Returns the variant instance itself after it's been processed or an existing processing has been found on the service.
def processed
process unless processed?
# Returns a combination key of the blob and the variation that together identifies a specific variant.
def key
# Returns the URL of the variant on the service. This URL is intended to be short-lived for security and not used directly
# with users. Instead, the +service_url+ should only be exposed as a redirect from a stable, possibly authenticated URL.
# Hiding the +service_url+ behind a redirect also gives you the power to change services without updating all URLs. And
# it allows permanent URLs that redirect to the +service_url+ to be cached in the view.
# Use <tt>url_for(variant)</tt> (or the implied form, like +link_to variant+ or +redirect_to variant+) to get the stable URL
# for a variant that points to the ActiveStorage::RepresentationsController, which in turn will use this +service_call+ method
# for its redirection.
def service_url(expires_in: ActiveStorage.service_urls_expire_in, disposition: :inline)
service.url key, expires_in: expires_in, disposition: disposition, filename: filename, content_type: content_type
# Returns the receiving variant. Allows ActiveStorage::Variant and ActiveStorage::Preview instances to be used interchangeably.
def image
def processed?
def process do |image|
transform(image) { |output| upload(output) }
def transform(image, &block)
variation.transform(image, format: format, &block)
def upload(file)
service.upload(key, file)
def specification
@specification ||=
if WEB_IMAGE_CONTENT_TYPES.include?(blob.content_type) \
filename: blob.filename,
content_type: blob.content_type,
format: nil
else \
content_type: "image/png",
format: "png"
delegate :filename, :content_type, :format, to: :specification
class Specification < OpenStruct; end