Shrine::UploadedFile::InstanceMethods

Methods

Public Class

Public Instance

==
[]
as_json
close
data
delete
download
eof?
exists?
extension
hash
id
inspect
metadata
mime_type
open
opened?
original_filename
read
replace
rewind
shrine_class
size
storage
storage_key
stream
to_io
to_json
uploader
url

Public Instance Aliases

content_type	->	mime_type
eql?	->	==

Attributes

id	[R]	The location where the file was uploaded to the storage.
metadata	[R]	A hash of file metadata that was extracted during upload.
storage_key	[R]	The identifier of the storage the file is uploaded to.

Public Class methods

new(data)

Initializes the uploaded file with the given data hash.

[show source]

   # File lib/shrine/uploaded_file.rb
35 def initialize(data)
36   @id          = data[:id]              || data["id"]
37   @storage_key = data[:storage]&.to_sym || data["storage"]&.to_sym
38   @metadata    = data[:metadata]        || data["metadata"]        || {}
39 
40   fail Error, "#{data.inspect} isn't valid uploaded file data" unless @id && @storage_key
41 
42   storage # ensure storage is registered
43 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
225 def ==(other)
226   self.class       == other.class       &&
227   self.id          == other.id          &&
228   self.storage_key == other.storage_key
229 end

[](key)

Shorthand for accessing metadata values.

[show source]

   # File lib/shrine/uploaded_file.rb
71 def [](key)
72   metadata[key]
73 end

as_json(*args)

Conform to ActiveSupport’s JSON interface.

[show source]

    # File lib/shrine/uploaded_file.rb
214 def as_json(*args)
215   data
216 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
171 def close
172   io.close if opened?
173 end

data()

Returns serializable hash representation of the uploaded file.

[show source]

    # File lib/shrine/uploaded_file.rb
219 def data
220   { "id" => id, "storage" => storage_key.to_s, "metadata" => metadata }
221 end

delete()

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

[show source]

    # File lib/shrine/uploaded_file.rb
198 def delete
199   storage.delete(id)
200 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
121 def download(**options)
122   tempfile = Tempfile.new(["shrine", ".#{extension}"], binmode: true)
123   stream(tempfile, **options)
124   tempfile.open
125 
126   block_given? ? yield(tempfile) : tempfile
127 ensure
128   tempfile.close! if ($! || block_given?) && tempfile
129 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
159 def eof?
160   io.eof?
161 end

exists?()

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

[show source]

    # File lib/shrine/uploaded_file.rb
187 def exists?
188   storage.exists?(id)
189 end

extension()

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

[show source]

   # File lib/shrine/uploaded_file.rb
52 def extension
53   identifier = id =~ URI::DEFAULT_PARSER.make_regexp ? id.sub(/\?.+$/, "") : id # strip query params for shrine-url
54   result = File.extname(identifier)[1..-1]
55   result ||= File.extname(original_filename.to_s)[1..-1]
56   result.downcase if result
57 end

hash()

Enables using UploadedFile objects as hash keys.

[show source]

    # File lib/shrine/uploaded_file.rb
233 def hash
234   [id, storage_key].hash
235 end

inspect()

Returns simplified inspect output.

[show source]

    # File lib/shrine/uploaded_file.rb
253 def inspect
254   "#<#{self.class.inspect} storage=#{storage_key.inspect} id=#{id.inspect} metadata=#{metadata.inspect}>"
255 end

mime_type()

The MIME type of the uploaded file.

[show source]

   # File lib/shrine/uploaded_file.rb
65 def mime_type
66   metadata["mime_type"]
67 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
 92 def open(**options)
 93   @io.close if @io
 94   @io = _open(**options)
 95 
 96   return @io unless block_given?
 97 
 98   begin
 99     yield @io
100   ensure
101     close
102     @io = nil
103   end
104 end

opened?()

Returns whether the file has already been opened.

[show source]

    # File lib/shrine/uploaded_file.rb
176 def opened?
177   !!@io
178 end

original_filename()

The filename that was extracted from the uploaded file.

[show source]

   # File lib/shrine/uploaded_file.rb
46 def original_filename
47   metadata["filename"]
48 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
153 def read(*args)
154   io.read(*args)
155 end

replace(io, **options)

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

[show source]

    # File lib/shrine/uploaded_file.rb
192 def replace(io, **options)
193   uploader.upload(io, **options, location: id)
194 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
165 def rewind
166   io.rewind
167 end

shrine_class()

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

[show source]

    # File lib/shrine/uploaded_file.rb
248 def shrine_class
249   self.class.shrine_class
250 end

size()

The filesize of the uploaded file.

[show source]

   # File lib/shrine/uploaded_file.rb
60 def size
61   (@io && @io.size) || (metadata["size"] && Integer(metadata["size"]))
62 end

storage()

Returns the storage that this file was uploaded to.

[show source]

    # File lib/shrine/uploaded_file.rb
243 def storage
244   shrine_class.find_storage(storage_key)
245 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
142 def stream(destination, **options)
143   if opened?
144     IO.copy_stream(io, destination)
145     io.rewind
146   else
147     open(**options) { |io| IO.copy_stream(io, destination) }
148   end
149 end

to_io()

Returns an opened IO object for the uploaded file.

[show source]

    # File lib/shrine/uploaded_file.rb
203 def to_io
204   io
205 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
209 def to_json(*args)
210   data.to_json(*args)
211 end

uploader()

Returns an uploader object for the corresponding storage.

[show source]

    # File lib/shrine/uploaded_file.rb
238 def uploader
239   shrine_class.new(storage_key)
240 end

url(**options)

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

[show source]

    # File lib/shrine/uploaded_file.rb
181 def url(**options)
182   storage.url(id, **options)
183 end

module Shrine::UploadedFile::InstanceMethods

Methods

Public Class

Public Instance

Public Instance Aliases

Attributes

Public Class methods

Public Instance methods