shrine 3.0.0 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c4cf7d403c331ddb66dc01ea8e9210a827065c08fd206d89be8aa1dac24775b
-  data.tar.gz: 9a1b304b4fd4c9640f1bda7904c6402490af9456c896d69bd815fcf8f34ea1e2
+  metadata.gz: 0b327565465d4140206d1f88433647e7959b6c56ecbdea7d433f1aa5eb01825d
+  data.tar.gz: c19fb7f15299b1d061325f8f83e790f44481456fbc9730d4a909923193dde1a3
 SHA512:
-  metadata.gz: 0eeb00bf6fa625a51f993bda58e0d016b6c85d0831f9be4ce6f914c720054f03684f83617b963f894b51216b96f9ad42eddbcfcf4f717521123d474397c8e3d6
-  data.tar.gz: dd07bd03ea16adf721fdbd8568aa33f1f47a36a32ac5c82537721492c12a21e1b169ebbf8b2872fcb4c938f68bbbde9a1aff6b447fee0a50663898c105e2c62e
+  metadata.gz: 897bbe8787b3a1f7e59db3e6beebbc91b32ec5e4c19cd832029e05205425c12d837bf8475f21949c23a6c805504da45a0937de0d3dc9f50d3d35921b5f6a7901
+  data.tar.gz: 995b0ada0e5bdb2c4e198304d913f6cfe22d8814328d58bf559490ea572ac3d5555f3eb15fce898ae423ff54f76ba3bcbbeb7f6e05470ddca8acee37ee675455

data/CHANGELOG.md

@@ -1,4 +1,10 @@
-## 3.0.0 (14-10-2019)
+## 3.0.1 (2019-10-17) [[release notes]](https://shrinerb.com/docs/release_notes/3.0.1)
+
+* `metadata_attributes` – Fix exception being raised when there is no attached file (@janko)
+
+* `core` – Simplify `UploadedFile#inspect` output (@janko)
+
+## 3.0.0 (2019-10-14) [[release notes]](https://shrinerb.com/docs/release_notes/3.0.0)
 
 * `derivation_endpoint` – Pass `action: :derivation` when uploading derivation results (@janko)
 
@@ -230,6 +236,8 @@
 
 * `core` – Add `Attacher#data` and `Attacher.from_data` for dumping to and loading from a Hash (@janko)
 
+* `core` – Change `Attacher#assign` to raise exception when non-cached file is assigned (@janko)
+
 * `core` – Enable `Attacher#assign` to accept cached file data as a Hash (@janko)
 
 * `core` – Add `Attacher#file` alias for `Attacher#get` (@janko)
@@ -356,7 +364,7 @@
 
 * `s3` – Drop support for `aws-sdk` 2.x (@janko)
 
-## 2.19.0 (2019-07-18)
+## 2.19.0 (2019-07-18) [[release notes]](https://shrinerb.com/docs/release_notes/2.19.0)
 
 * `pretty_location` – Allow specifying a different identifier from `id` (@00dav00)
 
@@ -412,7 +420,7 @@
 
 * `core` – Allow registering storage objects under string keys (@janko)
 
-## 2.18.0 (2019-06-24)
+## 2.18.0 (2019-06-24) [[release notes]](https://shrinerb.com/docs/release_notes/2.18.0)
 
 * `core` – Add `Shrine.upload` method as a shorthand for `Shrine.new(...).upload(...)` (@janko)
 
@@ -436,7 +444,7 @@
 
 * `parsed_json` – Fix overriden `Attacher#assign` not accepting second argument (@janko)
 
-## 2.17.0 (2019-05-06)
+## 2.17.0 (2019-05-06) [[release notes]](https://shrinerb.com/docs/release_notes/2.17.0)
 
 * `data_uri` – Add `Attacher#assign_data_uri` which accepts additional `Shrine#upload` options (@janko)
 
@@ -486,7 +494,7 @@
 
 * `parsed_json` – Accepts hashes with symbols keys (@aglushkov)
 
-## 2.16.0 (2019-02-18)
+## 2.16.0 (2019-02-18) [[release notes]](https://shrinerb.com/docs/release_notes/2.16.0)
 
 * `derivation_endpoint` – Add `:upload_open_options` for download option for derivation result (@janko)
 
@@ -512,7 +520,7 @@
 
 * Fix `store_dimensions` plugin making second argument in `Shrine#extract_metadata` mandatory (@jrochkind)
 
-## 2.15.0 (2019-02-08)
+## 2.15.0 (2019-02-08) [[release notes]](https://shrinerb.com/docs/release_notes/2.15.0)
 
 * Add `derivation_endpoint` plugin for processing uploaded files on-the-fly (@janko)
 
@@ -522,7 +530,7 @@
 
 * Yield a new File object on `Shrine.with_file` when `tempfile` plugin is loaded (@janko)
 
-## 2.14.0 (2018-12-27)
+## 2.14.0 (2018-12-27) [[release notes]](https://shrinerb.com/docs/release_notes/2.14.0)
 
 * Add `tempfile` plugin for easier reusing of the same uploaded file copy on disk (@janko)
 
@@ -592,7 +600,7 @@
 
 * Use a guard raise cause for `bucket` argument in S3 for an appropriate error message (@ardecvz)
 
-## 2.13.0 (2018-11-04)
+## 2.13.0 (2018-11-04) [[release notes]](https://shrinerb.com/docs/release_notes/2.13.0)
 
 * Specify UTF-8 charset in `Content-Type` response header in `presign_endpoint` plugin (@janko)
 
@@ -624,7 +632,7 @@
 
 * In `S3#upload` deprecate using aws-sdk-s3 lower than 1.14 when uploading IO objects of unknown size (@janko)
 
-## 2.12.0 (2018-08-22)
+## 2.12.0 (2018-08-22) [[release notes]](https://shrinerb.com/docs/release_notes/2.12.0)
 
 * Ignore nil values when assigning files from a remote URL (@janko)
 
@@ -652,7 +660,7 @@
 
 * Make `UploadedFile#open` always open a new IO object and close the previous one (@janko)
 
-## 2.11.0 (2018-04-28)
+## 2.11.0 (2018-04-28) [[release notes]](https://shrinerb.com/docs/release_notes/2.11.0)
 
 * Add `Shrine.with_file` for temporarily converting an IO-like object into a file (@janko)
 
@@ -680,7 +688,7 @@
 
 * Deprecate `direct_upload` plugin in favor of `upload_endpoint` and `presign_endpoint` plugins (@janko)
 
-## 2.10.0 (2018-03-28)
+## 2.10.0 (2018-03-28) [[release notes]](https://shrinerb.com/docs/release_notes/2.10.0)
 
 * Add `:fastimage` analyzer to `determine_mime_type` plugin (@mokolabs)
 
@@ -702,7 +710,7 @@
 
 * Inherit the logger on subclassing `Shrine` and make it shared across subclasses (@hmistry)
 
-## 2.9.0 (2018-01-27)
+## 2.9.0 (2018-01-27) [[release notes]](https://shrinerb.com/docs/release_notes/2.9.0)
 
 * Support arrays of files in `versions` plugin (@janko)
 
@@ -726,7 +734,7 @@
 
 * Allow passing options to `Model#<attachment>_attacher` for overriding `Attacher` options (@janko)
 
-## 2.8.0 (2017-10-11)
+## 2.8.0 (2017-10-11) [[release notes]](https://shrinerb.com/docs/release_notes/2.8.0)
 
 * Expand relative directory paths when initializing `Storage::FileSystem` (@janko)
 
@@ -756,7 +764,7 @@
 
 * Update `direct_upload` plugin to support Roda 3 (@janko)
 
-## 2.7.0 (2017-09-11)
+## 2.7.0 (2017-09-11) [[release notes]](https://shrinerb.com/docs/release_notes/2.7.0)
 
 * Deprecate the `Shrine::DownloadEndpoint` constant over `Shrine.download_endpoint` (@janko)
 
@@ -824,11 +832,11 @@
 
 * Don't add a newline at the end of the base64-formatted signature (@janko)
 
-## 2.6.1 (2017-04-12)
+## 2.6.1 (2017-04-12) [[release notes]](https://shrinerb.com/docs/release_notes/2.6.1)
 
 * Fix `download_endpoint` returning incorrect reponse body in some cases (@janko)
 
-## 2.6.0 (2017-04-04)
+## 2.6.0 (2017-04-04) [[release notes]](https://shrinerb.com/docs/release_notes/2.6.0)
 
 * Make `Shrine::Storage::FileSystem#path` public which returns path to the file as a `Pathname` object (@janko)
 
@@ -900,7 +908,7 @@
 
 * Raise `Shrine::Error` when `Shrine#generate_location` returns nil (@janko)
 
-## 2.5.0 (2016-11-11)
+## 2.5.0 (2016-11-11) [[release notes]](https://shrinerb.com/docs/release_notes/2.5.0)
 
 * Add `Attacher.default_url` as the idiomatic way of declaring default URLs (@janko)
 
@@ -926,7 +934,7 @@
 
 * Make it possible to extract multiple metadata values at once with the `add_metadata` plugin (@janko)
 
-## 2.4.1 (2016-10-17)
+## 2.4.1 (2016-10-17) [[release notes]](https://shrinerb.com/docs/release_notes/2.4.1)
 
 * Move back JSON serialization from `Attacher#write` to `Attacher#_set` (@janko)
 
@@ -936,7 +944,7 @@
 
 * In `UploadedFile#download` use extension from `#original_filename` if `#id` doesn't have it (@janko)
 
-## 2.4.0 (2016-10-11)
+## 2.4.0 (2016-10-11) [[release notes]](https://shrinerb.com/docs/release_notes/2.4.0)
 
 * Add `#convert_before_write` and `#convert_after_read` on the Attacher for data attribute conversion (@janko)
 
@@ -972,11 +980,11 @@
 
 * Override `#to_s` in `Shrine::Attachment` for better introspection with `puts` (@janko)
 
-## 2.3.1 (2016-09-01)
+## 2.3.1 (2016-09-01) [[release notes]](https://shrinerb.com/docs/release_notes/2.3.1)
 
 * Don't change permissions of existing directories in FileSystem storage (@janko)
 
-## 2.3.0 (2016-08-27)
+## 2.3.0 (2016-08-27) [[release notes]](https://shrinerb.com/docs/release_notes/2.3.0)
 
 * Prevent client from caching the presign response in direct_upload plugin (@janko)
 
@@ -1002,7 +1010,7 @@
 
 * Add `:directory_permissions` to `Storage::FileSystem` (@janko)
 
-## 2.2.0 (2016-07-29)
+## 2.2.0 (2016-07-29) [[release notes]](https://shrinerb.com/docs/release_notes/2.2.0)
 
 * Soft deprecate `:phase` over `:action` in `context` (@janko)
 
@@ -1034,11 +1042,11 @@
 
 * Avoid an additional HEAD request to determine content length in multipart S3 copy (@janko)
 
-## 2.1.1 (2016-07-14)
+## 2.1.1 (2016-07-14) [[release notes]](https://shrinerb.com/docs/release_notes/2.1.1)
 
 * Fix `S3#open` throwing a NameError if `net/http` isn't required (@janko)
 
-## 2.1.0 (2016-06-27)
+## 2.1.0 (2016-06-27) [[release notes]](https://shrinerb.com/docs/release_notes/2.1.0)
 
 * Remove `:names` from versions plugin, and deprecate generating versions in :cache phase (@janko)
 
@@ -1054,11 +1062,11 @@
 
 * Deprecate `#cached_<attachment>_data=` over using `<attachment>` for the hidden field (@janko)
 
-## 2.0.1 (2016-05-30)
+## 2.0.1 (2016-05-30) [[release notes]](https://shrinerb.com/docs/release_notes/2.0.1)
 
 * Don't override previously set default_url in versions plugin (@janko)
 
-## 2.0.0 (2016-05-19)
+## 2.0.0 (2016-05-19) [[release notes]](https://shrinerb.com/docs/release_notes/2.0.0)
 
 * Include query parameters in CDN-ed S3 URLs, making them work for private objects (@janko)
 
@@ -1138,17 +1146,17 @@
 
 * Deprecate loading the backgrounding plugin through the old "background_helpers" alias (@janko)
 
-## 1.4.2 (2016-04-19)
+## 1.4.2 (2016-04-19) [[release notes]](https://shrinerb.com/docs/release_notes/1.4.2)
 
 * Removed ActiveRecord's automatic support for optimistic locking as it wasn't stable (@janko)
 
 * Fixed record's dataset being modified after promoting preventing further updates with the same instance (@janko)
 
-## 1.4.1 (2016-04-18)
+## 1.4.1 (2016-04-18) [[release notes]](https://shrinerb.com/docs/release_notes/1.4.1)
 
 * Bring back triggering callbacks on promote in ORM plugins, and add support for optimistic locking (@janko)
 
-## 1.4.0 (2016-04-15)
+## 1.4.0 (2016-04-15) [[release notes]](https://shrinerb.com/docs/release_notes/1.4.0)
 
 * Return "Content-Length" response header in download_endpoint plugin (@janko)
 
@@ -1204,7 +1212,7 @@
 
 * Fix keep_files not to spawn a background job when file will not be deleted (@janko)
 
-## 1.3.0 (2016-03-12)
+## 1.3.0 (2016-03-12) [[release notes]](https://shrinerb.com/docs/release_notes/1.3.0)
 
 * Add `<attachment>_cached?` and `<attachment>_stored?` to migration_helpers plugin (@janko)
 
@@ -1246,7 +1254,7 @@
 
 * Fix `NameError` when silencing "missing record" errors in backgrounding (@janko)
 
-## 1.2.0 (2016-01-26)
+## 1.2.0 (2016-01-26) [[release notes]](https://shrinerb.com/docs/release_notes/1.2.0)
 
 * Make `Shrine::Attacher.promote` and `Shrine::Attacher.delete` return the record in backgrounding plugin (@janko)
 
@@ -1262,7 +1270,7 @@
 
 * Make custom metadata inherited from uploaded files and make `#extract_metadata` called only on caching (@janko)
 
-## 1.1.0 (2015-12-26)
+## 1.1.0 (2015-12-26) [[release notes]](https://shrinerb.com/docs/release_notes/1.1.0)
 
 * Rename the "background_helpers" plugin to "backgrounding" (@janko)
 
@@ -1332,7 +1340,7 @@
 
 * Reduce length of URLs generated with pretty_location plugin (@gshaw)
 
-## 1.0.0 (2015-11-27)
+## 1.0.0 (2015-11-27) [[release notes]](https://shrinerb.com/docs/release_notes/1.0.0)
 
 * Improve Windows compatibility in the FileSystem storage (@janko)
 

data/README.md

@@ -23,6 +23,91 @@ Please follow along with the **[Getting Started guide]**.
 | Wiki                    | [github.com/shrinerb/shrine/wiki](https://github.com/shrinerb/shrine/wiki)     |
 | Help & Discussion       | [discourse.shrinerb.com](https://discourse.shrinerb.com)                       |
 
+## Setup
+
+Add the gem to your Gemfile:
+
+```rb
+# Gemfile
+gem "shrine", "~> 3.0"
+```
+
+Then add `config/initializers/shrine.rb` which sets up the storage and loads
+ORM integration:
+
+```rb
+require "shrine"
+require "shrine/storage/file_system"
+
+Shrine.storages = {
+  cache: Shrine::Storage::FileSystem.new("public", prefix: "uploads/cache"), # temporary
+  store: Shrine::Storage::FileSystem.new("public", prefix: "uploads"),       # permanent
+}
+
+Shrine.plugin :activerecord           # loads Active Record integration
+Shrine.plugin :cached_attachment_data # enables retaining cached file across form redisplays
+Shrine.plugin :restore_cached_data    # extracts metadata for assigned cached files
+```
+
+Next, add the `<name>_data` column to the table you want to attach files to. For
+an "image" attachment on a `photos` table this would be an `image_data` column:
+
+```sh
+$ rails generate migration add_image_data_to_photos image_data:text
+```
+
+Now create an uploader class (which you can put in `app/uploaders`) and
+register the attachment on your model:
+
+```rb
+class ImageUploader < Shrine
+  # plugins and uploading logic
+end
+```
+```rb
+class Photo < ActiveRecord::Base
+  include ImageUploader::Attachment(:image) # adds an `image` virtual attribute
+end
+```
+
+In our views let's now add form fields for our attachment attribute that will
+allow users to upload files:
+
+```erb
+<%= form_for @photo do |f| %>
+  <%= f.hidden_field :image, value: @photo.cached_image_data %>
+  <%= f.file_field :image %>
+  <%= f.submit %>
+<% end %>
+```
+
+When the form is submitted, in your controller you can assign the file from
+request params to the attachment attribute on the model:
+
+```rb
+class PhotosController < ApplicationController
+  def create
+    Photo.create(photo_params) # attaches the uploaded file
+    # ...
+  end
+
+  private
+
+  def photo_params
+    params.require(:photo).permit(:image)
+  end
+end
+```
+
+Once a file is uploaded and attached to the record, you can retrieve the file
+URL and display it on the page:
+
+```erb
+<%= image_tag @photo.image_url %>
+```
+
+See the **[Getting Started guide]** for further documentation.
+
 ## Inspiration
 
 Shrine was heavily inspired by [Refile] and [Roda]. From Refile it borrows the

data/doc/advantages.md

@@ -276,9 +276,9 @@ end
 ```rb
 movie.video_derivatives! # create derivatives
 
-movie.video              #=> #<Shrine::UploadedFile @id="5a5cd0.mov" ...>
-movie.video(:transcoded) #=> #<Shrine::UploadedFile @id="7481d6.mp4" ...>
-movie.video(:screenshot) #=> #<Shrine::UploadedFile @id="8f3136.jpg" ...>
+movie.video              #=> #<Shrine::UploadedFile id="5a5cd0.mov" ...>
+movie.video(:transcoded) #=> #<Shrine::UploadedFile id="7481d6.mp4" ...>
+movie.video(:screenshot) #=> #<Shrine::UploadedFile id="8f3136.jpg" ...>
 ```
 
 ## Metadata & Validation

data/doc/attacher.md

@@ -96,14 +96,14 @@ If given a raw file, it will upload it to temporary storage:
 
 ```rb
 attacher.assign(file)
-attacher.file #=> #<Shrine::UploadedFile @id="asdf.jpg", @storage_key=:cache>
+attacher.file #=> #<Shrine::UploadedFile id="asdf.jpg" storage=:cache ...>
 ```
 
 If given cached file data (JSON or Hash), it will set the cached file:
 
 ```rb
 attacher.assign('{"id":"asdf.jpg","storage":"cache","metadata":{...}}')
-attacher.file #=> #<Shrine::UploadedFile @id="asdf.jpg", @storage_key=:cache>
+attacher.file #=> #<Shrine::UploadedFile id="asdf.jpg" storage=:cache ...>
 ```
 
 If given an empty string, it will no-op:
@@ -143,7 +143,7 @@ The `Attacher#attach` method uploads a given file to permanent storage:
 
 ```rb
 attacher.attach(file)
-attacher.file #=> #<Shrine::UploadedFile @id="asdf.jpg" @storage=:store>
+attacher.file #=> #<Shrine::UploadedFile id="asdf.jpg" storage=:store ...>
 ```
 
 This method is useful when attaching files from scripts, where validation
@@ -153,7 +153,7 @@ You can specify a different destination storage with the `:storage` option:
 
 ```rb
 attacher.attach(file, storage: :other_store)
-attacher.file #=> #<Shrine::UploadedFile @id="asdf.jpg" @storage=:other_store>
+attacher.file #=> #<Shrine::UploadedFile id="asdf.jpg" storage=:other_store ...>
 ```
 
 Any additional options passed to `Attacher#attach`, `Attacher#attach_cached`
@@ -171,9 +171,9 @@ If you want to upload a file to without attaching it, you can use
 `Attacher#upload`:
 
 ```rb
-attacher.upload(file)               #=> #<Shrine::UploadedFile @storage=:store ...>
-attacher.upload(file, :cache)       #=> #<Shrine::UploadedFile @storage=:cache ...>
-attacher.upload(file, :other_store) #=> #<Shrine::UploadedFile @storage=:other_store ...>
+attacher.upload(file)               #=> #<Shrine::UploadedFile storage=:store ...>
+attacher.upload(file, :cache)       #=> #<Shrine::UploadedFile storage=:cache ...>
+attacher.upload(file, :other_store) #=> #<Shrine::UploadedFile storage=:other_store ...>
 ```
 
 This is useful if you want to attacher [context](#context) such as `:record`
@@ -202,20 +202,19 @@ attacher.changed? #=> true
 You can use `Attacher#change` to attach an `UploadedFile` object as is:
 
 ```rb
-uploaded_file #=> #<Shrine::UploadedFile>
+uploaded_file #=> #<Shrine::UploadedFile id="foo" ...>
 attacher.change(uploaded_file)
-attacher.file #=> #<Shrine::UploadedFile> (same object)
+attacher.file #=> #<Shrine::UploadedFile id="foo" ...>
 attacher.changed? #=> true
-
 ```
 
 If you want to attach a file without triggering dirty tracking or validation,
 you can use `Attacher#set`:
 
 ```rb
-uploaded_file #=> #<Shrine::UploadedFile>
+uploaded_file #=> #<Shrine::UploadedFile id="foo" ...>
 attacher.set(uploaded_file)
-attacher.file #=> #<Shrine::UploadedFile> (same object)
+attacher.file #=> #<Shrine::UploadedFile id="foo" ...>
 attacher.changed? #=> false
 ```
 
@@ -246,16 +245,16 @@ storage, and in this case uploads it to permanent storage.
 ```rb
 attacher.attach_cached(io)
 attacher.finalize # uploads attached file to permanent storage
-attacher.file #=> #<Shrine::UploadedFile @storage=:store ...>
+attacher.file #=> #<Shrine::UploadedFile storage=:store ...>
 ```
 
 Internally it calls `Attacher#promote_cached`, which you can call directly if
 you want to pass any promote options:
 
 ```rb
-attacher.file #=> #<Shrine::UploadedFile @storage=:cache ...>
+attacher.file #=> #<Shrine::UploadedFile storage=:cache ...>
 attacher.promote_cached # uploads attached file to permanent storage if new and cached
-attacher.file #=> #<Shrine::UploadedFile @storage=:store ...>
+attacher.file #=> #<Shrine::UploadedFile storage=:store ...>
 ```
 
 You can also call `Attacher#promote` if you want to upload attached file to