module Shrine::UploadedFile::InstanceMethods

  1. lib/shrine/uploaded_file.rb

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
224 def ==(other)
225   self.class       == other.class       &&
226   self.id          == other.id          &&
227   self.storage_key == other.storage_key
228 end
[](key)

Shorthand for accessing metadata values.

[show source]
   # File lib/shrine/uploaded_file.rb
70 def [](key)
71   metadata[key]
72 end
as_json(*args)

Conform to ActiveSupport's JSON interface.

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

Returns serializable hash representation of the uploaded file.

[show source]
    # File lib/shrine/uploaded_file.rb
218 def data
219   { "id" => id, "storage" => storage_key.to_s, "metadata" => metadata }
220 end
delete()

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

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

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

[show source]
    # File lib/shrine/uploaded_file.rb
186 def exists?
187   storage.exists?(id)
188 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   result = File.extname(id)[1..-1] || File.extname(original_filename.to_s)[1..-1]
54   result.sub!(/\?.+$/, "") if result && id =~ URI::regexp # strip query params for shrine-url
55   result.downcase if result
56 end
hash()

Enables using UploadedFile objects as hash keys.

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

Returns simplified inspect output.

[show source]
    # File lib/shrine/uploaded_file.rb
252 def inspect
253   "#<#{self.class.inspect} storage=#{storage_key.inspect} id=#{id.inspect} metadata=#{metadata.inspect}>"
254 end
mime_type()

The MIME type of the uploaded file.

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

Returns whether the file has already been opened.

[show source]
    # File lib/shrine/uploaded_file.rb
175 def opened?
176   !!@io
177 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
152 def read(*args)
153   io.read(*args)
154 end
replace(io, **options)

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

[show source]
    # File lib/shrine/uploaded_file.rb
191 def replace(io, **options)
192   uploader.upload(io, **options, location: id)
193 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
164 def rewind
165   io.rewind
166 end
shrine_class()

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

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

The filesize of the uploaded file.

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

Returns the storage that this file was uploaded to.

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

Returns an opened IO object for the uploaded file.

[show source]
    # File lib/shrine/uploaded_file.rb
202 def to_io
203   io
204 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
208 def to_json(*args)
209   data.to_json(*args)
210 end
uploader()

Returns an uploader object for the corresponding storage.

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

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

[show source]
    # File lib/shrine/uploaded_file.rb
180 def url(**options)
181   storage.url(id, **options)
182 end