shrine 1.0.0 → 1.1.0

data/doc/paperclip.md

@@ -22,10 +22,6 @@ class ImageUploader < Shrine
   def process(io, context)
     # processing
   end
-
-  def default_url(context)
-    # default URL
-  end
 end
 ```
 
@@ -37,8 +33,8 @@ you can instantiate uploaders with a specific storage:
 require "shrine/storage/file_system"
 
 Shrine.storages = {
-  cache: Shrine::Storage::FileSystem.new("public", subdirectory: "uploads/cache"),
-  store: Shrine::Storage::FileSystem.new("public", subdirectory: "uploads/store"),
+  cache: Shrine::Storage::FileSystem.new("public", prefix: "uploads/cache"),
+  store: Shrine::Storage::FileSystem.new("public", prefix: "uploads/store"),
 }
 ```
 ```rb
@@ -74,9 +70,9 @@ end
 #### Regenerating versions
 
 Shrine doesn't have a built-in way of regenerating versions, because that's
-very individual and depends on what versions you want regenerated, what ORM
-are you using, how many records there are in your database etc. But I wrote
-a "[Regenerating versions]" guide that should give you useful guidelines.
+very individual and depends on what versions you want regenerated, what ORM are
+you using, how many records there are in your database etc. The [Regenerating
+versions] guide provides some useful tips on this task.
 
 ### Logging
 
@@ -208,8 +204,8 @@ which you have to register:
 require "shrine/storage/file_system"
 
 Shrine.storages = {
-  cache: Shrine::Storage::FileSystem.new("public", subdirectory: "uploads/cache"),
-  store: Shrine::Storage::FileSystem.new("public", subdirectory: "uploads/store"),
+  cache: Shrine::Storage::FileSystem.new("public", prefix: "uploads/cache"),
+  store: Shrine::Storage::FileSystem.new("public", prefix: "uploads/store"),
 }
 ```
 
@@ -222,13 +218,12 @@ As explained in the "Processing" section, processing is done by overriding the
 
 #### `:default_url`
 
-In Shrine you achieve default URLs by defining the instance method on the
-uploader:
+For default URLs you can use the `default_url` plugin:
 
 ```rb
 class ImageUploader < Shrine
-  def default_url(context)
-    "/placeholders/missing-image.png"
+  plugin :default_url do |context|
+    "/attachments/#{context[:name]}/default.jpg"
   end
 end
 ```
@@ -301,8 +296,8 @@ user.avatar.id #=> "users/342/avatar/398543qjfdsf.jpg"
 
 #### `#reprocess!`
 
-Shrine doesn't have an equivalent to this, but there is a "[Regenerating
-versions]" that should give you some useful guidelines.
+Shrine doesn't have an equivalent to this, but the [Regenerating versions]
+guide provides some useful tips on how to do this.
 
 [file]: http://linux.die.net/man/1/file
 [Regenerating versions]: http://shrinerb.com/rdoc/files/doc/regenerating_versions_md.html

data/doc/refile.md

@@ -0,0 +1,338 @@
+# Shrine for Refile Users
+
+This guide is aimed at helping Refile users transition to Shrine. We will first
+generally mention what are the key differences, and afterwards we will give a
+complete reference of Refile's interface and note what is the equivalent in
+Shrine.
+
+## Uploaders
+
+Shrine has the concept of storages very similar to Refile's backends. However,
+while in Refile you usually work with storages directly, in Shrine you use
+*uploaders* which act as wrappers around storages, and they are subclasses of
+`Shrine`:
+
+```rb
+require "shrine/storage/file_system"
+require "shrine/storage/s3"
+
+Shrine.storages = {
+  cache: Shrine::Storage::FileSystem.new(*args),
+  store: Shrine::Storage::S3.new(*args),
+}
+```
+```rb
+class ImageUploader < Shrine
+  # uploading logic
+end
+```
+
+While in Refile you configure attachments by passing options to `.attachment`,
+in Shrine you define all your uploading logic inside uploaders, and then
+generate an attacment module with that uploader which is included into the
+model:
+
+```rb
+class ImageUploader < Shrine
+  plugin :store_dimensions
+  plugin :determine_mime_type
+  plugin :keep_files, destroyed: true
+end
+```
+```rb
+class User
+  include ImageUploader[:avatar] # requires "avatar_data" column
+end
+```
+
+Unlike Refile which has just a few options of configuring attachments, Shrine
+has a very rich arsenal of features via plugins, and allows you to share your
+uploading logic between uploaders through inheritance.
+
+### ORMs
+
+In Refile you extend the model with an Attachment module specific to the ORM
+you're using. In Shrine you load the appropriate ORM plugin:
+
+```rb
+Shrine.plugin :sequel # or :activerecord
+```
+```rb
+class Photo < Sequel::Model
+  include ImageUploader[:image]
+end
+```
+
+These integrations work much like Refile; on assignment the file is cached,
+and on saving the record file is moved from cache to store. Shrine doesn't
+provide form helpers for Rails, because it's so easy to do it yourself:
+
+```erb
+<%= form_for @photo do |f| %>
+  <%= f.hidden_field :image, value: @photo.image_data %>
+  <%= f.file_field :image %>
+<% end %>
+```
+
+### URLs
+
+To get file URLs, in Shrine you just call `#url` on the file:
+
+```rb
+@photo.image.url
+@photo.image_url # returns nil if attachment is missing
+```
+
+If you're using storages which don't expose files over URL, or you want to
+secure your downloads, you can use the `download_endpoint` plugin.
+
+### Metadata
+
+While in Refile you're required to have a separate column for each metadata you
+want to save (filename, size, content type), in Shrine all of the metadata are
+stored in a single column (for "avatar" it's `avatar_data` column) as JSON.
+
+```rb
+user.avatar_data #=> "{\"storage\":\"cache\",\"id\":\"9260ea09d8effd.jpg\",\"metadata\":{...}}"
+```
+
+By default Shrine stores "filename", "size" and "mime_type" metadata, but you
+can also store image dimensions by loading the `store_dimensions` plugin.
+
+### Processing
+
+One of the key differences between Refile and Shrine is that in Refile you do
+processing on-the-fly (like Dragonfly), while in Shrine you do your processing
+on upload (like CarrierWave and Paperclip). However, there are storages which
+you can use which support on-the-fly processing, like [shrine-cloudinary] or
+[shrine-imgix].
+
+In Shrine you do processing by overriding the `#process` method on your
+uploader (for images you can use the [image_processing] gem):
+
+```rb
+require "image_processing/mini_magick"
+
+class ImageUploader < Shrine
+  include ImageProcessing::MiniMagick
+
+  def process(io, context)
+    case context[:phase]
+    when :store
+      resize_to_fit!(io.download, 700, 700)
+    end
+  end
+end
+```
+
+### Validations
+
+While in Refile you can do extension, mime type and filesize validation by
+passing options to `.attachment`, in Shrine you do this logic instance level,
+with the help of the `validation_helpers` plugin:
+
+```rb
+class ImageUploader < Shrine
+  plugin :validation_helpers
+
+  Attacher.validate do
+    validate_mime_type_inclusion ["image/jpeg", "image/png", "image/gif"]
+  end
+end
+```
+
+### Direct uploads
+
+Shrine borrows Refile's idea of direct uploads, and ships with a
+`direct_upload` plugin which provides the endpoint that you can mount:
+
+```rb
+class ImageUploader < Shrine
+  plugin :direct_upload
+end
+```
+```rb
+# config/routes.rb
+Rails.application.routes.draw do
+  mount ImageUploader::UploadEndpoint => "/attachments/images"
+end
+```
+```rb
+# POST /attachments/images/cache/avatar
+{
+  "id": "43kewit94.jpg",
+  "storage": "cache",
+  "metadata": {
+    "size": 384393,
+    "filename": "nature.jpg",
+    "mime_type": "image/jpeg"
+  }
+}
+```
+
+Unlike Refile, Shrine doesn't ship with a JavaScript script which you can just
+include to make it work. Instead, you're expected to use one of the many
+excellent JavaScript libraries for generic file uploads, for example
+[jQuery-File-Upload].
+
+#### Presigned S3 uploads
+
+The `direct_upload` plugin also provides an endpoint for getting S3 presigns,
+you just need to pass the `presign: true` option. In the same way as with regular
+direct uploads, you can use a generic JavaScript file upload library. For the
+details read the [Direct Uploads to S3] guide.
+
+### Multiple uploads
+
+Shrine doesn't have a built-in solution for accepting multiple uploads, but
+it's actually very easy to do manually, see the [example app] on how you can do
+multiple uploads directly to S3.
+
+## Refile to Shrine direct mapping
+
+### `Refile`
+
+#### `.cache`, `.store`, `.backends`
+
+Shrine calles these "storages", and it doesn't have special accessors for
+`:cache` and `:store`:
+
+```rb
+Shrine.storages = {
+  cache: Shrine::Storage::Foo.new(*args),
+  store: Shrine::Storage::Bar.new(*args),
+}
+```
+
+#### `.app`, `.mount_point`, `.automount`
+
+The `direct_upload` plugin provides a subset of Refile's app's functionality,
+and you have to mount it in your framework's router:
+
+```rb
+# config/routes.rb
+Rails.application.routes.draw do
+  # adds `POST /attachments/images/:storage/:name`
+  mount ImageUploader::UploadEndpoint => "/attachments/images"
+end
+```
+
+#### `.allow_uploads_to`
+
+```rb
+Shrine.plugin :direct_upload, storages: [:cache]
+```
+
+#### `.logger`
+
+```rb
+Shrine.plugin :logging
+```
+
+#### `.processors`, `.processor`
+
+In Shrine processing is done by overriding the `#process` method in your
+uploader:
+
+```rb
+class MyUploader < Shrine
+  def process(io, context)
+    # ...
+  end
+end
+```
+
+#### `.types`
+
+In Shrine validations are done by calling `.validate` on the attacher class:
+
+```rb
+class MyUploader < Shrine
+  plugin :validation_helpers
+
+  Attacher.validate do
+    validate_max_size 5*1024*1024
+  end
+end
+```
+
+#### `.extract_filename`, `.extract_content_type`
+
+In Shrine equivalents are (private) methods `Shrine#extract_filename` and
+`Shrine#extract_mime_type`.
+
+#### `.app_url`
+
+You should use your framework to generate the URL to your mounted direct
+enpdoint.
+
+#### `.attachment_url`, `.file_url`
+
+You can call `#url` on the uploaded file, or `#<name>_url` on the model.
+Additionally you can use the `download_endpoint` plugin.
+
+#### `.upload_url`, `.attachment_upload_url`, `.presign_url`, `.attachment_presign_url`
+
+These should be generated directly by you, it depends on where you've mounted
+the direct endpoint.
+
+#### `.host`, `.cdn_host`, `.app_host`, `.allow_downloads_from`, `allow_origin`, `.content_max_age`
+
+Not needed since Shrine doesn't offer on-the-fly processing.
+
+#### `.secret_key`, `.token`, `.valid_token?`
+
+Not needed since Shrine doesn't offer on-the-fly processing.
+
+### `attachment`
+
+Shrine's equivalent to calling the attachment is including an attachment module
+of an uploader:
+
+```rb
+class User
+  include ImageUploader[:avatar]
+end
+```
+
+#### `:extension`, `:content_type`, `:type`
+
+In Shrine validations are done instance-level inside the uploader, most
+commonly with the `validation_helpers` plugin:
+
+```rb
+class ImageUploader < Shrine
+  plugin :validation_helpers
+
+  Attacher.validate do
+    validate_extension_inclusion [/jpe?g/, "png"]
+    validate_mime_type_inclusion [/image/jpeg/, "image/png"]
+  end
+end
+```
+
+#### `:cache`, `:store`
+
+Shrine provides a `default_storage` plugin for setting custom storages on the
+uploader:
+
+```rb
+Shrine.storages[:custom_cache] = Shrine::Storage::Foo.new(*args)
+Shrine.storages[:custom_store] = Shrine::Storage::Bar.new(*args)
+```
+```rb
+class ImageUploader < Shrine
+  plugin :default_storage, cache: :custom_cache, store: :custom_store
+end
+```
+
+#### `:raise_errors`
+
+No equivalent currently exists in Shrine.
+
+[shrine-cloudinary]: https://github.com/janko-m/shrine-cloudinary
+[shrine-imgix]: https://github.com/janko-m/shrine-imgix
+[image_processing]: https://github.com/janko-m/image_processing
+[jQuery-File-Upload]: https://github.com/blueimp/jQuery-File-Upload
+[Direct Uploads to S3]: http://shrinerb.com/rdoc/files/doc/direct_s3_md.html
+[example app]: https://github.com/janko-m/shrine-example

data/doc/regenerating_versions.md

@@ -1,4 +1,4 @@
-# Regenerating versions
+# Reprocessing Versions
 
 While your app is serving uploads in production, you may realize that you want
 to change how your attachment's versions are generated. This means that, in
@@ -6,15 +6,66 @@ addition to changing you processing code, you also need to reprocess the
 existing attachments. This guide is aimed to help doing this migration with
 zero downtime and no unused files left in the main storage.
 
-## Regenerating a specific version
+## Adding versions
+
+Most common scenario is when initially you're not doing any processing, but
+later decide that you want to generate versions. First you need to update your
+code to generate versions, and you also need to change your views to use those
+versions:
+
+```rb
+class ImageUploader < Shrine
+  plugin :versions, names: [:original, :thumb]
+
+  def process(io, context)
+    case context[:phase]
+    when :store
+      thumb = process_thumb(io.download) # replace with actual processing method
+      {original: io, thumb: thumb}
+    end
+  end
+end
+```
+```rb
+# In your views add the version name to all <attachment>_url calls.
+user.avatar_url(:thumb)
+```
+
+Note that you should deploy both of these changes at once, because the
+`<attachment>_url` method will fail if there are versions generated but no
+version name was passed in. If a version name was passed in but versions aren't
+generated yet (which will be the case here), it will just return the
+unprocessed file URL.
+
+Afterwards you should run a script which reprocesses the versions for existing
+files:
+
+```rb
+Shrine.plugin :migration_helpers # before the model is loaded
+```
+```rb
+User.paged_each do |user|
+  user.update_avatar do |avatar|
+    unless avatar.is_a?(Hash)
+      file = some_processing(avatar.download)
+      thumb = user.avatar_store.upload(file, {record: user, name: :avatar, version: :thumb})
+      {original: avatar, thumb: thumb}
+    end
+  end
+end
+```
+
+## Reprocessing a single version
 
 The simplest scenario is where you need to regenerate an existing version.
 First you need to change and deploy your updated processing code, and
 afterwards you can run a script like this on your production database:
 
 ```rb
-Shrine.plugin :migration_helpers
+Shrine.plugin :migration_helpers # before the model is loaded
+```
 
+```rb
 User.paged_each do |user|
   user.update_avatar do |avatar|
     thumb = some_processing(avatar[:original].download)
@@ -47,15 +98,17 @@ After you've deployed this change, you should run a script that will generate
 the new version for all existing records:
 
 ```rb
-Shrine.plugin :migration_helpers
+Shrine.plugin :migration_helpers # before the model is loaded
+```
 
+```rb
 User.paged_each do |user|
   user.update_avatar do |avatar|
-    unless new = avatar[:new]
+    unless avatar[:new]
       file = some_processing(avatar[:original].download, *args)
-      new = user.avatar_store.upload(file)
+      new = user.avatar_store.upload(file, {record: user, name: :avatar, version: :new})
+      avatar.merge(new: new)
     end
-    avatar.merge(new: new)
   end
 end
 ```
@@ -72,29 +125,40 @@ not to use the new version, and deploy that code. After you've done that, you
 can run a script which removes that version:
 
 ```rb
-Shrine.plugin :migration_helpers
+Shrine.plugin :migration_helpers # before the model is loaded
+```
+
+```rb
+removed_versions = []
 
 User.paged_each do |user|
   user.update_avatar do |avatar|
     old_version = avatar.delete(:old_version)
-    old_version.delete if old_version
+    removed_versions << old_version if old_version
     avatar
   end
 end
+
+if removed_versions.any?
+  uploader = removed_versions.first.uploader
+  uploader.delete(removed_versions)
+end
 ```
 
 After the script has finished, you should be able to safely remove the version
 name from the list.
 
-## Regenerating all versions
+## Reprocessing all versions
 
 If you made a lot of changes to versions, it might make sense to simply
 regenerate all versions. After you've deployed the change in processing, you
 can run a script which updates existing records:
 
 ```rb
-Shrine.plugin :migration_helpers
+Shrine.plugin :migration_helpers # before the model is loaded
+```
 
+```rb
 User.paged_each do |user|
   if user.avatar && user.avatar_store.uploaded?(user.avatar)
     user.update(avatar: user.avatar[:original])