shrine 2.5.0 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9bfafd65b7f7fe8b99b1c5f93ef378bfc3dc7eac
-  data.tar.gz: 698ed63662d4394c346f5ae2946e892de53d694e
+  metadata.gz: af515b9a7c0e52d86cc58b7765dd6f894ab152e5
+  data.tar.gz: 6fa6cf185cc41cb6185538423bf144f8dd854f40
 SHA512:
-  metadata.gz: 2fcf2377c360c399342238366a1458f48f078d7b946b52af09b3e9acdbc8761e7b07270700f6a9b09b4195a43536947d6fc145da10c75667f88bd95dd9284edf
-  data.tar.gz: f293b1ba574687eae1edc8abad8fbdfbb2db2a4028470964f612ccf51a9e74a8dd810caf2e8dc6c784b9136fc6503ac168175d955404b923def1fd89eafc1a61
+  metadata.gz: f5a3a92fa19e363cffc64853ff5aafd1385d200698b6fc803606d366c487eca53f2c39c1ea3fc436613f3ed16916da1b0587a0ffa9672c6bd7175b2ec3c2000b
+  data.tar.gz: fdc756c2aea5c035348cb2f640edcfdc2773e8ea1c2ed041ae9d270c2a609e7f5500e79c352979e47f37736dec033cb9fae34c4a2ff439d60ddc673bbf3a8c0f

data/README.md

@@ -31,7 +31,7 @@ Shrine.storages = {
   store: Shrine::Storage::FileSystem.new("public", prefix: "uploads/store"), # permanent
 }
 
-Shrine.plugin :sequel # :activerecord
+Shrine.plugin :sequel # or :activerecord
 Shrine.plugin :cached_attachment_data # for forms
 Shrine.plugin :rack_file # for non-Rails apps
 ```
@@ -60,7 +60,7 @@ end
 
 ```rb
 class Photo < Sequel::Model # ActiveRecord::Base
-  include ImageUploader[:image] # adds an `image` virtual attribute
+  include ImageUploader::Attachment.new(:image) # adds an `image` virtual attribute
 end
 ```
 
@@ -265,9 +265,9 @@ Shrine.plugin :sequel # :activerecord
 
 ```rb
 class Photo < Sequel::Model # ActiveRecord::Base
-  include ImageUploader[:image]                 #
-  include ImageUploader.attachment(:image)      # these are all equivalent
   include ImageUploader::Attachment.new(:image) #
+  include ImageUploader.attachment(:image)      # these are all equivalent
+  include ImageUploader[:image]                 #
 end
 ```
 
@@ -292,13 +292,13 @@ photo.image #=> nil
 photo.image = File.open("waterfall.jpg")
 photo.image      #=> #<Shrine::UploadedFile @data={...}>
 photo.image_url  #=> "/uploads/cache/0sdfllasfi842.jpg"
-photo.image_data #=> '{"storage":"cache","id":"0sdfllasfi842.jpg","metadata":{...}}'
+photo.image_data #=> '{"id":"0sdfllasfi842.jpg","storage":"cache","metadata":{...}}'
 
 # the cached file is promoted to permanent storage and saved to `image_data` column
 photo.save
 photo.image      #=> #<Shrine::UploadedFile @data={...}>
 photo.image_url  #=> "/uploads/store/l02kladf8jlda.jpg"
-photo.image_data #=> '{"storage":"store","id":"l02kladf8jlda.jpg","metadata":{...}}'
+photo.image_data #=> '{"id":"l02kladf8jlda.jpg","storage":"store","metadata":{...}}'
 
 # the attached file is deleted with the record
 photo.destroy
@@ -322,8 +322,8 @@ uploads], via the hidden form field.
 
 ```rb
 photo.image = '{
-  "storage": "cache",
   "id": "9260ea09d8effd.jpg",
+  "storage": "cache",
   "metadata": { ... }
 }'
 ```
@@ -486,7 +486,7 @@ class ImageUploader < Shrine
   plugin :processing
 
   process(:store) do |io, context|
-    resize_to_limit!(io.download, 800, 800)
+    resize_to_limit!(io.download, 800, 800) { |cmd| cmd.auto_orient } # orient rotated images
   end
 end
 ```
@@ -524,7 +524,7 @@ class ImageUploader < Shrine
   process(:store) do |io, context|
     original = io.download
 
-    size_800 = resize_to_limit!(original, 800, 800)
+    size_800 = resize_to_limit!(original, 800, 800) { |cmd| cmd.auto_orient } # orient rotated images
     size_500 = resize_to_limit(size_800,  500, 500)
     size_300 = resize_to_limit(size_500,  300, 300)
 
@@ -639,7 +639,7 @@ class DocumentUploader < Shrine
 
   Attacher.validate do
     validate_max_size 5*1024*1024, message: "is too large (max is 5 MB)"
-    validate_mime_type_inclusion ["application/pdf"]
+    validate_mime_type_inclusion %w[application/pdf]
   end
 end
 ```
@@ -744,9 +744,10 @@ The above setup will provide the following endpoints:
 * `GET /images/cache/presign` - for direct uploads to external service (e.g. Amazon S3)
 
 Now when the user selects a file, the client can immediately start uploading
-the file asynchronously using one of these endpoints. For JavaScript you can
-use generic file upload libraries like [jQuery-File-Upload], [Dropzone] or
-[FineUploader].
+the file asynchronously using one of these endpoints. The JSON data of the
+uploaded file can then be written to the hidden attachment field, and submitted
+instead of the file. For JavaScript you can use generic file upload libraries
+like [jQuery-File-Upload], [Dropzone] or [FineUploader].
 
 See the [direct_upload] plugin documentation and [Direct Uploads to S3][direct uploads]
 guide for more details, as well as the [Roda][roda_demo] and

data/doc/attacher.md

@@ -7,7 +7,7 @@ fields to the form just works.
 
 ```rb
 class Photo < Sequel::Model
-  include ImageUploader[:image]
+  include ImageUploader::Attachment.new(:image)
 end
 ```
 
@@ -59,8 +59,8 @@ attacher.assign(io)
 
 # writes the given cached file to the data column
 attacher.assign '{
-  "storage": "cache",
   "id": "9260ea09d8effd.jpg",
+  "storage": "cache",
   "metadata": { ... }
 }'
 ```
@@ -87,14 +87,15 @@ The `#read` method will just return the value of the underlying
 `<attachment>_data` attribute.
 
 ```rb
-attacher.read #=> '{"storage":"cache","id":"dsg024lfs.jpg",...}'
+attacher.read #=> '{"id":"dsg024lfs.jpg","storage":"cache","metadata":{...}}'
 ```
 
 In general you can use `#uploaded_file` to contruct a `Shrine::UploadedFile`
 from a JSON string.
 
 ```rb
-attacher.uploaded_file('{"storage":"cache","id":"dsg024lfs.jpg",...}') #=> #<Shrine::UploadedFile>
+attachment_data = '{"id":"dsg024lfs.jpg","storage":"cache","metadata":{...}}'
+attacher.uploaded_file(attachment_data) #=> #<Shrine::UploadedFile>
 ```
 
 ## URL
@@ -133,8 +134,8 @@ to permanent storage after the record is saved. You can use `#finalize` for
 that, since that will also automatically delete any previously attached files.
 
 ```rb
-# We run the finalization only if a new file was attached
-attacher.finalize if attacher.attached?
+# Replaces previous attachment and replaces new
+attacher.finalize
 ```
 
 This is normally automatically added to a callback by the ORM plugin when going

data/doc/carrierwave.md

@@ -146,7 +146,7 @@ class ImageUploader < Shrine
   plugin :validation_helpers
 
   Attacher.validate do
-    validate_extension_inclusion [/jpe?g/, "gif", "png"]
+    validate_extension_inclusion %w[jpg jpeg gif png]
     validate_mime_type_inclusion %w[image/jpeg image/gif image/png]
     validate_max_size 10*1024*1024 unless record.admin?
   end
@@ -176,7 +176,7 @@ end
 ```
 ```rb
 class Photo < ActiveRecord::Base
-  include ImageUploader[:avatar]
+  include ImageUploader::Attachment.new(:avatar)
 end
 ```
 
@@ -248,6 +248,7 @@ attachments:
 
 ```rb
 require "fastimage"
+require "mime/types"
 
 module CarrierwaveShrineSynchronization
   def self.included(model)
@@ -285,8 +286,8 @@ module CarrierwaveShrineSynchronization
     path = uploader.store_path(read_attribute(uploader.mounted_as))
 
     size   = uploader.file.size if changes.key?(uploader.mounted_as)
-    size ||= FastImage.new(uploader.url).content_length
-    size ||= File.size(File.join(uploader.root, path))
+    size ||= FastImage.new(uploader.url).content_length # OPTIONAL (makes an HTTP request)
+    size ||= File.size(File.join(uploader.root, path)) if File.exist?(path)
     filename = File.basename(path)
     mime_type = MIME::Types.type_for(path).first.to_s.presence
 
@@ -451,24 +452,24 @@ class ImageUploader < Shrine
   plugin :validation_helpers
 
   Attacher.validate do
-    validate_extension_inclusion [/jpe?g/, 'png'] # whitelist
-    validate_extension_exclusion ['php']          # blacklist
+    validate_extension_inclusion %w[jpg jpeg png] # whitelist
+    validate_extension_exclusion %w[php]          # blacklist
   end
 end
 ```
 
-#### `#blacklist_mime_type_pattern`, `#whitelist_mime_type_pattern`
+#### `#blacklist_mime_type_pattern`, `#whitelist_mime_type_pattern`, `#content_type_whitelist`, `#content_type_blacklist`
 
 In Shrine MIME type whitelisting/blacklisting is part of validations, and is
-provided by the `validation_helpers` plugin:
+provided by the `validation_helpers` plugin, though it doesn't support regexes:
 
 ```rb
 class ImageUploader < Shrine
   plugin :validation_helpers
 
   Attacher.validate do
-    validate_mime_type_inclusion [/image/] # whitelist
-    validate_mime_type_exclusion [/video/] # blacklist
+    validate_mime_type_inclusion %w[image/jpeg image/png] # whitelist
+    validate_mime_type_exclusion %w[text/x-php]           # blacklist
   end
 end
 ```
@@ -511,7 +512,7 @@ Shrine.plugin :sequel
 ```
 ```rb
 class User < Sequel::Model
-  include ImageUploader[:avatar]
+  include ImageUploader::Attachment.new(:avatar)
 end
 ```
 
@@ -554,18 +555,19 @@ argument (`user.avatar_url(:thumb)`).
 
 #### `#<attachment>_cache`
 
-Shrine doesn't provide this method, instead it expects to recieve the
-attachment through the accessor, you can assign it `<attachment>_data`:
+Shrine has the `cached_attachment_data` plugin, which gives model a reader method
+that you can use for retaining the cached file:
 
+```rb
+Shrine.plugin :cached_attachment_data
+```
 ```erb
 <%= form_for @user do |f| %>
-  <%= f.hidden_field :avatar, value: @user.avatar_data %>
+  <%= f.hidden_field :avatar, value: @user.cached_avatar_data %>
   <%= f.file_field :avatar %>
 <% end %>
 ```
 
-You might also want to look at the `cached_attachment_data` plugin.
-
 #### `#remote_<attachment>_url`
 
 In Shrine this method is provided by the `remote_url` plugin.
@@ -623,7 +625,7 @@ class ImageUploader < Shrine
     # Evaluated inside an instance of Shrine::Attacher.
     if record.guest?
       validate_max_size 2*1024*1024, message: "is too large (max is 2 MB)"
-      validate_mime_type_inclusion ["image/jpg", "image/png", "image/gif"]
+      validate_mime_type_inclusion %w[image/jpg image/png image/gif]
     end
   end
 end

data/doc/design.md

@@ -187,7 +187,7 @@ We can include this module to a model:
 
 ```rb
 class Photo
-  include Shrine[:image]
+  include Shrine::Attachment.new(:image)
 end
 ```
 ```rb

data/doc/direct_s3.md

@@ -13,11 +13,14 @@ beneficial for several use cases:
 * With multiple servers it's generally not possible to cache files to the disk,
   unless you're using a distibuted filesystem that's shared between servers.
 
-* Heroku restricts file uploads to disk, allowing you to save files only in
-  the temporary folder, which gets wiped out between deploys.
+* On Heroku any uploaded files that aren't part of version control don't persist,
+  they get removed each time you do a new deploy or when the dyno automatically
+  changes the location.
 
-* Heroku has a 30-second request limit, so if the client has a slow connection
-  and/or your files are larger, uploads to your app can easily hit that limit.
+* If your request workers have a timeout configured or you're using Heroku,
+  uploading a large files to S3 or any external service inside the
+  request-response lifecycle might not be able to finish before the request
+  times out.
 
 You can start by setting both temporary and permanent storage to S3 with
 different prefixes (or even buckets):
@@ -108,7 +111,7 @@ necessary request parameters:
 {
   "url" => "https://my-bucket.s3-eu-west-1.amazonaws.com",
   "fields" => {
-    "key" => "b7d575850ba61b44c8a9ff889dfdb14d88cdc25f8dd121004c8",
+    "key" => "cache/b7d575850ba61b44c8a9ff889dfdb14d88cdc25f8dd121004c8",
     "policy" => "eyJleHBpcmF0aW9uIjoiMjAxNS0QwMToxMToyOVoiLCJjb25kaXRpb25zIjpbeyJidWNrZXQiOiJzaHJpbmUtdGVzdGluZyJ9LHsia2V5IjoiYjdkNTc1ODUwYmE2MWI0NGU3Y2M4YTliZmY4OGU5ZGZkYjE2NTQ0ZDk4OGNkYzI1ZjhkZDEyMTAwNGM4In0seyJ4LWFtei1jcmVkZW50aWFsIjoiQUtJQUlKRjU1VE1aWlk0NVVUNlEvMjAxNTEwMjQvZXUtd2VzdC0xL3MzL2F3czRfcmVxdWVzdCJ9LHsieC1hbXotYWxnb3JpdGhtIjoiQVdTNC1ITUFDLVNIQTI1NiJ9LHsieC1hbXotZGF0ZSI6IjIwMTUxMDI0VDAwMTEyOVoifV19",
     "x-amz-credential" => "AKIAIJF55TMZYT6Q/20151024/eu-west-1/s3/aws4_request",
     "x-amz-algorithm" => "AWS4-HMAC-SHA256",

data/doc/multiple_files.md

@@ -60,7 +60,7 @@ In our new model we can create a Shrine attachment attribute:
 
 ```rb
 class Photo < Sequel::Model
-  include ImageUploader[:image]
+  include ImageUploader::Attachment.new(:image)
 end
 ```
 
@@ -96,9 +96,9 @@ After each upload finishes, you can generate a nested hash for the new
 associated record, and write the uploaded file JSON to the attachment field:
 
 ```rb
-album[photos_attributes][0][image] = '{"storage":"cache","id":"38k25.jpg","metadata":{...}}'
-album[photos_attributes][1][image] = '{"storage":"cache","id":"sg0fg.jpg","metadata":{...}}'
-album[photos_attributes][2][image] = '{"storage":"cache","id":"041jd.jpg","metadata":{...}}'
+album[photos_attributes][0][image] = '{"id":"38k25.jpg","storage":"cache","metadata":{...}}'
+album[photos_attributes][1][image] = '{"id":"sg0fg.jpg","storage":"cache","metadata":{...}}'
+album[photos_attributes][2][image] = '{"id":"041jd.jpg","storage":"cache","metadata":{...}}'
 ```
 
 Once you submit this to the app, the ORM's nested attributes behaviour will

data/doc/paperclip.md

@@ -64,7 +64,7 @@ class ImageUploader < Shrine
 end
 
 class Photo < ActiveRecord::Base
-  include ImageUploader[:image]
+  include ImageUploader::Attachment.new(:image)
 end
 ```
 
@@ -204,7 +204,7 @@ gives your models similar set of methods that Paperclip gives:
 
 ```rb
 class Photo < Sequel::Model
-  include ImageUploader[:image]
+  include ImageUploader::Attachment.new(:image)
 end
 ```
 
@@ -286,6 +286,7 @@ attachments:
 
 ```rb
 require "fastimage"
+require "mime/types"
 
 module PaperclipShrineSynchronization
   def self.included(model)
@@ -342,8 +343,8 @@ module PaperclipShrineSynchronization
     file = attachment.instance_variable_get("@queued_for_write")[style.name]
 
     size   = file.size if file
-    size ||= FastImage.new(url).content_length
-    size ||= File.size(path)
+    size ||= FastImage.new(url).content_length # OPTIONAL (makes an HTTP request)
+    size ||= File.size(path) if File.exist?(path)
     filename = File.basename(path)
     mime_type = MIME::Types.type_for(path).first.to_s.presence
 
@@ -368,7 +369,7 @@ end
 
 After you deploy this code, the `image_data` column should now be successfully
 synchronized with new attachments.  Next step is to run a script which writes
-all existing CarrierWave attachments to `image_data`:
+all existing Paperclip attachments to `image_data`:
 
 ```rb
 Photo.find_each do |photo|
@@ -393,7 +394,7 @@ an attachment module:
 
 ```rb
 class User < Sequel::Model
-  include ImageUploader[:avatar] # adds `avatar`, `avatar=` and `avatar_url` methods
+  include ImageUploader::Attachment.new(:avatar) # adds `avatar`, `avatar=` and `avatar_url` methods
 end
 ```
 

data/doc/refile.md

@@ -118,7 +118,7 @@ class ImageUploader < Shrine
 end
 
 class Photo < Sequel::Model
-  include ImageUploader[:image]
+  include ImageUploader::Attachment.new(:image)
 end
 ```
 
@@ -371,7 +371,7 @@ of an uploader:
 
 ```rb
 class User
-  include ImageUploader[:avatar]
+  include ImageUploader::Attachment.new(:avatar)
 end
 ```
 
@@ -385,8 +385,8 @@ class ImageUploader < Shrine
   plugin :validation_helpers
 
   Attacher.validate do
-    validate_extension_inclusion [/jpe?g/, "png"]
-    validate_mime_type_inclusion ["image/jpeg", "image/png"]
+    validate_extension_inclusion %w[jpg jpeg png]
+    validate_mime_type_inclusion %w[image/jpeg image/png]
   end
 end
 ```
@@ -410,6 +410,68 @@ end
 
 No equivalent currently exists in Shrine.
 
+### `accepts_attachments_for`
+
+No equivalent in Shrine, but take a look at the "[Multiple Files]" guide.
+
+### Form helpers
+
+#### `attachment_field`
+
+The following Refile code
+
+```erb
+<%= form_for @user do |form| %>
+  <%= form.attachment_field :profile_image %>
+<% end %>
+```
+
+is equivalent to the following Shrine code
+
+```rb
+Shrine.plugin :cached_attachment_data
+```
+```erb
+<%= form_for @user do |form| %>
+  <%= form.hidden_field :profile_image, value: @user.cached_profile_image_data %>
+  <%= form.file_field :profile_image %>
+<% end %>
+```
+
+### Model methods
+
+#### `remove_<attachment>`
+
+Shrine comes with a `remove_attachment` plugin which adds the same
+`#remove_<attachment>` method to the model.
+
+```rb
+Shrine.plugin :remove_attachment
+```
+```erb
+<%= form_for @user do |form| %>
+  <%= form.hidden_field :profile_image, value: @user.cached_profile_image_data %>
+  <%= form.file_field :profile_image %>
+  <%= form.check_box :remove_profile_image %>
+<% end %>
+```
+
+#### `remote_<attachment>_url`
+
+Shrine comes with a `remote_url` plugin which adds the same
+`#<attachment>_remote_url` method to the model.
+
+```rb
+Shrine.plugin :remote_url
+```
+```erb
+<%= form_for @user do |form| %>
+  <%= form.hidden_field :profile_image, value: @user.cached_profile_image_data %>
+  <%= form.file_field :profile_image %>
+  <%= form.text_field :profile_image_remote_url %>
+<% end %>
+```
+
 [shrine-cloudinary]: https://github.com/janko-m/shrine-cloudinary
 [shrine-imgix]: https://github.com/janko-m/shrine-imgix
 [shrine-uploadcare]: https://github.com/janko-m/shrine-uploadcare
@@ -418,3 +480,4 @@ No equivalent currently exists in Shrine.
 [jQuery-File-Upload]: https://github.com/blueimp/jQuery-File-Upload
 [Direct Uploads to S3]: http://shrinerb.com/rdoc/files/doc/direct_s3_md.html
 [demo app]: https://github.com/janko-m/shrine/tree/master/demo
+[Multiple Files]: http://shrinerb.com/rdoc/files/doc/multiple_files_md.html