module Shrine::UploadedFile::InstanceMethods

  1. lib/shrine/uploaded_file.rb

Public Instance Aliases

content_type -> mime_type
eql? -> ==

Attributes

data [R]

The hash of information which defines this uploaded file.

Public Class methods

new (data)

Initializes the uploaded file with the given data hash.

[show source]
   # File lib/shrine/uploaded_file.rb
30 def initialize(data)
31   raise Error, "#{data.inspect} isn't valid uploaded file data" unless data["id"] && data["storage"]
32 
33   @data = data
34   @data["metadata"] ||= {}
35   storage # ensure storage is registered
36 end

Public Instance methods

== (other)

Returns true if the other UploadedFile is uploaded to the same storage and it has the same id.

[show source]
    # File lib/shrine/uploaded_file.rb
222 def ==(other)
223   other.is_a?(self.class) &&
224   self.id == other.id &&
225   self.storage_key == other.storage_key
226 end
as_json (*args)

Conform to ActiveSupport's JSON interface.

[show source]
    # File lib/shrine/uploaded_file.rb
216 def as_json(*args)
217   data
218 end
close ()

Part of complying to the IO interface. It delegates to the internally opened IO object.

[show source]
    # File lib/shrine/uploaded_file.rb
173 def close
174   io.close if opened?
175 end
delete ()

Calls #delete on the storage, which deletes the file from the storage.

[show source]
    # File lib/shrine/uploaded_file.rb
200 def delete
201   storage.delete(id)
202 end
download (**options)

Streams content into a newly created Tempfile and returns it.

If a block is given, the opened Tempfile object is yielded to the block, and at the end of the block it's automatically closed and deleted. In this case the return value of the method is the block return value.

If no block is given, the opened Tempfile is returned.

uploaded_file.download
#=> #<File:/var/folders/.../20180302-33119-1h1vjbq.jpg>

# or

uploaded_file.download { |tempfile| tempfile.read } # tempfile is deleted
[show source]
    # File lib/shrine/uploaded_file.rb
123 def download(**options)
124   tempfile = Tempfile.new(["shrine", ".#{extension}"], binmode: true)
125   stream(tempfile, **options)
126   tempfile.open
127 
128   block_given? ? yield(tempfile) : tempfile
129 ensure
130   tempfile.close! if ($! || block_given?) && tempfile
131 end
eof? ()

Part of complying to the IO interface. It delegates to the internally opened IO object.

[show source]
    # File lib/shrine/uploaded_file.rb
161 def eof?
162   io.eof?
163 end
exists? ()

Calls #exists? on the storage, which checks whether the file exists on the storage.

[show source]
    # File lib/shrine/uploaded_file.rb
189 def exists?
190   storage.exists?(id)
191 end
extension ()

The extension derived from id if present, otherwise it's derived from original_filename.

[show source]
   # File lib/shrine/uploaded_file.rb
60 def extension
61   result = File.extname(id)[1..-1] || File.extname(original_filename.to_s)[1..-1]
62   result.sub!(/\?.+$/, "") if result && id =~ URI::regexp # strip query params for shrine-url
63   result.downcase if result
64 end
hash ()

Enables using UploadedFile objects as hash keys.

[show source]
    # File lib/shrine/uploaded_file.rb
230 def hash
231   [id, storage_key].hash
232 end
id ()

The location where the file was uploaded to the storage.

[show source]
   # File lib/shrine/uploaded_file.rb
39 def id
40   @data.fetch("id")
41 end
metadata ()

A hash of file metadata that was extracted during upload.

[show source]
   # File lib/shrine/uploaded_file.rb
49 def metadata
50   @data.fetch("metadata")
51 end
mime_type ()

The MIME type of the uploaded file.

[show source]
   # File lib/shrine/uploaded_file.rb
72 def mime_type
73   metadata["mime_type"]
74 end
open (**options)

Calls #open on the storage to open the uploaded file for reading. Most storages will return a lazy IO object which dynamically retrieves file content from the storage as the object is being read.

If a block is given, the opened IO object is yielded to the block, and at the end of the block it's automatically closed. In this case the return value of the method is the block return value.

If no block is given, the opened IO object is returned.

uploaded_file.open #=> IO object returned by the storage
uploaded_file.read #=> "..."
uploaded_file.close

# or

uploaded_file.open { |io| io.read } # the IO is automatically closed
[show source]
    # File lib/shrine/uploaded_file.rb
 94 def open(**options)
 95   @io.close if @io
 96   @io = _open(**options)
 97 
 98   return @io unless block_given?
 99 
100   begin
101     yield @io
102   ensure
103     close
104     @io = nil
105   end
106 end
opened? ()

Returns whether the file has already been opened.

[show source]
    # File lib/shrine/uploaded_file.rb
178 def opened?
179   !!@io
180 end
original_filename ()

The filename that was extracted from the uploaded file.

[show source]
   # File lib/shrine/uploaded_file.rb
54 def original_filename
55   metadata["filename"]
56 end
read (*args)

Part of complying to the IO interface. It delegates to the internally opened IO object.

[show source]
    # File lib/shrine/uploaded_file.rb
155 def read(*args)
156   io.read(*args)
157 end
replace (io, context = {})

Uploads a new file to this file's location and returns it.

[show source]
    # File lib/shrine/uploaded_file.rb
194 def replace(io, context = {})
195   uploader.upload(io, context.merge(location: id))
196 end
rewind ()

Part of complying to the IO interface. It delegates to the internally opened IO object.

[show source]
    # File lib/shrine/uploaded_file.rb
167 def rewind
168   io.rewind
169 end
shrine_class ()

Returns the Shrine class that this file's class is namespaced under.

[show source]
    # File lib/shrine/uploaded_file.rb
245 def shrine_class
246   self.class.shrine_class
247 end
size ()

The filesize of the uploaded file.

[show source]
   # File lib/shrine/uploaded_file.rb
67 def size
68   (@io && @io.size) || (metadata["size"] && Integer(metadata["size"]))
69 end
storage ()

Returns the storage that this file was uploaded to.

[show source]
    # File lib/shrine/uploaded_file.rb
240 def storage
241   shrine_class.find_storage(storage_key)
242 end
storage_key ()

The string identifier of the storage the file is uploaded to.

[show source]
   # File lib/shrine/uploaded_file.rb
44 def storage_key
45   @data.fetch("storage")
46 end
stream (destination, **options)

Streams uploaded file content into the specified destination. The destination object is given directly to IO.copy_stream, so it can be either a path on disk or an object that responds to #write.

If the uploaded file is already opened, it will be simply rewinded after streaming finishes. Otherwise the uploaded file is opened and then closed after streaming.

uploaded_file.stream(StringIO.new)
# or
uploaded_file.stream("/path/to/destination")
[show source]
    # File lib/shrine/uploaded_file.rb
144 def stream(destination, **options)
145   if opened?
146     IO.copy_stream(io, destination)
147     io.rewind
148   else
149     open(**options) { |io| IO.copy_stream(io, destination) }
150   end
151 end
to_io ()

Returns an opened IO object for the uploaded file.

[show source]
    # File lib/shrine/uploaded_file.rb
205 def to_io
206   io
207 end
to_json (*args)

Returns the data hash in the JSON format. Suitable for storing in a database column or passing to a background job.

[show source]
    # File lib/shrine/uploaded_file.rb
211 def to_json(*args)
212   data.to_json(*args)
213 end
uploader ()

Returns an uploader object for the corresponding storage.

[show source]
    # File lib/shrine/uploaded_file.rb
235 def uploader
236   shrine_class.new(storage_key)
237 end
url (**options)

Calls #url on the storage, forwarding any given URL options.

[show source]
    # File lib/shrine/uploaded_file.rb
183 def url(**options)
184   storage.url(id, **options)
185 end