]> git.openstreetmap.org Git - rails.git/blob - vendor/plugins/file_column/lib/file_column.rb
Merged 17073:17076 from trunk.
[rails.git] / vendor / plugins / file_column / lib / file_column.rb
1 require 'fileutils'
2 require 'tempfile'
3 require 'magick_file_column'
4
5 module FileColumn # :nodoc:
6   def self.append_features(base)
7     super
8     base.extend(ClassMethods)
9   end
10
11   def self.create_state(instance,attr)
12     filename = instance[attr]
13     if filename.nil? or filename.empty?
14       NoUploadedFile.new(instance,attr)
15     else
16       PermanentUploadedFile.new(instance,attr)
17     end
18   end
19
20   def self.init_options(defaults, model, attr)
21     options = defaults.dup
22     options[:store_dir] ||= File.join(options[:root_path], model, attr)
23     unless options[:store_dir].is_a?(Symbol)
24       options[:tmp_base_dir] ||= File.join(options[:store_dir], "tmp")
25     end
26     options[:base_url] ||= options[:web_root] + File.join(model, attr)
27
28     [:store_dir, :tmp_base_dir].each do |dir_sym|
29       if options[dir_sym].is_a?(String) and !File.exists?(options[dir_sym])
30         FileUtils.mkpath(options[dir_sym])
31       end
32     end
33
34     options
35   end
36
37   class BaseUploadedFile # :nodoc:
38
39     def initialize(instance,attr)
40       @instance, @attr = instance, attr
41       @options_method = "#{attr}_options".to_sym
42     end
43
44
45     def assign(file)
46       if file.is_a? File
47         # this did not come in via a CGI request. However,
48         # assigning files directly may be useful, so we
49         # make just this file object similar enough to an uploaded
50         # file that we can handle it. 
51         file.extend FileColumn::FileCompat
52       end
53
54       if file.nil?
55         delete
56       else
57         if file.size == 0
58           # user did not submit a file, so we
59           # can simply ignore this
60           self
61         else
62           if file.is_a?(String)
63             # if file is a non-empty string it is most probably
64             # the filename and the user forgot to set the encoding
65             # to multipart/form-data. Since we would raise an exception
66             # because of the missing "original_filename" method anyways,
67             # we raise a more meaningful exception rightaway.
68             raise TypeError.new("Do not know how to handle a string with value '#{file}' that was passed to a file_column. Check if the form's encoding has been set to 'multipart/form-data'.")
69           end
70           upload(file)
71         end
72       end
73     end
74
75     def just_uploaded?
76       @just_uploaded
77     end
78
79     def on_save(&blk)
80       @on_save ||= []
81       @on_save << Proc.new
82     end
83     
84     # the following methods are overriden by sub-classes if needed
85
86     def temp_path
87       nil
88     end
89
90     def absolute_dir
91       if absolute_path then File.dirname(absolute_path) else nil end
92     end
93
94     def relative_dir
95       if relative_path then File.dirname(relative_path) else nil end
96     end
97
98     def after_save
99       @on_save.each { |blk| blk.call } if @on_save
100       self
101     end
102
103     def after_destroy
104     end
105
106     def options
107       @instance.send(@options_method)
108     end
109
110     private
111     
112     def store_dir
113       if options[:store_dir].is_a? Symbol
114         raise ArgumentError.new("'#{options[:store_dir]}' is not an instance method of class #{@instance.class.name}") unless @instance.respond_to?(options[:store_dir])
115
116         dir = File.join(options[:root_path], @instance.send(options[:store_dir]))
117         FileUtils.mkpath(dir) unless File.exists?(dir)
118         dir
119       else 
120         options[:store_dir]
121       end
122     end
123
124     def tmp_base_dir
125       if options[:tmp_base_dir]
126         options[:tmp_base_dir] 
127       else
128         dir = File.join(store_dir, "tmp")
129         FileUtils.mkpath(dir) unless File.exists?(dir)
130         dir
131       end
132     end
133
134     def clone_as(klass)
135       klass.new(@instance, @attr)
136     end
137
138   end
139     
140
141   class NoUploadedFile < BaseUploadedFile # :nodoc:
142     def delete
143       # we do not have a file so deleting is easy
144       self
145     end
146
147     def upload(file)
148       # replace ourselves with a TempUploadedFile
149       temp = clone_as TempUploadedFile
150       temp.store_upload(file)
151       temp
152     end
153
154     def absolute_path(subdir=nil)
155       nil
156     end
157
158
159     def relative_path(subdir=nil)
160       nil
161     end
162
163     def assign_temp(temp_path)
164       return self if temp_path.nil? or temp_path.empty?
165       temp = clone_as TempUploadedFile
166       temp.parse_temp_path temp_path
167       temp
168     end
169   end
170
171   class RealUploadedFile < BaseUploadedFile # :nodoc:
172     def absolute_path(subdir=nil)
173       if subdir
174         File.join(@dir, subdir, @filename)
175       else
176         File.join(@dir, @filename)
177       end
178     end
179
180     def relative_path(subdir=nil)
181       if subdir
182         File.join(relative_path_prefix, subdir, @filename)
183       else
184         File.join(relative_path_prefix, @filename)
185       end
186     end
187
188     private
189
190     # regular expressions to try for identifying extensions
191     EXT_REGEXPS = [ 
192       /^(.+)\.([^.]+\.[^.]+)$/, # matches "something.tar.gz"
193       /^(.+)\.([^.]+)$/ # matches "something.jpg"
194     ]
195
196     def split_extension(filename,fallback=nil)
197       EXT_REGEXPS.each do |regexp|
198         if filename =~ regexp
199           base,ext = $1, $2
200           return [base, ext] if options[:extensions].include?(ext.downcase)
201         end
202       end
203       if fallback and filename =~ EXT_REGEXPS.last
204         return [$1, $2]
205       end
206       [filename, ""]
207     end
208     
209   end
210
211   class TempUploadedFile < RealUploadedFile # :nodoc:
212
213     def store_upload(file)
214       @tmp_dir = FileColumn.generate_temp_name
215       @dir = File.join(tmp_base_dir, @tmp_dir)      
216       FileUtils.mkdir(@dir)
217       
218       @filename = FileColumn::sanitize_filename(file.original_filename)
219       local_file_path = File.join(tmp_base_dir,@tmp_dir,@filename)
220       
221       # stored uploaded file into local_file_path
222       # If it was a Tempfile object, the temporary file will be
223       # cleaned up automatically, so we do not have to care for this
224       if file.respond_to?(:local_path) and file.local_path and File.exists?(file.local_path)
225         FileUtils.copy_file(file.local_path, local_file_path)
226       elsif file.respond_to?(:read)
227         File.open(local_file_path, "wb") { |f| f.write(file.read) }
228       else
229         raise ArgumentError.new("Do not know how to handle #{file.inspect}")
230       end
231       File.chmod(options[:permissions], local_file_path)
232       
233       if options[:fix_file_extensions]
234         # try to determine correct file extension and fix
235         # if necessary
236         content_type = get_content_type((file.content_type.chomp if file.content_type))
237         if content_type and options[:mime_extensions][content_type]
238           @filename = correct_extension(@filename,options[:mime_extensions][content_type])
239         end
240
241         new_local_file_path = File.join(tmp_base_dir,@tmp_dir,@filename)
242         File.rename(local_file_path, new_local_file_path) unless new_local_file_path == local_file_path
243         local_file_path = new_local_file_path
244       end
245       
246       @instance[@attr] = @filename
247       @just_uploaded = true
248     end
249
250
251     # tries to identify and strip the extension of filename
252     # if an regular expresion from EXT_REGEXPS matches and the
253     # downcased extension is a known extension (in options[:extensions])
254     # we'll strip this extension
255     def strip_extension(filename)
256       split_extension(filename).first
257     end
258
259     def correct_extension(filename, ext)
260       strip_extension(filename) << ".#{ext}"
261     end
262     
263     def parse_temp_path(temp_path, instance_options=nil)
264       raise ArgumentError.new("invalid format of '#{temp_path}'") unless temp_path =~ %r{^((\d+\.)+\d+)/([^/].+)$}
265       @tmp_dir, @filename = $1, FileColumn.sanitize_filename($3)
266       @dir = File.join(tmp_base_dir, @tmp_dir)
267
268       @instance[@attr] = @filename unless instance_options == :ignore_instance
269     end
270     
271     def upload(file)
272       # store new file
273       temp = clone_as TempUploadedFile
274       temp.store_upload(file)
275       
276       # delete old copy
277       delete_files
278
279       # and return new TempUploadedFile object
280       temp
281     end
282
283     def delete
284       delete_files
285       @instance[@attr] = ""
286       clone_as NoUploadedFile
287     end
288
289     def assign_temp(temp_path)
290       return self if temp_path.nil? or temp_path.empty?
291       # we can ignore this since we've already received a newly uploaded file
292
293       # however, we delete the old temporary files
294       temp = clone_as TempUploadedFile
295       temp.parse_temp_path(temp_path, :ignore_instance)
296       temp.delete_files
297
298       self
299     end
300
301     def temp_path
302       File.join(@tmp_dir, @filename)
303     end
304
305     def after_save
306       super
307
308       # we have a newly uploaded image, move it to the correct location
309       file = clone_as PermanentUploadedFile
310       file.move_from(File.join(tmp_base_dir, @tmp_dir), @just_uploaded)
311
312       # delete temporary files
313       delete_files
314
315       # replace with the new PermanentUploadedFile object
316       file
317     end
318
319     def delete_files
320       FileUtils.rm_rf(File.join(tmp_base_dir, @tmp_dir))
321     end
322
323     def get_content_type(fallback=nil)
324       if options[:file_exec]
325         begin
326           content_type = `#{options[:file_exec]} -bi "#{File.join(@dir,@filename)}"`.chomp
327           content_type = fallback unless $?.success?
328           content_type.gsub!(/;.+$/,"") if content_type
329           content_type
330         rescue
331           fallback
332         end
333       else
334         fallback
335       end
336     end
337
338     private
339
340     def relative_path_prefix
341       File.join("tmp", @tmp_dir)
342     end
343   end
344
345   
346   class PermanentUploadedFile < RealUploadedFile # :nodoc:
347     def initialize(*args)
348       super *args
349       @dir = File.join(store_dir, relative_path_prefix)
350       @filename = @instance[@attr]
351       @filename = nil if @filename.empty?
352     end
353
354     def move_from(local_dir, just_uploaded)
355       # remove old permament dir first
356       # this creates a short moment, where neither the old nor
357       # the new files exist but we can't do much about this as
358       # filesystems aren't transactional.
359       FileUtils.rm_rf @dir
360
361       FileUtils.mv local_dir, @dir
362
363       @just_uploaded = just_uploaded
364     end
365
366     def upload(file)
367       temp = clone_as TempUploadedFile
368       temp.store_upload(file)
369       temp
370     end
371
372     def delete
373       file = clone_as NoUploadedFile
374       @instance[@attr] = ""
375       file.on_save { delete_files }
376       file
377     end
378
379     def assign_temp(temp_path)
380       return nil if temp_path.nil? or temp_path.empty?
381
382       temp = clone_as TempUploadedFile
383       temp.parse_temp_path(temp_path)
384       temp
385     end
386
387     def after_destroy
388       delete_files
389     end
390
391     def delete_files
392       FileUtils.rm_rf @dir
393     end
394
395     private
396     
397     def relative_path_prefix
398       raise RuntimeError.new("Trying to access file_column, but primary key got lost.") if @instance.id.to_s.empty?
399       @instance.id.to_s
400     end
401   end
402     
403   # The FileColumn module allows you to easily handle file uploads. You can designate
404   # one or more columns of your model's table as "file columns" like this:
405   #
406   #   class Entry < ActiveRecord::Base
407   #
408   #     file_column :image
409   #   end
410   #
411   # Now, by default, an uploaded file "test.png" for an entry object with primary key 42 will
412   # be stored in in "public/entry/image/42/test.png". The filename "test.png" will be stored
413   # in the record's "image" column. The "entries" table should have a +VARCHAR+ column
414   # named "image".
415   #
416   # The methods of this module are automatically included into <tt>ActiveRecord::Base</tt>
417   # as class methods, so that you can use them in your models.
418   #
419   # == Generated Methods
420   #
421   # After calling "<tt>file_column :image</tt>" as in the example above, a number of instance methods
422   # will automatically be generated, all prefixed by "image":
423   #
424   # * <tt>Entry#image=(uploaded_file)</tt>: this will handle a newly uploaded file
425   #   (see below). Note that
426   #   you can simply call your upload field "entry[image]" in your view (or use the
427   #   helper).
428   # * <tt>Entry#image(subdir=nil)</tt>: This will return an absolute path (as a
429   #   string) to the currently uploaded file
430   #   or nil if no file has been uploaded
431   # * <tt>Entry#image_relative_path(subdir=nil)</tt>: This will return a path relative to
432   #   this file column's base directory
433   #   as a string or nil if no file has been uploaded. This would be "42/test.png" in the example.
434   # * <tt>Entry#image_just_uploaded?</tt>: Returns true if a new file has been uploaded to this instance.
435   #   You can use this in your code to perform certain actions (e. g., validation,
436   #   custom post-processing) only on newly uploaded files.
437   #
438   # You can access the raw value of the "image" column (which will contain the filename) via the
439   # <tt>ActiveRecord::Base#attributes</tt> or <tt>ActiveRecord::Base#[]</tt> methods like this:
440   #
441   #   entry['image']    # e.g."test.png"
442   #
443   # == Storage of uploaded files
444   #
445   # For a model class +Entry+ and a column +image+, all files will be stored under
446   # "public/entry/image". A sub-directory named after the primary key of the object will
447   # be created, so that files can be stored using their real filename. For example, a file
448   # "test.png" stored in an Entry object with id 42 will be stored in
449   #
450   #   public/entry/image/42/test.png
451   #
452   # Files will be moved to this location in an +after_save+ callback. They will be stored in
453   # a temporary location previously as explained in the next section.
454   #
455   # By default, files will be created with unix permissions of <tt>0644</tt> (i. e., owner has
456   # read/write access, group and others only have read access). You can customize
457   # this by passing the desired mode as a <tt>:permissions</tt> options. The value
458   # you give here is passed directly to <tt>File::chmod</tt>, so on Unix you should
459   # give some octal value like 0644, for example.
460   #
461   # == Handling of form redisplay
462   #
463   # Suppose you have a form for creating a new object where the user can upload an image. The form may
464   # have to be re-displayed because of validation errors. The uploaded file has to be stored somewhere so
465   # that the user does not have to upload it again. FileColumn will store these in a temporary directory
466   # (called "tmp" and located under the column's base directory by default) so that it can be moved to
467   # the final location if the object is successfully created. If the form is never completed, though, you
468   # can easily remove all the images in this "tmp" directory once per day or so.
469   #
470   # So in the example above, the image "test.png" would first be stored in 
471   # "public/entry/image/tmp/<some_random_key>/test.png" and be moved to
472   # "public/entry/image/<primary_key>/test.png".
473   #
474   # This temporary location of newly uploaded files has another advantage when updating objects. If the
475   # update fails for some reasons (e.g. due to validations), the existing image will not be overwritten, so
476   # it has a kind of "transactional behaviour".
477   #
478   # == Additional Files and Directories
479   #
480   # FileColumn allows you to keep more than one file in a directory and will move/delete
481   # all the files and directories it finds in a model object's directory when necessary.
482   #
483   # As a convenience you can access files stored in sub-directories via the +subdir+
484   # parameter if they have the same filename.
485   #
486   # Suppose your uploaded file is named "vancouver.jpg" and you want to create a
487   # thumb-nail and store it in the "thumb" directory. If you call
488   # <tt>image("thumb")</tt>, you
489   # will receive an absolute path for the file "thumb/vancouver.jpg" in the same
490   # directory "vancouver.jpg" is stored. Look at the documentation of FileColumn::Magick
491   # for more examples and how to create these thumb-nails automatically.
492   #
493   # == File Extensions
494   #
495   # FileColumn will try to fix the file extension of uploaded files, so that
496   # the files are served with the correct mime-type by your web-server. Most
497   # web-servers are setting the mime-type based on the file's extension. You
498   # can disable this behaviour by passing the <tt>:fix_file_extensions</tt> option
499   # with a value of +nil+ to +file_column+.
500   #
501   # In order to set the correct extension, FileColumn tries to determine
502   # the files mime-type first. It then uses the +MIME_EXTENSIONS+ hash to
503   # choose the corresponding file extension. You can override this hash
504   # by passing in a <tt>:mime_extensions</tt> option to +file_column+.
505   #
506   # The mime-type of the uploaded file is determined with the following steps:
507   #
508   # 1. Run the external "file" utility. You can specify the full path to
509   #    the executable in the <tt>:file_exec</tt> option or set this option
510   #    to +nil+ to disable this step
511   #
512   # 2. If the file utility couldn't determine the mime-type or the utility was not
513   #    present, the content-type provided by the user's browser is used
514   #    as a fallback.
515   #
516   # == Custom Storage Directories
517   #
518   # FileColumn's storage location is determined in the following way. All
519   # files are saved below the so-called "root_path" directory, which defaults to
520   # "RAILS_ROOT/public". For every file_column, you can set a separte "store_dir"
521   # option. It defaults to "model_name/attribute_name".
522   # 
523   # Files will always be stored in sub-directories of the store_dir path. The
524   # subdirectory is named after the instance's +id+ attribute for a saved model,
525   # or "tmp/<randomkey>" for unsaved models.
526   #
527   # You can specify a custom root_path by setting the <tt>:root_path</tt> option.
528   # 
529   # You can specify a custom storage_dir by setting the <tt>:storage_dir</tt> option.
530   #
531   # For setting a static storage_dir that doesn't change with respect to a particular
532   # instance, you assign <tt>:storage_dir</tt> a String representing a directory
533   # as an absolute path.
534   #
535   # If you need more fine-grained control over the storage directory, you
536   # can use the name of a callback-method as a symbol for the
537   # <tt>:store_dir</tt> option. This method has to be defined as an
538   # instance method in your model. It will be called without any arguments
539   # whenever the storage directory for an uploaded file is needed. It should return
540   # a String representing a directory relativeo to root_path.
541   #
542   # Uploaded files for unsaved models objects will be stored in a temporary
543   # directory. By default this directory will be a "tmp" directory in
544   # your <tt>:store_dir</tt>. You can override this via the
545   # <tt>:tmp_base_dir</tt> option.
546   module ClassMethods
547
548     # default mapping of mime-types to file extensions. FileColumn will try to
549     # rename a file to the correct extension if it detects a known mime-type
550     MIME_EXTENSIONS = {
551       "image/gif" => "gif",
552       "image/jpeg" => "jpg",
553       "image/pjpeg" => "jpg",
554       "image/x-png" => "png",
555       "image/jpg" => "jpg",
556       "image/png" => "png",
557       "application/x-shockwave-flash" => "swf",
558       "application/pdf" => "pdf",
559       "application/pgp-signature" => "sig",
560       "application/futuresplash" => "spl",
561       "application/msword" => "doc",
562       "application/postscript" => "ps",
563       "application/x-bittorrent" => "torrent",
564       "application/x-dvi" => "dvi",
565       "application/x-gzip" => "gz",
566       "application/x-ns-proxy-autoconfig" => "pac",
567       "application/x-shockwave-flash" => "swf",
568       "application/x-tgz" => "tar.gz",
569       "application/x-tar" => "tar",
570       "application/zip" => "zip",
571       "audio/mpeg" => "mp3",
572       "audio/x-mpegurl" => "m3u",
573       "audio/x-ms-wma" => "wma",
574       "audio/x-ms-wax" => "wax",
575       "audio/x-wav" => "wav",
576       "image/x-xbitmap" => "xbm",             
577       "image/x-xpixmap" => "xpm",             
578       "image/x-xwindowdump" => "xwd",             
579       "text/css" => "css",             
580       "text/html" => "html",                          
581       "text/javascript" => "js",
582       "text/plain" => "txt",
583       "text/xml" => "xml",
584       "video/mpeg" => "mpeg",
585       "video/quicktime" => "mov",
586       "video/x-msvideo" => "avi",
587       "video/x-ms-asf" => "asf",
588       "video/x-ms-wmv" => "wmv"
589     }
590
591     EXTENSIONS = Set.new MIME_EXTENSIONS.values
592     EXTENSIONS.merge %w(jpeg)
593
594     # default options. You can override these with +file_column+'s +options+ parameter
595     DEFAULT_OPTIONS = {
596       :root_path => File.join(RAILS_ROOT, "public"),
597       :web_root => "",
598       :mime_extensions => MIME_EXTENSIONS,
599       :extensions => EXTENSIONS,
600       :fix_file_extensions => true,
601       :permissions => 0644,
602
603       # path to the unix "file" executbale for
604       # guessing the content-type of files
605       :file_exec => "file" 
606     }
607     
608     # handle the +attr+ attribute as a "file-upload" column, generating additional methods as explained
609     # above. You should pass the attribute's name as a symbol, like this:
610     #
611     #   file_column :image
612     #
613     # You can pass in an options hash that overrides the options
614     # in +DEFAULT_OPTIONS+.
615     def file_column(attr, options={})
616       options = DEFAULT_OPTIONS.merge(options) if options
617       
618       my_options = FileColumn::init_options(options, 
619         ActiveSupport::Inflector.underscore(self.name).to_s,
620                                             attr.to_s)
621       
622       state_attr = "@#{attr}_state".to_sym
623       state_method = "#{attr}_state".to_sym
624       
625       define_method state_method do
626         result = instance_variable_get state_attr
627         if result.nil?
628           result = FileColumn::create_state(self, attr.to_s)
629           instance_variable_set state_attr, result
630         end
631         result
632       end
633       
634       private state_method
635       
636       define_method attr do |*args|
637         send(state_method).absolute_path *args
638       end
639       
640       define_method "#{attr}_relative_path" do |*args|
641         send(state_method).relative_path *args
642       end
643
644       define_method "#{attr}_dir" do
645         send(state_method).absolute_dir
646       end
647
648       define_method "#{attr}_relative_dir" do
649         send(state_method).relative_dir
650       end
651
652       define_method "#{attr}=" do |file|
653         state = send(state_method).assign(file)
654         instance_variable_set state_attr, state
655         if state.options[:after_upload] and state.just_uploaded?
656           state.options[:after_upload].each do |sym|
657             self.send sym
658           end
659         end
660       end
661       
662       define_method "#{attr}_temp" do
663         send(state_method).temp_path
664       end
665       
666       define_method "#{attr}_temp=" do |temp_path|
667         instance_variable_set state_attr, send(state_method).assign_temp(temp_path)
668       end
669       
670       after_save_method = "#{attr}_after_save".to_sym
671       
672       define_method after_save_method do
673         instance_variable_set state_attr, send(state_method).after_save
674       end
675       
676       after_save after_save_method
677       
678       after_destroy_method = "#{attr}_after_destroy".to_sym
679       
680       define_method after_destroy_method do
681         send(state_method).after_destroy
682       end
683       after_destroy after_destroy_method
684       
685       define_method "#{attr}_just_uploaded?" do
686         send(state_method).just_uploaded?
687       end
688
689       # this creates a closure keeping a reference to my_options
690       # right now that's the only way we store the options. We
691       # might use a class attribute as well
692       define_method "#{attr}_options" do
693         my_options
694       end
695
696       private after_save_method, after_destroy_method
697
698       FileColumn::MagickExtension::file_column(self, attr, my_options) if options[:magick]
699     end
700     
701   end
702   
703   private
704   
705   def self.generate_temp_name
706     now = Time.now
707     "#{now.to_i}.#{now.usec}.#{Process.pid}"
708   end
709   
710   def self.sanitize_filename(filename)
711     filename = File.basename(filename.gsub("\\", "/")) # work-around for IE
712     filename.gsub!(/[^a-zA-Z0-9\.\-\+_]/,"_")
713     filename = "_#{filename}" if filename =~ /^\.+$/
714     filename = "unnamed" if filename.size == 0
715     filename
716   end
717   
718 end
719
720