durran-carrierwave 0.3.2.3 → 0.4.3

data/Generators

@@ -1,4 +1,4 @@
 scope 'merb-gen' do
-  dir = File.join(File.dirname(__FILE__), 'lib', 'generators/')
+  dir = File.join(File.dirname(__FILE__), 'merb_generators/')
   Merb.add_generators dir + 'uploader_generator'
 end

data/History.txt

@@ -1,5 +1,42 @@
-=== Version 0.3.2.3 2009-08-28
-* Added support for MongoMapper
+=== Version 0.4.2 2009-11-26
+
+* [added] RightAWS as an alternative S3 implementation
+* [added] An option to enable/disable processing for tests
+* [added] Mongoid ORM support
+* [fixed] DataMapper now works both with and without dm-validations
+
+=== Version 0.4.1 2009-10-26
+
+* [changed] Major changes to the ImageScience module, it actually works now!
+* [fixed] Bug in configuration where it complais that it can't dup Symbol
+
+* [removed] Support for Sequel < 2.12
+* [removed] `crop_resized` and `resize` aliases in RMagick, use `resize_to_fill` and `resize_to_fit` respectively
+
+=== Version 0.4.0 2009-10-12
+
+* [changed] the `public` option has been renamed `root` and the old `root` option was removed. No more ambiguity.
+* [changed] Major *breaking* changes to the configuration syntax.
+
+* [removed] support for `default_path`
+* [removed] the `cache_to_cache_dir` option
+* [removed] storage no longer calls `setup!` on storage engines
+
+* [added] Support for MongoDB's GridFS store
+
+=== Version 0.3.4 2009-09-01
+
+* [added] `default_url` as a replacement for `default_path`
+* [deprecated] `default_path` is deprecated
+
+=== Version 0.3.4 2009-08-31
+
+* [fixed] Deleting no longer causes TypeError in MongoMapper
+
+=== Version 0.3.3 2009-08-29
+
+* [added] Support for MongoMapper
+* [added] Support for CNamed Bucket URLs for Amazon S3
 
 === Version 0.3.2 2009-07-18
 

data/Manifest.txt

@@ -3,7 +3,6 @@ History.txt
 Manifest.txt
 README.rdoc
 Rakefile
-carrierwave.gemspec
 cucumber.yml
 features/caching.feature
 features/file_storage.feature
@@ -12,6 +11,7 @@ features/file_storage_overridden_store_dir.feature
 features/file_storage_reversing_processor.feature
 features/fixtures/bork.txt
 features/fixtures/monkey.txt
+features/grid_fs_storage.feature
 features/mount_activerecord.feature
 features/mount_datamapper.feature
 features/step_definitions/activerecord_steps.rb
@@ -36,29 +36,33 @@ lib/carrierwave/core_ext/module_setup.rb
 lib/carrierwave/mount.rb
 lib/carrierwave/orm/activerecord.rb
 lib/carrierwave/orm/datamapper.rb
+lib/carrierwave/orm/mongoid.rb
 lib/carrierwave/orm/mongomapper.rb
 lib/carrierwave/orm/sequel.rb
 lib/carrierwave/processing/image_science.rb
+lib/carrierwave/processing/mini_magick.rb
 lib/carrierwave/processing/rmagick.rb
 lib/carrierwave/sanitized_file.rb
 lib/carrierwave/storage/abstract.rb
 lib/carrierwave/storage/file.rb
+lib/carrierwave/storage/grid_fs.rb
+lib/carrierwave/storage/right_s3.rb
 lib/carrierwave/storage/s3.rb
 lib/carrierwave/test/matchers.rb
 lib/carrierwave/uploader.rb
 lib/carrierwave/uploader/cache.rb
 lib/carrierwave/uploader/callbacks.rb
-lib/carrierwave/uploader/default_path.rb
+lib/carrierwave/uploader/configuration.rb
+lib/carrierwave/uploader/default_url.rb
 lib/carrierwave/uploader/extension_whitelist.rb
 lib/carrierwave/uploader/mountable.rb
-lib/carrierwave/uploader/paths.rb
 lib/carrierwave/uploader/processing.rb
 lib/carrierwave/uploader/proxy.rb
 lib/carrierwave/uploader/remove.rb
 lib/carrierwave/uploader/store.rb
 lib/carrierwave/uploader/url.rb
 lib/carrierwave/uploader/versions.rb
-lib/generators/uploader_generator.rb
+merb_generators/uploader_generator.rb
 rails_generators/uploader/USAGE
 rails_generators/uploader/templates/uploader.rb
 rails_generators/uploader/uploader_generator.rb
@@ -67,17 +71,27 @@ script/destroy
 script/generate
 spec/compatibility/paperclip_spec.rb
 spec/fixtures/bork.txt
+spec/fixtures/landscape.jpg
+spec/fixtures/portrait.jpg
 spec/fixtures/test.jpeg
 spec/fixtures/test.jpg
 spec/mount_spec.rb
 spec/orm/activerecord_spec.rb
 spec/orm/datamapper_spec.rb
+spec/orm/mongoid_spec.rb
 spec/orm/mongomapper_spec.rb
 spec/orm/sequel_spec.rb
+spec/processing/image_science_spec.rb
+spec/processing/mini_magick_spec.rb
+spec/processing/rmagick_spec.rb
 spec/sanitized_file_spec.rb
 spec/spec_helper.rb
+spec/storage/grid_fs_spec.rb
+spec/storage/right_s3_spec.rb
+spec/storage/s3_spec.rb
 spec/uploader/cache_spec.rb
-spec/uploader/default_path_spec.rb
+spec/uploader/configuration_spec.rb
+spec/uploader/default_url_spec.rb
 spec/uploader/extension_whitelist_spec.rb
 spec/uploader/mountable_spec.rb
 spec/uploader/paths_spec.rb

data/README.rdoc

@@ -9,7 +9,7 @@ upload files.
 
 == Description
 
-* RDoc Documentation {available at Rubyforge}[http://carrierwave.rubyforge.org/].
+* RDoc Documentation {available at Rubyforge}[http://carrierwave.rubyforge.org/rdoc].
 * Source code {hosted at GitHub}[http://github.com/jnicklas/carrierwave]
 * Please {report any issues}[http://github.com/jnicklas/carrierwave/issues] on GitHub
 * Please direct any questions at the {mailing list}[http://groups.google.com/group/carrierwave]
@@ -20,12 +20,10 @@ Install the latest stable release:
 
     [sudo] gem install carrierwave
 
-Or the cutting edge development version:
-
-    [sudo] gem install jnicklas-carrierwave --source http://gems.github.com
+CarrierWave is hosted *only* on {Gemcutter}[http://gemcutter.org] as of version 0.4.0.
 
 In Merb, add it as a dependency to your config/dependencies.rb:
-    
+
     dependency 'carrierwave'
 
 In Rails, add it to your environment.rb:
@@ -56,14 +54,14 @@ should look something like this:
 You can use your uploader class to store and retrieve files like this:
 
     uploader = AvatarUploader.new
-    
+
     uploader.store!(my_file)
-    
+
     uploader.retrieve_from_store!('my_file.png')
 
 CarrierWave gives you a +store+ for permanent storage, and a +cache+ for
 temporary storage. You can use different stores, at the moment a filesystem
-store and an Amazon S3 store are bundled.
+store, an Amazon S3 store and a store for MongoDB's GridFS are bundled.
 
 Most of the time you are going to want to use CarrierWave together with an ORM.
 It is quite simple to mount uploaders on columns in your model, so you can
@@ -71,33 +69,22 @@ simply assign files and get going:
 
 === ActiveRecord, DataMapper, Sequel, MongoMapper
 
-If you are *not* using Merb or Rails you'll need to require the relevant ORM
-extension.
+Make sure you are loading CarrierWave after loading your ORM, otherwise you'll
+need to require the relevant extension manually, e.g.:
 
     require 'carrierwave/orm/activerecord'
-    require 'carrierwave/orm/datamapper'
-    require 'carrierwave/orm/sequel'
-    require 'carrierwave/orm/mongomapper'
 
-Open your model file, for ActiveRecord do something like:
+Add a string column to the model you want to mount the uploader on:
 
-    class User < ActiveRecord::Base
-      mount_uploader :avatar, AvatarUploader
-    end
+    add_column :user, :avatar, :string
 
-Or for DataMapper:
+Open your model file and mount the uploader:
 
     class User
-      include DataMapper::Resource
-
       mount_uploader :avatar, AvatarUploader
     end
 
-Or for Sequel
-
-    class User < Sequel::Model
-      mount_uploader :avatar, AvatarUploader
-    end
+This works the same with all supported ORMs.
 
 Now you can cache files by assigning them to the attribute, they will
 automatically be stored when the record is saved.
@@ -122,6 +109,18 @@ method:
 
 This works for the file storage as well as Amazon S3.
 
+== Securing uploads
+
+Certain file might be dangerous if uploaded to the wrong location, such as php files or other script files. CarrierWave allows you to specify a white-list of allowed extensions.
+
+If you're mounting the uploader, uploading a file with the wrong extension will make the record invalid instead. Otherwise, an error is raised.
+
+    class MyUploader < CarrierWave::Uploader::Base
+      def extension_white_list
+        %w(jpg jpeg gif png)
+      end
+    end
+
 == Adding versions
 
 Often you'll want to add different versions of the same file. The classic
@@ -130,12 +129,12 @@ example is image thumbnails. There is built in support for this:
     class MyUploader < CarrierWave::Uploader::Base
       include CarrierWave::RMagick
 
-      process :resize => [800, 800]
+      process :resize_to_fit => [800, 800]
 
       version :thumb do
-        process :crop_resized => [200,200]
+        process :resize_to_fill => [200,200]
       end
-      
+
     end
 
 When this uploader is used, an uploaded image would be scaled to be no larger
@@ -144,7 +143,7 @@ and cropped to exactly 200 by 200 pixels. The uploader could be used like this:
 
     uploader = AvatarUploader.new
     uploader.store!(my_file)                              # size: 1024x768
-    
+
     uploader.url # => '/url/to/my_file.png'               # size: 800x600
     uploader.thumb.url # => '/url/to/thumb_my_file.png'   # size: 200x200
 
@@ -178,7 +177,7 @@ like this:
       </p>
     <% end %>
 
-It might be a good idea to show th user that a file has been uploaded, in the
+It might be a good idea to show the user that a file has been uploaded, in the
 case of images, a small thumbnail would be a good indicator:
 
     <% form_for @user do |f| %>
@@ -190,21 +189,79 @@ case of images, a small thumbnail would be a good indicator:
       </p>
     <% end %>
 
-NOTE: this feature currently requires write access to your filesystem. If write
-access is unavailable you will not be able to upload files. You can prevent
-CarrierWave from writing to the file system by setting
-`CarrierWave.config[:cache_to_cache_dir] = false`. This will however break
-redisplays of forms.
-
-== Providing a default path
+== Providing a default URL
 
 In many cases, especially when working with images, it might be a good idea to
-provide a default path, a fallback in case no file has been uploaded. You can do
-this easily by overriding the +default_path+ method in your uploader:
+provide a default url, a fallback in case no file has been uploaded. You can do
+this easily by overriding the +default_url+ method in your uploader:
 
     class MyUploader < CarrierWave::Uploader::Base
-      def default_path
-        "images/fallback/" + [version_name, "default.png"].compact.join('_')
+      def default_url
+        "/images/fallback/" + [version_name, "default.png"].compact.join('_')
+      end
+    end
+
+== Configuring CarrierWave
+
+CarrierWave has a broad range of configuration options, which you can configure,
+both globally and on a per-uploader basis:
+
+    CarrierWave.configure do |config|
+      config.permissions = 0666
+      config.storage = :s3
+    end
+
+Or alternatively:
+
+    class AvatarUploader < CarrierWave::Uploader::Base
+      permissions 0777
+    end
+
+== Testing CarrierWave
+
+It's a good idea to test you uploaders in isolation. In order to speed up your
+tests, it's recommended to switch off processing in your tests, and to use the
+file storage. In Rails you could do that by adding an initializer with:
+
+    if Rails.env.test?
+      Carrierwave.configure do |config|
+        config.storage = :file
+        config.enable_processing = false
+      end
+    end
+
+If you need to test your processing, you should test it in isolation, and enable
+processing only for those tests that need it.
+
+CarrierWave comes with some RSpec matchers which you may find useful:
+
+    require 'carrierwave/test/matchers'
+
+    describe MyUploader do
+      before do
+        MyUploader.enable_processing = true
+        @uploader = MyUploader.new(@user, :avatar)
+        @uploader.store!(File.open(path_to_file))
+      end
+
+      after do
+        MyUploader.enable_processing = false
+      end
+
+      context 'the thumb version' do
+        it "should scale down a landscape image to be exactly 64 by 64 pixels" do
+          @uploader.thumb.should have_dimensions(200, 200)
+        end
+      end
+
+      context 'the small version' do
+        it "should scale down a landscape image to fit within 200 by 200 pixels" do
+          @uploader.small.should be_no_larger_than(200, 200)
+        end
+      end
+
+      it "should make the image readable only to the owner and not executable" do
+        @uploader.should have_premissions(0600)
       end
     end
 
@@ -212,20 +269,59 @@ this easily by overriding the +default_path+ method in your uploader:
 
 You'll need to configure a bucket, access id and secret key like this:
 
-    CarrierWave.config[:s3][:access_key_id] = 'xxxxxx'
-    CarrierWave.config[:s3][:secret_access_key] = 'xxxxxx'
-    CarrierWave.config[:s3][:bucket] = 'name_of_bucket'
+    CarrierWave.configure do |config|
+      config.s3_access_key_id = 'xxxxxx'
+      config.s3_secret_access_key = 'xxxxxx'
+      config.s3_bucket = 'name_of_bucket'
+    end
 
 Do this in an initializer in Rails, and in a +before_app_loads+ block in Merb.
 
 And then in your uploader, set the storage to :s3
 
-    class AvatarUploader < 
+    class AvatarUploader < CarrierWave::Uploader::Base
       storage :s3
     end
 
 That's it! You can still use the +CarrierWave::Uploader#url+ method to return
-the url to the file on Amazon S3
+the url to the file on Amazon S3.
+
+Alternatively, and especially if your bucket is located in Europe, you can use the
+RightAWS library by setting the storage to :right_s3
+
+    class AvatarUploader < CarrierWave::Uploader::Base
+      storage :right_s3
+    end
+
+CarrierWave uses the RightAWS S3 Interface directly, meaning that the performance issues
+mentioned by Jonathan Yurek for paperclip do not apply: http://groups.google.com/group/paperclip-plugin/browse_thread/thread/d4dc166a9a5f0df4#
+
+
+== Using MongoDB's GridFS store
+
+You'll need to configure the database and host to use:
+
+    CarrierWave.configure do |config|
+      config.grid_fs_database = 'my_mongo_database'
+      config.grid_fs_host = 'mongo.example.com'
+    end
+
+The defaults are 'carrierwave' and 'localhost'.
+
+And then in your uploader, set the storage to +:grid_fs+:
+
+    class AvatarUploader < CarrierWave::Uploader::Base
+      storage :grid_fs
+    end
+
+Since GridFS doesn't make the files available via HTTP, you'll need to stream
+them yourself. In Rails for example, you could use the +send_data+ method. You
+can tell CarrierWave the URL you will serve your images from, allowing it to
+generate the correct URL, by setting eg:
+
+    CarrierWave.configure do |config|
+      config.grid_fs_access_url = "/image/show"
+    end
 
 == Using RMagick
 
@@ -239,16 +335,16 @@ include it in your Uploader:
     end
 
 The RMagick module gives you a few methods, like
-+CarrierWave::RMagick#crop_resized+ which manipulate the image file in some way.
-You can set a +process+ callback, which will call that method any time a file is
-uploaded.
++CarrierWave::RMagick#resize_to_fill+ which manipulate the image file in some
+way. You can set a +process+ callback, which will call that method any time a
+file is uploaded.
 
     class AvatarUploader < CarrierWave::Uploader::Base
       include CarrierWave::RMagick
-      
-      process :crop_resized => [200, 200]
+
+      process :resize_to_fill => [200, 200]
       process :convert => 'png'
-      
+
       def filename
         super + '.png'
       end
@@ -263,8 +359,31 @@ ImageScience works the same way as RMagick.
 
     class AvatarUploader < CarrierWave::Uploader::Base
       include CarrierWave::ImageScience
-      
-      process :crop_resized => [200, 200]
+
+      process :resize_to_fill => [200, 200]
+    end
+
+== Using MiniMagick
+
+MiniMagick is similar to RMagick but performs all the operations using the 'mogrify'
+command which is part of the standard ImageMagick kit. This allows you to have the power
+of ImageMagick without having to worry about installing all the RMagick libraries.
+
+See the MiniMagick site for more details:
+
+http://github.com/probablycorey/mini_magick
+
+And the ImageMagick command line options for more for whats on offer:
+
+http://www.imagemagick.org/script/command-line-options.php
+
+Currently, the MiniMagick carrierwave processor provides exactly the same methods as
+for the RMagick processor.
+
+    class AvatarUploader < CarrierWave::Uploader::Base
+      include CarrierWave::MiniMagick
+
+      process :resize_to_fill => [200, 200]
     end
 
 == Migrating
@@ -303,6 +422,12 @@ These people have contributed their time and effort to CarrierWave:
 * Jonas Nicklas
 * Pavel Kunc
 * Andrew Timberlake
+* Durran Jordan
+* Scott Motte
+* Sho Fukamachi
+* Sam Lown
+* Dave Ott
+* Quin Hoxie
 
 == License
 
@@ -339,4 +464,4 @@ extensively specced, and there are cucumber features for some common use cases.
 Just dig in and look at the source for more in-depth explanation of what things
 are doing.
 
-Issues are reported on GitHub, pull requests are very welcome!
+Issues are reported on GitHub, pull requests are very welcome!