carrierwave 0.11.2 → 1.3.2

Sign up to get free protection for your applications and to get access to all the features.

Potentially problematic release.


This version of carrierwave might be problematic. Click here for more details.

Files changed (58) hide show
  1. checksums.yaml +5 -5
  2. data/README.md +255 -125
  3. data/lib/carrierwave/compatibility/paperclip.rb +0 -2
  4. data/lib/carrierwave/error.rb +1 -0
  5. data/lib/carrierwave/locale/en.yml +7 -4
  6. data/lib/carrierwave/mount.rb +219 -176
  7. data/lib/carrierwave/mounter.rb +165 -0
  8. data/lib/carrierwave/orm/activerecord.rb +50 -21
  9. data/lib/carrierwave/processing/mini_magick.rb +86 -15
  10. data/lib/carrierwave/processing/rmagick.rb +63 -8
  11. data/lib/carrierwave/processing.rb +0 -1
  12. data/lib/carrierwave/sanitized_file.rb +51 -46
  13. data/lib/carrierwave/storage/abstract.rb +15 -2
  14. data/lib/carrierwave/storage/file.rb +69 -2
  15. data/lib/carrierwave/storage/fog.rb +152 -33
  16. data/lib/carrierwave/storage.rb +0 -9
  17. data/lib/carrierwave/test/matchers.rb +77 -12
  18. data/lib/carrierwave/uploader/cache.rb +41 -27
  19. data/lib/carrierwave/uploader/callbacks.rb +0 -2
  20. data/lib/carrierwave/uploader/configuration.rb +54 -9
  21. data/lib/carrierwave/uploader/content_type_whitelist.rb +1 -1
  22. data/lib/carrierwave/uploader/default_url.rb +3 -5
  23. data/lib/carrierwave/uploader/download.rb +66 -15
  24. data/lib/carrierwave/uploader/extension_blacklist.rb +14 -10
  25. data/lib/carrierwave/uploader/extension_whitelist.rb +13 -10
  26. data/lib/carrierwave/uploader/file_size.rb +43 -0
  27. data/lib/carrierwave/uploader/mountable.rb +7 -8
  28. data/lib/carrierwave/uploader/processing.rb +10 -10
  29. data/lib/carrierwave/uploader/proxy.rb +5 -7
  30. data/lib/carrierwave/uploader/remove.rb +0 -2
  31. data/lib/carrierwave/uploader/serialization.rb +1 -3
  32. data/lib/carrierwave/uploader/store.rb +14 -23
  33. data/lib/carrierwave/uploader/url.rb +3 -5
  34. data/lib/carrierwave/uploader/versions.rb +82 -82
  35. data/lib/carrierwave/uploader.rb +11 -2
  36. data/lib/carrierwave/utilities/uri.rb +5 -6
  37. data/lib/carrierwave/utilities.rb +0 -3
  38. data/lib/carrierwave/validations/active_model.rb +3 -5
  39. data/lib/carrierwave/version.rb +1 -1
  40. data/lib/carrierwave.rb +32 -10
  41. data/lib/generators/templates/uploader.rb +4 -8
  42. metadata +64 -79
  43. data/lib/carrierwave/locale/cs.yml +0 -11
  44. data/lib/carrierwave/locale/de.yml +0 -11
  45. data/lib/carrierwave/locale/el.yml +0 -11
  46. data/lib/carrierwave/locale/es.yml +0 -11
  47. data/lib/carrierwave/locale/fr.yml +0 -11
  48. data/lib/carrierwave/locale/ja.yml +0 -11
  49. data/lib/carrierwave/locale/nb.yml +0 -11
  50. data/lib/carrierwave/locale/nl.yml +0 -11
  51. data/lib/carrierwave/locale/pl.yml +0 -11
  52. data/lib/carrierwave/locale/pt-BR.yml +0 -11
  53. data/lib/carrierwave/locale/pt-PT.yml +0 -11
  54. data/lib/carrierwave/locale/ru.yml +0 -11
  55. data/lib/carrierwave/locale/sk.yml +0 -11
  56. data/lib/carrierwave/locale/tr.yml +0 -11
  57. data/lib/carrierwave/processing/mime_types.rb +0 -74
  58. data/lib/carrierwave/utilities/deprecation.rb +0 -18
data/README.md CHANGED
@@ -3,8 +3,10 @@
3
3
  This gem provides a simple and extremely flexible way to upload files from Ruby applications.
4
4
  It works well with Rack based web applications, such as Ruby on Rails.
5
5
 
6
- [![Build Status](https://travis-ci.org/carrierwaveuploader/carrierwave.png?branch=master)](http://travis-ci.org/carrierwaveuploader/carrierwave)
7
- [![Code Climate](https://codeclimate.com/github/carrierwaveuploader/carrierwave.png)](https://codeclimate.com/github/carrierwaveuploader/carrierwave)
6
+ [![Build Status](https://travis-ci.org/carrierwaveuploader/carrierwave.svg?branch=master)](http://travis-ci.org/carrierwaveuploader/carrierwave)
7
+ [![Code Climate](https://codeclimate.com/github/carrierwaveuploader/carrierwave.svg)](https://codeclimate.com/github/carrierwaveuploader/carrierwave)
8
+ [![SemVer](https://api.dependabot.com/badges/compatibility_score?dependency-name=carrierwave&package-manager=bundler&version-scheme=semver)](https://dependabot.com/compatibility-score.html?dependency-name=carrierwave&package-manager=bundler&version-scheme=semver)
9
+
8
10
 
9
11
  ## Information
10
12
 
@@ -14,25 +16,27 @@ It works well with Rack based web applications, such as Ruby on Rails.
14
16
 
15
17
  ## Getting Help
16
18
 
17
- * Please ask the [Google Group](http://groups.google.com/group/carrierwave) for help if you have any questions.
19
+ * Please ask the community on [Stack Overflow](https://stackoverflow.com/questions/tagged/carrierwave) for help if you have any questions. Please do not post usage questions on the issue tracker.
18
20
  * Please report bugs on the [issue tracker](http://github.com/carrierwaveuploader/carrierwave/issues) but read the "getting help" section in the wiki first.
19
21
 
20
22
  ## Installation
21
23
 
22
- Install the latest stable release:
24
+ Install the latest release:
23
25
 
24
- [sudo] gem install carrierwave
26
+ ```
27
+ $ gem install carrierwave
28
+ ```
25
29
 
26
30
  In Rails, add it to your Gemfile:
27
31
 
28
32
  ```ruby
29
- gem 'carrierwave'
33
+ gem 'carrierwave', '~> 1.0'
30
34
  ```
31
35
 
32
36
  Finally, restart the server to apply the changes.
33
37
 
34
- Note that CarrierWave is not compatible with Rails 2 as of version 0.5. If you want to use
35
- Rails 2, please use the 0.4-stable branch on GitHub.
38
+ As of version 1.0, CarrierWave requires Rails 4.0 or higher and Ruby 2.0
39
+ or higher. If you're on Rails 3, you should use v0.11.0.
36
40
 
37
41
  ## Getting Started
38
42
 
@@ -85,7 +89,7 @@ a migration:
85
89
 
86
90
 
87
91
  rails g migration add_avatar_to_users avatar:string
88
- rake db:migrate
92
+ rails db:migrate
89
93
 
90
94
  Open your model file and mount the uploader:
91
95
 
@@ -100,24 +104,92 @@ automatically be stored when the record is saved.
100
104
 
101
105
  ```ruby
102
106
  u = User.new
103
- u.avatar = params[:file]
104
- u.avatar = File.open('somewhere')
107
+ u.avatar = params[:file] # Assign a file like this, or
108
+
109
+ # like this
110
+ File.open('somewhere') do |f|
111
+ u.avatar = f
112
+ end
113
+
105
114
  u.save!
106
115
  u.avatar.url # => '/url/to/file.png'
107
116
  u.avatar.current_path # => 'path/to/file.png'
108
- u.avatar.identifier # => 'file.png'
117
+ u.avatar_identifier # => 'file.png'
109
118
  ```
110
119
 
120
+ **Note**: `u.avatar` will never return nil, even if there is no photo associated to it.
121
+ To check if a photo was saved to the model, use `u.avatar.file.nil?` instead.
122
+
111
123
  ### DataMapper, Mongoid, Sequel
112
124
 
113
125
  Other ORM support has been extracted into separate gems:
114
126
 
115
127
  * [carrierwave-datamapper](https://github.com/carrierwaveuploader/carrierwave-datamapper)
116
128
  * [carrierwave-mongoid](https://github.com/carrierwaveuploader/carrierwave-mongoid)
117
- * [carrierwave-sequel](https://github.com/jnicklas/carrierwave-sequel)
129
+ * [carrierwave-sequel](https://github.com/carrierwaveuploader/carrierwave-sequel)
118
130
 
119
131
  There are more extensions listed in [the wiki](https://github.com/carrierwaveuploader/carrierwave/wiki)
120
132
 
133
+ ## Multiple file uploads
134
+
135
+ CarrierWave also has convenient support for multiple file upload fields.
136
+
137
+ ### ActiveRecord
138
+
139
+ Add a column which can store an array. This could be an array column or a JSON
140
+ column for example. Your choice depends on what your database supports. For
141
+ example, create a migration like this:
142
+
143
+
144
+ #### For databases with ActiveRecord json data type support (e.g. PostgreSQL, MySQL)
145
+
146
+ rails g migration add_avatars_to_users avatars:json
147
+ rails db:migrate
148
+
149
+ #### For database without ActiveRecord json data type support (e.g. SQLite)
150
+
151
+ rails g migration add_avatars_to_users avatars:string
152
+ rails db:migrate
153
+
154
+ __Note__: JSON datatype doesn't exists in SQLite adapter, that's why you can use a string datatype which will be serialized in model.
155
+
156
+ Open your model file and mount the uploader:
157
+
158
+
159
+ ```ruby
160
+ class User < ActiveRecord::Base
161
+ mount_uploaders :avatars, AvatarUploader
162
+ serialize :avatars, JSON # If you use SQLite, add this line.
163
+ end
164
+ ```
165
+
166
+ Make sure that you mount the uploader with write (mount_uploaders) with `s` not (mount_uploader)
167
+ in order to avoid errors when uploading multiple files
168
+
169
+ Make sure your file input fields are set up as multiple file fields. For
170
+ example in Rails you'll want to do something like this:
171
+
172
+ ```erb
173
+ <%= form.file_field :avatars, multiple: true %>
174
+ ```
175
+
176
+ Also, make sure your upload controller permits the multiple file upload attribute, *pointing to an empty array in a hash*. For example:
177
+
178
+ ```ruby
179
+ params.require(:user).permit(:email, :first_name, :last_name, {avatars: []})
180
+ ```
181
+
182
+ Now you can select multiple files in the upload dialog (e.g. SHIFT+SELECT), and they will
183
+ automatically be stored when the record is saved.
184
+
185
+ ```ruby
186
+ u = User.new(params[:user])
187
+ u.save!
188
+ u.avatars[0].url # => '/url/to/file.png'
189
+ u.avatars[0].current_path # => 'path/to/file.png'
190
+ u.avatars[0].identifier # => 'file.png'
191
+ ```
192
+
121
193
  ## Changing the storage directory
122
194
 
123
195
  In order to change where uploaded files are put, just override the `store_dir`
@@ -146,85 +218,69 @@ end
146
218
 
147
219
  ## Securing uploads
148
220
 
149
- Certain file might be dangerous if uploaded to the wrong location, such as php
150
- files or other script files. CarrierWave allows you to specify a white-list of
151
- allowed extensions.
221
+ Certain files might be dangerous if uploaded to the wrong location, such as PHP
222
+ files or other script files. CarrierWave allows you to specify a whitelist of
223
+ allowed extensions or content types.
152
224
 
153
225
  If you're mounting the uploader, uploading a file with the wrong extension will
154
226
  make the record invalid instead. Otherwise, an error is raised.
155
227
 
156
228
  ```ruby
157
229
  class MyUploader < CarrierWave::Uploader::Base
158
- def extension_white_list
230
+ def extension_whitelist
159
231
  %w(jpg jpeg gif png)
160
232
  end
161
233
  end
162
234
  ```
163
235
 
164
- ### CVE-2016-3714 (ImageTragick)
165
- This version of CarrierWave has the ability to mitigate CVE-2016-3714. However, you **MUST** set a `content_type_whitelist` in your uploaders for this protection to be effective, and you **MUST** either disable ImageMagick's default SVG delegate or use the RSVG delegate for SVG processing.
166
-
167
- A valid whitelist that will restrict your uploader to images only, and mitigate the CVE is:
236
+ The same thing could be done using content types.
237
+ Let's say we need an uploader that accepts only images. This can be done like this
168
238
 
169
239
  ```ruby
170
240
  class MyUploader < CarrierWave::Uploader::Base
171
241
  def content_type_whitelist
172
- [/image\//]
242
+ /image\//
173
243
  end
174
244
  end
175
245
  ```
176
246
 
177
- **WARNING**: A `content_type_whitelist` is the only form of whitelist or blacklist supported by CarrierWave that can effectively mitigate against CVE-2016-3714. Use of `extension_type_whitelist` will not inspect the file headers, and thus still leaves your application open to the vulnerability.
247
+ You can use a blacklist to reject content types.
248
+ Let's say we need an uploader that reject JSON files. This can be done like this
178
249
 
250
+ ```ruby
251
+ class NoJsonUploader < CarrierWave::Uploader::Base
252
+ def content_type_blacklist
253
+ ['application/text', 'application/json']
254
+ end
255
+ end
256
+ ```
179
257
 
180
258
  ### Filenames and unicode chars
181
259
 
182
260
  Another security issue you should care for is the file names (see
183
261
  [Ruby On Rails Security Guide](http://guides.rubyonrails.org/security.html#file-uploads)).
184
- By default, CarrierWave provides only English letters, arabic numerals and '-+_.' symbols as
262
+ By default, CarrierWave provides only English letters, arabic numerals and some symbols as
185
263
  white-listed characters in the file name. If you want to support local scripts (Cyrillic letters, letters with diacritics and so on), you
186
264
  have to override `sanitize_regexp` method. It should return regular expression which would match
187
265
  all *non*-allowed symbols.
188
266
 
189
- With Ruby 1.9 and higher you can simply write (as it has [Oniguruma](http://oniguruma.rubyforge.org/oniguruma/)
190
- built-in):
191
-
192
267
  ```ruby
193
268
  CarrierWave::SanitizedFile.sanitize_regexp = /[^[:word:]\.\-\+]/
194
269
  ```
195
270
 
196
- With Ruby 1.8 you have to manually specify all character ranges. For example, for files which may
197
- contain Russian letters:
198
-
199
- ```ruby
200
- CarrierWave::SanitizedFile.sanitize_regexp = /[^a-zA-Zа-яА-ЯёЁ0-9\.\-\+_]/u
201
- ```
202
-
203
271
  Also make sure that allowing non-latin characters won't cause a compatibility issue with a third-party
204
272
  plugins or client-side software.
205
273
 
206
274
  ## Setting the content type
207
275
 
208
- If you care about the content type of your files and notice that it's not being set
209
- as expected, you can configure your uploaders to use `CarrierWave::MimeTypes`.
210
- This adds a dependency on the [mime-types](http://rubygems.org/gems/mime-types) gem,
211
- but is recommended when using fog, and fog already has a dependency on mime-types.
212
-
213
- ```ruby
214
- require 'carrierwave/processing/mime_types'
215
-
216
- class MyUploader < CarrierWave::Uploader::Base
217
- include CarrierWave::MimeTypes
218
-
219
- process :set_content_type
220
- end
221
- ```
276
+ As of v0.11.0, the `mime-types` gem is a runtime dependency and the content type is set automatically.
277
+ You no longer need to do this manually.
222
278
 
223
279
  ## Adding versions
224
280
 
225
281
  Often you'll want to add different versions of the same file. The classic example is image thumbnails. There is built in support for this*:
226
282
 
227
- *Note: You must have Imagemagick and MiniMagick installed to do image resizing. MiniMagick is a Ruby interface for Imagemagick which is a C program. This is why MiniMagick fails on 'bundle install' without Imagemagick installed.
283
+ *Note:* You must have Imagemagick and MiniMagick installed to do image resizing. MiniMagick is a Ruby interface for Imagemagick which is a C program. This is why MiniMagick fails on 'bundle install' without Imagemagick installed.
228
284
 
229
285
  Some documentation refers to RMagick instead of MiniMagick but MiniMagick is recommended.
230
286
 
@@ -238,24 +294,32 @@ $ brew install imagemagick
238
294
  class MyUploader < CarrierWave::Uploader::Base
239
295
  include CarrierWave::MiniMagick
240
296
 
241
- process :resize_to_fit => [800, 800]
297
+ process resize_to_fit: [800, 800]
242
298
 
243
299
  version :thumb do
244
- process :resize_to_fill => [200,200]
300
+ process resize_to_fill: [200,200]
245
301
  end
246
302
 
247
303
  end
248
304
  ```
249
305
 
250
306
  When this uploader is used, an uploaded image would be scaled to be no larger
251
- than 800 by 800 pixels. A version called thumb is then created, which is scaled
252
- and cropped to exactly 200 by 200 pixels. The uploader could be used like this:
307
+ than 800 by 800 pixels. The original aspect ratio will be kept.
308
+ A version called thumb is then created, which is scaled
309
+ to exactly 200 by 200 pixels.
310
+
311
+ If you would like to crop images to a specific height and width you
312
+ can use the alternative option of '''resize_to_fill'''. It will make sure
313
+ that the width and height specified are filled, only cropping
314
+ if the aspect ratio requires it.
315
+
316
+ The uploader could be used like this:
253
317
 
254
318
  ```ruby
255
319
  uploader = AvatarUploader.new
256
320
  uploader.store!(my_file) # size: 1024x768
257
321
 
258
- uploader.url # => '/url/to/my_file.png' # size: 800x600
322
+ uploader.url # => '/url/to/my_file.png' # size: 800x800
259
323
  uploader.thumb.url # => '/url/to/thumb_my_file.png' # size: 200x200
260
324
  ```
261
325
 
@@ -283,11 +347,11 @@ properties within the model or based on the picture itself.
283
347
  ```ruby
284
348
  class MyUploader < CarrierWave::Uploader::Base
285
349
 
286
- version :human, :if => :is_human?
287
- version :monkey, :if => :is_monkey?
288
- version :banner, :if => :is_landscape?
350
+ version :human, if: :is_human?
351
+ version :monkey, if: :is_monkey?
352
+ version :banner, if: :is_landscape?
289
353
 
290
- protected
354
+ private
291
355
 
292
356
  def is_human? picture
293
357
  model.can_program?(:ruby)
@@ -321,7 +385,7 @@ class MyUploader < CarrierWave::Uploader::Base
321
385
  process resize_to_fill: [280, 280]
322
386
  end
323
387
 
324
- version :small_thumb, :from_version => :thumb do
388
+ version :small_thumb, from_version: :thumb do
325
389
  process resize_to_fill: [20, 20]
326
390
  end
327
391
 
@@ -340,7 +404,7 @@ file, just add a hidden field called `avatar_cache` (don't forget to add it to
340
404
  the attr_accessible list as necessary). In Rails, this would look like this:
341
405
 
342
406
  ```erb
343
- <%= form_for @user, :html => {:multipart => true} do |f| %>
407
+ <%= form_for @user, html: { multipart: true } do |f| %>
344
408
  <p>
345
409
  <label>My Avatar</label>
346
410
  <%= f.file_field :avatar %>
@@ -353,7 +417,7 @@ It might be a good idea to show the user that a file has been uploaded, in the
353
417
  case of images, a small thumbnail would be a good indicator:
354
418
 
355
419
  ```erb
356
- <%= form_for @user, :html => {:multipart => true} do |f| %>
420
+ <%= form_for @user, html: { multipart: true } do |f| %>
357
421
  <p>
358
422
  <label>My Avatar</label>
359
423
  <%= image_tag(@user.avatar_url) if @user.avatar? %>
@@ -369,7 +433,7 @@ If you want to remove a previously uploaded file on a mounted uploader, you can
369
433
  easily add a checkbox to the form which will remove the file when checked.
370
434
 
371
435
  ```erb
372
- <%= form_for @user, :html => {:multipart => true} do |f| %>
436
+ <%= form_for @user, html: { multipart: true } do |f| %>
373
437
  <p>
374
438
  <label>My Avatar</label>
375
439
  <%= image_tag(@user.avatar_url) if @user.avatar? %>
@@ -400,7 +464,7 @@ via a URL. CarrierWave makes this simple, just add the appropriate attribute to
400
464
  form and you're good to go:
401
465
 
402
466
  ```erb
403
- <%= form_for @user, :html => {:multipart => true} do |f| %>
467
+ <%= form_for @user, html: { multipart: true } do |f| %>
404
468
  <p>
405
469
  <label>My Avatar URL:</label>
406
470
  <%= image_tag(@user.avatar_url) if @user.avatar? %>
@@ -422,7 +486,7 @@ this easily by overriding the `default_url` method in your uploader:
422
486
 
423
487
  ```ruby
424
488
  class MyUploader < CarrierWave::Uploader::Base
425
- def default_url
489
+ def default_url(*args)
426
490
  "/images/fallback/" + [version_name, "default.png"].compact.join('_')
427
491
  end
428
492
  end
@@ -432,7 +496,7 @@ Or if you are using the Rails asset pipeline:
432
496
 
433
497
  ```ruby
434
498
  class MyUploader < CarrierWave::Uploader::Base
435
- def default_url
499
+ def default_url(*args)
436
500
  ActionController::Base.helpers.asset_path("fallback/" + [version_name, "default.png"].compact.join('_'))
437
501
  end
438
502
  end
@@ -459,7 +523,7 @@ instance.recreate_versions!(:thumb, :large)
459
523
  Or on a mounted uploader:
460
524
 
461
525
  ```ruby
462
- User.all.each do |user|
526
+ User.find_each do |user|
463
527
  user.avatar.recreate_versions!
464
528
  end
465
529
  ```
@@ -467,7 +531,7 @@ end
467
531
  Note: `recreate_versions!` will throw an exception on records without an image. To avoid this, scope the records to those with images or check if an image exists within the block. If you're using ActiveRecord, recreating versions for a user avatar might look like this:
468
532
 
469
533
  ```ruby
470
- User.all.each do |user|
534
+ User.find_each do |user|
471
535
  user.avatar.recreate_versions! if user.avatar?
472
536
  end
473
537
  ```
@@ -497,6 +561,16 @@ If you're using Rails, create an initializer for this:
497
561
 
498
562
  config/initializers/carrierwave.rb
499
563
 
564
+ If you want CarrierWave to fail noisily in development, you can change these configs in your environment file:
565
+
566
+ ```ruby
567
+ CarrierWave.configure do |config|
568
+ config.ignore_integrity_errors = false
569
+ config.ignore_processing_errors = false
570
+ config.ignore_download_errors = false
571
+ end
572
+ ```
573
+
500
574
 
501
575
  ## Testing with CarrierWave
502
576
 
@@ -527,35 +601,43 @@ require 'carrierwave/test/matchers'
527
601
  describe MyUploader do
528
602
  include CarrierWave::Test::Matchers
529
603
 
604
+ let(:user) { double('user') }
605
+ let(:uploader) { MyUploader.new(user, :avatar) }
606
+
530
607
  before do
531
608
  MyUploader.enable_processing = true
532
- @uploader = MyUploader.new(@user, :avatar)
533
- @uploader.store!(File.open(path_to_file))
609
+ File.open(path_to_file) { |f| uploader.store!(f) }
534
610
  end
535
611
 
536
612
  after do
537
613
  MyUploader.enable_processing = false
538
- @uploader.remove!
614
+ uploader.remove!
539
615
  end
540
616
 
541
617
  context 'the thumb version' do
542
- it "should scale down a landscape image to be exactly 64 by 64 pixels" do
543
- @uploader.thumb.should have_dimensions(64, 64)
618
+ it "scales down a landscape image to be exactly 64 by 64 pixels" do
619
+ expect(uploader.thumb).to have_dimensions(64, 64)
544
620
  end
545
621
  end
546
622
 
547
623
  context 'the small version' do
548
- it "should scale down a landscape image to fit within 200 by 200 pixels" do
549
- @uploader.small.should be_no_larger_than(200, 200)
624
+ it "scales down a landscape image to fit within 200 by 200 pixels" do
625
+ expect(uploader.small).to be_no_larger_than(200, 200)
550
626
  end
551
627
  end
552
628
 
553
- it "should make the image readable only to the owner and not executable" do
554
- @uploader.should have_permissions(0600)
629
+ it "makes the image readable only to the owner and not executable" do
630
+ expect(uploader).to have_permissions(0600)
631
+ end
632
+
633
+ it "has the correct format" do
634
+ expect(uploader).to be_format('png')
555
635
  end
556
636
  end
557
637
  ```
558
638
 
639
+ If you're looking for minitest asserts, checkout [carrierwave_asserts](https://github.com/hcfairbanks/carrierwave_asserts).
640
+
559
641
  Setting the enable_processing flag on an uploader will prevent any of the versions from processing as well.
560
642
  Processing can be enabled for a single version by setting the processing flag on the version like so:
561
643
 
@@ -563,31 +645,43 @@ Processing can be enabled for a single version by setting the processing flag on
563
645
  @uploader.thumb.enable_processing = true
564
646
  ```
565
647
 
648
+ ## Fog
649
+
650
+ If you want to use fog you must add in your CarrierWave initializer the
651
+ following lines
652
+
653
+ ```ruby
654
+ config.fog_provider = 'fog' # 'fog/aws' etc. Defaults to 'fog'
655
+ config.fog_credentials = { ... } # Provider specific credentials
656
+ ```
657
+
566
658
  ## Using Amazon S3
567
659
 
568
- [Fog](http://github.com/fog/fog) is used to support Amazon S3. Ensure you have it in your Gemfile:
660
+ [Fog AWS](http://github.com/fog/fog-aws) is used to support Amazon S3. Ensure you have it in your Gemfile:
569
661
 
570
662
  ```ruby
571
- gem "fog", "~> 1.3.1"
663
+ gem "fog-aws"
572
664
  ```
573
665
 
574
666
  You'll need to provide your fog_credentials and a fog_directory (also known as a bucket) in an initializer.
575
- For the sake of performance it is assumed that the directory already exists, so please create it if need be.
667
+ For the sake of performance it is assumed that the directory already exists, so please create it if it needs to be.
576
668
  You can also pass in additional options, as documented fully in lib/carrierwave/storage/fog.rb. Here's a full example:
577
669
 
578
670
  ```ruby
579
671
  CarrierWave.configure do |config|
672
+ config.fog_provider = 'fog/aws' # required
580
673
  config.fog_credentials = {
581
- :provider => 'AWS', # required
582
- :aws_access_key_id => 'xxx', # required
583
- :aws_secret_access_key => 'yyy', # required
584
- :region => 'eu-west-1', # optional, defaults to 'us-east-1'
585
- :host => 's3.example.com', # optional, defaults to nil
586
- :endpoint => 'https://s3.example.com:8080' # optional, defaults to nil
674
+ provider: 'AWS', # required
675
+ aws_access_key_id: 'xxx', # required unless using use_iam_profile
676
+ aws_secret_access_key: 'yyy', # required unless using use_iam_profile
677
+ use_iam_profile: true, # optional, defaults to false
678
+ region: 'eu-west-1', # optional, defaults to 'us-east-1'
679
+ host: 's3.example.com', # optional, defaults to nil
680
+ endpoint: 'https://s3.example.com:8080' # optional, defaults to nil
587
681
  }
588
- config.fog_directory = 'name_of_directory' # required
589
- config.fog_public = false # optional, defaults to true
590
- config.fog_attributes = {'Cache-Control'=>'max-age=315576000'} # optional, defaults to {}
682
+ config.fog_directory = 'name_of_bucket' # required
683
+ config.fog_public = false # optional, defaults to true
684
+ config.fog_attributes = { cache_control: "public, max-age=#{365.days.to_i}" } # optional, defaults to {}
591
685
  end
592
686
  ```
593
687
 
@@ -616,11 +710,12 @@ Using a US-based account:
616
710
 
617
711
  ```ruby
618
712
  CarrierWave.configure do |config|
713
+ config.fog_provider = "fog/rackspace/storage" # optional, defaults to "fog"
619
714
  config.fog_credentials = {
620
- :provider => 'Rackspace',
621
- :rackspace_username => 'xxxxxx',
622
- :rackspace_api_key => 'yyyyyy',
623
- :rackspace_region => :ord # optional, defaults to :dfw
715
+ provider: 'Rackspace',
716
+ rackspace_username: 'xxxxxx',
717
+ rackspace_api_key: 'yyyyyy',
718
+ rackspace_region: :ord # optional, defaults to :dfw
624
719
  }
625
720
  config.fog_directory = 'name_of_directory'
626
721
  end
@@ -630,12 +725,13 @@ Using a UK-based account:
630
725
 
631
726
  ```ruby
632
727
  CarrierWave.configure do |config|
728
+ config.fog_provider = "fog/rackspace/storage" # optional, defaults to "fog"
633
729
  config.fog_credentials = {
634
- :provider => 'Rackspace',
635
- :rackspace_username => 'xxxxxx',
636
- :rackspace_api_key => 'yyyyyy',
637
- :rackspace_auth_url => Fog::Rackspace::UK_AUTH_ENDPOINT,
638
- :rackspace_region => :lon
730
+ provider: 'Rackspace',
731
+ rackspace_username: 'xxxxxx',
732
+ rackspace_api_key: 'yyyyyy',
733
+ rackspace_auth_url: Fog::Rackspace::UK_AUTH_ENDPOINT,
734
+ rackspace_region: :lon
639
735
  }
640
736
  config.fog_directory = 'name_of_directory'
641
737
  end
@@ -662,25 +758,27 @@ the url to the file on Rackspace Cloud Files.
662
758
 
663
759
  ## Using Google Storage for Developers
664
760
 
665
- [Fog](http://github.com/fog/fog) is used to support Google Storage for Developers. Ensure you have it in your Gemfile:
761
+ [Fog](http://github.com/fog/fog-google) is used to support Google Storage for Developers. Ensure you have it in your Gemfile:
666
762
 
667
763
  ```ruby
668
- gem "fog"
764
+ gem "fog-google"
765
+ gem "google-api-client", "> 0.8.5", "< 0.9"
766
+ gem "mime-types"
669
767
  ```
670
768
 
671
769
  You'll need to configure a directory (also known as a bucket), access key id and secret access key in the initializer.
672
770
  For the sake of performance it is assumed that the directory already exists, so please create it if need be.
673
771
 
674
- Sign up [here](http://gs-signup-redirect.appspot.com/) and get your credentials [here](https://storage.cloud.google.com/m)
675
- under the section “Interoperable Access”.
772
+ Please read the [fog-google README](https://github.com/fog/fog-google/blob/master/README.md) on how to get credentials.
676
773
 
677
774
 
678
775
  ```ruby
679
776
  CarrierWave.configure do |config|
777
+ config.fog_provider = 'fog/google' # required
680
778
  config.fog_credentials = {
681
- :provider => 'Google',
682
- :google_storage_access_key_id => 'xxxxxx',
683
- :google_storage_secret_access_key => 'yyyyyy'
779
+ provider: 'Google',
780
+ google_storage_access_key_id: 'xxxxxx',
781
+ google_storage_secret_access_key: 'yyyyyy'
684
782
  }
685
783
  config.fog_directory = 'name_of_directory'
686
784
  end
@@ -697,6 +795,31 @@ end
697
795
  That's it! You can still use the `CarrierWave::Uploader#url` method to return
698
796
  the url to the file on Google.
699
797
 
798
+ ## Optimized Loading of Fog
799
+
800
+ Since Carrierwave doesn't know which parts of Fog you intend to use, it will just load the entire library (unless you use e.g. [`fog-aws`, `fog-google`] instead of fog proper). If you prefer to load fewer classes into your application, you need to load those parts of Fog yourself *before* loading CarrierWave in your Gemfile. Ex:
801
+
802
+ ```ruby
803
+ gem "fog", "~> 1.27", require: "fog/rackspace/storage"
804
+ gem "carrierwave"
805
+ ```
806
+
807
+ A couple of notes about versions:
808
+ * This functionality was introduced in Fog v1.20.
809
+ * This functionality is slated for CarrierWave v1.0.0.
810
+
811
+ If you're not relying on Gemfile entries alone and are requiring "carrierwave" anywhere, ensure you require "fog/rackspace/storage" before it. Ex:
812
+
813
+ ```ruby
814
+ require "fog/rackspace/storage"
815
+ require "carrierwave"
816
+ ```
817
+
818
+ Beware that this specific require is only needed when working with a fog provider that was not extracted to its own gem yet.
819
+ A list of the extracted providers can be found in the page of the `fog` organizations [here](https://github.com/fog).
820
+
821
+ When in doubt, inspect `Fog.constants` to see what has been loaded.
822
+
700
823
  ## Dynamic Asset Host
701
824
 
702
825
  The `asset_host` config property can be assigned a proc (or anything that responds to `call`) for generating the host dynamically. The proc-compliant object gets an instance of the current `CarrierWave::Storage::Fog::File` or `CarrierWave::SanitizedFile` as its only argument.
@@ -734,8 +857,8 @@ Convert will only work if the file has the same file extension, thus the use of
734
857
  class AvatarUploader < CarrierWave::Uploader::Base
735
858
  include CarrierWave::RMagick
736
859
 
737
- process :resize_to_fill => [200, 200]
738
- process :convert => 'png'
860
+ process resize_to_fill: [200, 200]
861
+ process convert: 'png'
739
862
 
740
863
  def filename
741
864
  super.chomp(File.extname(super)) + '.png' if original_filename.present?
@@ -767,7 +890,7 @@ for the RMagick processor.
767
890
  class AvatarUploader < CarrierWave::Uploader::Base
768
891
  include CarrierWave::MiniMagick
769
892
 
770
- process :resize_to_fill => [200, 200]
893
+ process resize_to_fill: [200, 200]
771
894
  end
772
895
  ```
773
896
 
@@ -787,27 +910,32 @@ details.
787
910
  Be sure to use mount_on to specify the correct column:
788
911
 
789
912
  ```ruby
790
- mount_uploader :avatar, AvatarUploader, :mount_on => :avatar_file_name
913
+ mount_uploader :avatar, AvatarUploader, mount_on: :avatar_file_name
791
914
  ```
792
915
 
793
- Unfortunately attachment_fu differs too much in philosophy for there to be a
794
- sensible compatibility mode. Patches for migrating from other solutions will be
795
- happily accepted.
796
-
797
- ## i18n
916
+ ## I18n
798
917
 
799
- The Active Record validations use the Rails i18n framework. Add these keys to
918
+ The Active Record validations use the Rails `i18n` framework. Add these keys to
800
919
  your translations file:
801
920
 
802
921
  ```yaml
803
922
  errors:
804
923
  messages:
805
- carrierwave_processing_error: "Cannot resize image."
806
- carrierwave_integrity_error: "Not an image."
807
- carrierwave_download_error: "Couldn't download image."
808
- extension_white_list_error: "You are not allowed to upload %{extension} files, allowed types: %{allowed_types}"
809
- extension_black_list_error: "You are not allowed to upload %{extension} files, prohibited types: %{prohibited_types}"
810
- ```
924
+ carrierwave_processing_error: failed to be processed
925
+ carrierwave_integrity_error: is not of an allowed file type
926
+ carrierwave_download_error: could not be downloaded
927
+ extension_whitelist_error: "You are not allowed to upload %{extension} files, allowed types: %{allowed_types}"
928
+ extension_blacklist_error: "You are not allowed to upload %{extension} files, prohibited types: %{prohibited_types}"
929
+ content_type_whitelist_error: "You are not allowed to upload %{content_type} files, allowed types: %{allowed_types}"
930
+ content_type_blacklist_error: "You are not allowed to upload %{content_type} files"
931
+ rmagick_processing_error: "Failed to manipulate with rmagick, maybe it is not an image?"
932
+ mini_magick_processing_error: "Failed to manipulate with MiniMagick, maybe it is not an image? Original Error: %{e}"
933
+ min_size_error: "File size should be greater than %{min_size}"
934
+ max_size_error: "File size should be less than %{max_size}"
935
+ ```
936
+
937
+ The [`carrierwave-i18n`](https://github.com/carrierwaveuploader/carrierwave-i18n)
938
+ library adds support for additional locales.
811
939
 
812
940
  ## Large files
813
941
 
@@ -822,6 +950,7 @@ class MyUploader < CarrierWave::Uploader::Base
822
950
  def move_to_cache
823
951
  true
824
952
  end
953
+
825
954
  def move_to_store
826
955
  true
827
956
  end
@@ -848,9 +977,10 @@ Will add these callbacks:
848
977
  ```ruby
849
978
  after_save :store_avatar!
850
979
  before_save :write_avatar_identifier
851
- after_commit :remove_avatar! :on => :destroy
852
- before_update :store_previous_model_for_avatar
853
- after_save :remove_previously_stored_avatar
980
+ after_commit :remove_avatar!, on: :destroy
981
+ after_commit :mark_remove_avatar_false, on: :update
982
+ after_save :store_previous_changes_for_avatar
983
+ after_commit :remove_previously_stored_avatar, on: :update
854
984
  ```
855
985
 
856
986
  If you want to skip any of these callbacks (eg. you want to keep the existing
@@ -860,7 +990,7 @@ avatar, even after uploading a new one), you can use ActiveRecord’s
860
990
  ```ruby
861
991
  class User
862
992
  mount_uploader :avatar, AvatarUploader
863
- skip_callback :save, :after, :remove_previously_stored_avatar
993
+ skip_callback :commit, :after, :remove_previously_stored_avatar
864
994
  end
865
995
  ```
866
996
 
@@ -870,7 +1000,7 @@ See [CONTRIBUTING.md](https://github.com/carrierwaveuploader/carrierwave/blob/ma
870
1000
 
871
1001
  ## License
872
1002
 
873
- Copyright (c) 2008-2013 Jonas Nicklas
1003
+ Copyright (c) 2008-2015 Jonas Nicklas
874
1004
 
875
1005
  Permission is hereby granted, free of charge, to any person obtaining
876
1006
  a copy of this software and associated documentation files (the