Last Update: 2023-07-30 18:26:06 +0200

title: Shrine 2.0.0

Backwards compatibility

  • Metadata and upload options are now differently passed to storages, so the new signature of #upload and #move methods on the storage class should be:

def upload(io, id, shrine_metadata: {}, **upload_options)
  # ...

def move(io, id, shrine_metadata: {}, **upload_options)
  # ...
  • The Shrine::Confirm functionality has been removed from storages' specification, storages should update clear! to remove the confirmation.

  • The :delegate option in migration_helpers now defaults to false.

  • The migration_helpers plugin has been deprecated, Shrine::Attacher#cached? and Shrine::Attacher#stored? have been moved to base functionality.

  • The "background_helpers" alias for the backgrounding plugin has been deprecated and will be removed in Shrine 3.

  • In backgrounding plugin the "attachment" key has been renamed to "name", and "uploaded_file" has been renamed to "attachment" in the data hash in background job argument.

  • Shrine::Attacher.promote and Shrine::Attacher.delete from backgrounding plugin now return a Shrine::Attacher instance instead of the model instance.

  • The moving plugin doesn't delete files that aren't movable anymore. You should use delete_raw and/or delete_promoted plugins for this functionality.

  • The deprecated "delete_uploaded" alias for delete_raw plugin has been removed.

  • The deprecated "restore_cached" alias for restore_cached_data plugin has been removed.

  • The deprecated keep_location plugin has been removed.

  • The deprecated :subdirectory option in FileSystem storage has been removed.

  • The deprecated Shrine#default_url has been removed (specifying a default URL by overriding #default_url on the uploader), the default_url plugin should be used instead.

  • The deprecated Shrine.direct_endpoint alias for Shrine::UploadEndpoint in direct_upload plugin has been removed.

  • The :presign option in direct_upload plugin cannot be used for specifying presign options anymore; :presign_options should be used instead.

  • Shrine::Attacher#set and #assign methods don’t return the assigned uploaded file anymore.

  • Shrine::Attacher#delete! doesn’t spawn a background job anymore with backgrounding plugin, plugin writers should switch to #_delete instead.

  • The phases when files are internally deleted have been renamed.

  • Shrine doesn’t officially support Rubinius anymore.

New plugins

New storages

  • The shrine-memory storage has been released, which saves uploaded files in memory (useful in tests).

New features

  • The built-in analyzers can now be used when implementing a custom MIME type analyzer in determine_mime_type plugin.

plugin :determine_mime_type, analyzer: ->(io, analyzers) do
  analyzers[:mimemagic].call(io) || analyzers[:file].call(io)
  • The built-in analyzers can now be used when implementing a custom dimensions analyzer in store_dimensions plugin.

plugin :store_dimensions, analyzer: ->(io, analyzers) do
  dimensions = analyzers[:filemagic].call(io)
  dimensions || MiniMagick::Image.new(io).dimensions
  • Shrine::Attacher#cache!, #store! and #delete! are now public (they are wrappers for Shrine#upload and Shrine#delete with context passed in).

  • Shrine::Attacher#_delete has been added as a wrapper around #delete!, which the backgrounding plugin overrides and makes aynchronous. This nicely complements the Shrine::Attacher#_promote wrapper around #promote.

Other improvements

  • Shrine now prints a security warning when determine_mime_type plugin isn’t loaded.

  • Don't error in determine_mime_type with :mimemagic analyzer when MimeMagic cannot determine MIME of the file.

  • When :host is given to S3 storage, URLs will now include the query parameters, unless :public is given, just like without :host.

  • The Down version has been bumped to 2.2.0, which means the remote_url plugin now follows redirects (maximum of 2 redirects by default).

  • The Shrine::Attacher#_promote and Shrine::Attacher#promote now have the same generalized method signature.

  • The restore_cached_data plugin functionality won't get triggered anymore when form is submitted with already saved cached attachmnet (e.g. due to background processing).

  • The restore_cached_data plugin now doesn't check anymore if the cached file exists (which saves an HTTP request with remote storages).

  • The download_endpoint now makes only one HTTP request when downloading files from remote storages.

  • The activerecord plugin now allows attachment modules to be included in non-ActiveRecord models.

  • The sequel plugin now allows attachment modules to be included in non-Sequel models.

  • Plugin options are now persisted when reapplying plugins.

Shrine.plugin :download_endpoint, storages: [:store], prefix: "/downloads", disposition: "inline"

class DocumentUploader < Shrine
  # all other options above will be persisted
  plugin :download_endpoint, disposition: "attachment"
  • The :include_error has been removed from remote_url plugin, the error will now be included in the second argument depending on lambda's arity.

  • The dynamic_storage plugin doesn't cache the instantiated storages anymore, which enables use cases like storing storage definitions in the database.

  • The determine_mime_type plugin with :file analyzer now handles filenames that start with a dash ("-").

  • Shrine::Attacher now allocates less strings.