carrierwave 1.3.2 → 3.0.0

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 (50) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +235 -91
  3. data/lib/carrierwave/compatibility/paperclip.rb +4 -2
  4. data/lib/carrierwave/downloader/base.rb +101 -0
  5. data/lib/carrierwave/downloader/remote_file.rb +68 -0
  6. data/lib/carrierwave/locale/en.yml +9 -6
  7. data/lib/carrierwave/mount.rb +48 -61
  8. data/lib/carrierwave/mounter.rb +165 -77
  9. data/lib/carrierwave/orm/activerecord.rb +13 -55
  10. data/lib/carrierwave/processing/mini_magick.rb +108 -123
  11. data/lib/carrierwave/processing/rmagick.rb +11 -15
  12. data/lib/carrierwave/processing/vips.rb +284 -0
  13. data/lib/carrierwave/processing.rb +1 -0
  14. data/lib/carrierwave/sanitized_file.rb +60 -66
  15. data/lib/carrierwave/storage/abstract.rb +5 -5
  16. data/lib/carrierwave/storage/file.rb +6 -5
  17. data/lib/carrierwave/storage/fog.rb +101 -62
  18. data/lib/carrierwave/storage.rb +1 -0
  19. data/lib/carrierwave/test/matchers.rb +11 -7
  20. data/lib/carrierwave/uploader/cache.rb +40 -24
  21. data/lib/carrierwave/uploader/callbacks.rb +1 -1
  22. data/lib/carrierwave/uploader/configuration.rb +38 -19
  23. data/lib/carrierwave/uploader/content_type_allowlist.rb +62 -0
  24. data/lib/carrierwave/uploader/content_type_denylist.rb +62 -0
  25. data/lib/carrierwave/uploader/dimension.rb +66 -0
  26. data/lib/carrierwave/uploader/download.rb +2 -123
  27. data/lib/carrierwave/uploader/extension_allowlist.rb +63 -0
  28. data/lib/carrierwave/uploader/extension_denylist.rb +64 -0
  29. data/lib/carrierwave/uploader/file_size.rb +2 -2
  30. data/lib/carrierwave/uploader/mountable.rb +6 -0
  31. data/lib/carrierwave/uploader/processing.rb +42 -7
  32. data/lib/carrierwave/uploader/proxy.rb +17 -4
  33. data/lib/carrierwave/uploader/serialization.rb +1 -1
  34. data/lib/carrierwave/uploader/store.rb +46 -7
  35. data/lib/carrierwave/uploader/url.rb +7 -4
  36. data/lib/carrierwave/uploader/versions.rb +140 -105
  37. data/lib/carrierwave/uploader.rb +10 -17
  38. data/lib/carrierwave/utilities/file_name.rb +47 -0
  39. data/lib/carrierwave/utilities/uri.rb +14 -11
  40. data/lib/carrierwave/utilities.rb +1 -0
  41. data/lib/carrierwave/validations/active_model.rb +7 -9
  42. data/lib/carrierwave/version.rb +1 -1
  43. data/lib/carrierwave.rb +13 -17
  44. data/lib/generators/templates/{uploader.rb → uploader.rb.erb} +2 -2
  45. data/lib/generators/uploader_generator.rb +3 -3
  46. metadata +100 -33
  47. data/lib/carrierwave/uploader/content_type_blacklist.rb +0 -48
  48. data/lib/carrierwave/uploader/content_type_whitelist.rb +0 -48
  49. data/lib/carrierwave/uploader/extension_blacklist.rb +0 -51
  50. data/lib/carrierwave/uploader/extension_whitelist.rb +0 -52
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: d5e6d1dd656203f5e14c43b75b807e793d623126006ddf8c5a4f9f4706faa750
4
- data.tar.gz: 82281b939837f54716f580a1deb6397d87cc9bb867dc6a6938a4322d795500b1
3
+ metadata.gz: 79bb0ece072359fdea6b0f556a9b403bca195713a29424fb10d778bf3a9e557e
4
+ data.tar.gz: 2d566cf522931dba1289644c2a0e1318db509d3086235e022c439d3e0e34e83a
5
5
  SHA512:
6
- metadata.gz: 8eca3a53204f520d0cabf6e2384e6670cb634159e4b6c1e8d3915b6bab8473f21fb116047129b142a986588ea27401131d095186657770d7c31b03d6c929a1c9
7
- data.tar.gz: 316797cffad6d2568e50929862cd80ba3e56c05d557f70f8631b66fc60ffd65fe5862afe4121a1e5e775e55a5f6c9a6c14414bce6a57deab2d12a8a127ed5b0d
6
+ metadata.gz: 748384d2c1cd398385ebe72c7b17dbce246fee2e51d233c69ae9667bb698ede98065971f4502cdfe47de99e63826b638c47e4f32cb77ade88d63f18f0db1d075
7
+ data.tar.gz: 184d1e098e7cf781a58e8f927de3b79d22abeae1ff6e1475c62cdbd7b4c114e3744e542e7506821b6e53a2da084af3a1395653051b61a513df33ba5e0b0556cb
data/README.md CHANGED
@@ -3,14 +3,14 @@
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.svg?branch=master)](http://travis-ci.org/carrierwaveuploader/carrierwave)
6
+ [![Build Status](https://github.com/carrierwaveuploader/carrierwave/workflows/Test/badge.svg)](https://github.com/carrierwaveuploader/carrierwave/actions)
7
7
  [![Code Climate](https://codeclimate.com/github/carrierwaveuploader/carrierwave.svg)](https://codeclimate.com/github/carrierwaveuploader/carrierwave)
8
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
9
 
10
10
 
11
11
  ## Information
12
12
 
13
- * RDoc documentation [available on RubyDoc.info](http://rubydoc.info/gems/carrierwave/frames)
13
+ * RDoc documentation [available on RubyDoc.info](https://rubydoc.info/gems/carrierwave)
14
14
  * Source code [available on GitHub](http://github.com/carrierwaveuploader/carrierwave)
15
15
  * More information, known limitations, and how-tos [available on the wiki](https://github.com/carrierwaveuploader/carrierwave/wiki)
16
16
 
@@ -30,13 +30,19 @@ $ gem install carrierwave
30
30
  In Rails, add it to your Gemfile:
31
31
 
32
32
  ```ruby
33
- gem 'carrierwave', '~> 1.0'
33
+ gem 'carrierwave', '~> 3.0'
34
34
  ```
35
35
 
36
36
  Finally, restart the server to apply the changes.
37
37
 
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.
38
+ ## Upgrading from 2.x or earlier
39
+
40
+ CarrierWave 3.0 comes with a change in the way of handling the file extension on conversion. This results in following issues if you use `process convert: :format` to change the file format:
41
+
42
+ - If you have it on the uploader itself (not within a version), the file extension of the cached file will change. That means if you serve both CarrierWave 2.x and 3.x simultaneously on the same workload (e.g. using blue-green deployment), a cache file stored by 2.x can't be retrieved by 3.x and vice versa.
43
+ - If you have it within a version, the file extension of the stored file will change. You need to perform `#recreate_versions!` to make it usable again.
44
+
45
+ To preserve the 2.x behavior, you can set `force_extension false` right after calling `process convert: :format`. See [#2659](https://github.com/carrierwaveuploader/carrierwave/pull/2659) for the detail.
40
46
 
41
47
  ## Getting Started
42
48
 
@@ -94,7 +100,7 @@ a migration:
94
100
  Open your model file and mount the uploader:
95
101
 
96
102
  ```ruby
97
- class User < ActiveRecord::Base
103
+ class User < ApplicationRecord
98
104
  mount_uploader :avatar, AvatarUploader
99
105
  end
100
106
  ```
@@ -157,7 +163,7 @@ Open your model file and mount the uploader:
157
163
 
158
164
 
159
165
  ```ruby
160
- class User < ActiveRecord::Base
166
+ class User < ApplicationRecord
161
167
  mount_uploaders :avatars, AvatarUploader
162
168
  serialize :avatars, JSON # If you use SQLite, add this line.
163
169
  end
@@ -190,6 +196,17 @@ u.avatars[0].current_path # => 'path/to/file.png'
190
196
  u.avatars[0].identifier # => 'file.png'
191
197
  ```
192
198
 
199
+ If you want to preserve existing files on uploading new one, you can go like:
200
+
201
+ ```erb
202
+ <% user.avatars.each do |avatar| %>
203
+ <%= hidden_field :user, :avatars, multiple: true, value: avatar.identifier %>
204
+ <% end %>
205
+ <%= form.file_field :avatars, multiple: true %>
206
+ ```
207
+
208
+ Sorting avatars is supported as well by reordering `hidden_field`, an example using jQuery UI Sortable is available [here](https://github.com/carrierwaveuploader/carrierwave/wiki/How-to%3A-Add%2C-remove-and-reorder-images-using-multiple-file-upload).
209
+
193
210
  ## Changing the storage directory
194
211
 
195
212
  In order to change where uploaded files are put, just override the `store_dir`
@@ -216,10 +233,24 @@ class MyUploader < CarrierWave::Uploader::Base
216
233
  end
217
234
  ```
218
235
 
236
+ ## Changing the filename
237
+
238
+ To change the filename of uploaded files, you can override `#filename` method in the uploader.
239
+
240
+ ```ruby
241
+ class MyUploader < CarrierWave::Uploader::Base
242
+ def filename
243
+ "image.#{file.extension}" # If you upload 'file.jpg', you'll get 'image.jpg'
244
+ end
245
+ end
246
+ ```
247
+
248
+ Some old documentations (like [this](https://stackoverflow.com/a/5865117)) may instruct you to safeguard the filename value with `if original_filename`, but it's no longer necessary with CarrierWave 3.0 or later.
249
+
219
250
  ## Securing uploads
220
251
 
221
252
  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
253
+ files or other script files. CarrierWave allows you to specify an allowlist of
223
254
  allowed extensions or content types.
224
255
 
225
256
  If you're mounting the uploader, uploading a file with the wrong extension will
@@ -227,7 +258,7 @@ make the record invalid instead. Otherwise, an error is raised.
227
258
 
228
259
  ```ruby
229
260
  class MyUploader < CarrierWave::Uploader::Base
230
- def extension_whitelist
261
+ def extension_allowlist
231
262
  %w(jpg jpeg gif png)
232
263
  end
233
264
  end
@@ -238,29 +269,45 @@ Let's say we need an uploader that accepts only images. This can be done like th
238
269
 
239
270
  ```ruby
240
271
  class MyUploader < CarrierWave::Uploader::Base
241
- def content_type_whitelist
272
+ def content_type_allowlist
242
273
  /image\//
243
274
  end
244
275
  end
245
276
  ```
246
277
 
247
- You can use a blacklist to reject content types.
278
+ You can use a denylist to reject content types.
248
279
  Let's say we need an uploader that reject JSON files. This can be done like this
249
280
 
250
281
  ```ruby
251
282
  class NoJsonUploader < CarrierWave::Uploader::Base
252
- def content_type_blacklist
283
+ def content_type_denylist
253
284
  ['application/text', 'application/json']
254
285
  end
255
286
  end
256
287
  ```
257
288
 
289
+ ### CVE-2016-3714 (ImageTragick)
290
+ This version of CarrierWave has the ability to mitigate CVE-2016-3714. However, you **MUST** set a content_type_allowlist 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.
291
+
292
+
293
+ A valid allowlist that will restrict your uploader to images only, and mitigate the CVE is:
294
+
295
+ ```ruby
296
+ class MyUploader < CarrierWave::Uploader::Base
297
+ def content_type_allowlist
298
+ [/image\//]
299
+ end
300
+ end
301
+ ```
302
+
303
+ **WARNING**: A `content_type_allowlist` is the only form of allowlist or denylist supported by CarrierWave that can effectively mitigate against CVE-2016-3714. Use of `extension_allowlist` will not inspect the file headers, and thus still leaves your application open to the vulnerability.
304
+
258
305
  ### Filenames and unicode chars
259
306
 
260
307
  Another security issue you should care for is the file names (see
261
308
  [Ruby On Rails Security Guide](http://guides.rubyonrails.org/security.html#file-uploads)).
262
309
  By default, CarrierWave provides only English letters, arabic numerals and some symbols as
263
- white-listed characters in the file name. If you want to support local scripts (Cyrillic letters, letters with diacritics and so on), you
310
+ allowlisted characters in the file name. If you want to support local scripts (Cyrillic letters, letters with diacritics and so on), you
264
311
  have to override `sanitize_regexp` method. It should return regular expression which would match
265
312
  all *non*-allowed symbols.
266
313
 
@@ -278,17 +325,8 @@ You no longer need to do this manually.
278
325
 
279
326
  ## Adding versions
280
327
 
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*:
282
-
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.
284
-
285
- Some documentation refers to RMagick instead of MiniMagick but MiniMagick is recommended.
286
-
287
- To install Imagemagick on OSX with homebrew type the following:
288
-
289
- ```
290
- $ brew install imagemagick
291
- ```
328
+ Often you'll want to add different versions of the same file. The classic example is generating image thumbnails while preserving the original file to be used for high-quality representation.
329
+ In this section we'll explore how CarrierWave supports working with multiple versions. The image manipulation itself is covered in [another section](#manipulating-images).
292
330
 
293
331
  ```ruby
294
332
  class MyUploader < CarrierWave::Uploader::Base
@@ -305,15 +343,13 @@ end
305
343
 
306
344
  When this uploader is used, an uploaded image would be scaled to be no larger
307
345
  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
346
 
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
347
+ A version called `:thumb` is then created, which is scaled
348
+ to exactly 200 by 200 pixels. The thumbnail uses `resize_to_fill` which makes sure
313
349
  that the width and height specified are filled, only cropping
314
350
  if the aspect ratio requires it.
315
351
 
316
- The uploader could be used like this:
352
+ The above uploader could be used like this:
317
353
 
318
354
  ```ruby
319
355
  uploader = AvatarUploader.new
@@ -326,6 +362,24 @@ uploader.thumb.url # => '/url/to/thumb_my_file.png' # size: 200x200
326
362
  One important thing to remember is that process is called *before* versions are
327
363
  created. This can cut down on processing cost.
328
364
 
365
+ ### Conditional processing
366
+
367
+ If you want to use conditional process, you can only use `if` statement.
368
+
369
+ See `carrierwave/uploader/processing.rb` for details.
370
+
371
+ ```ruby
372
+ class MyUploader < CarrierWave::Uploader::Base
373
+ process :scale => [200, 200], :if => :image?
374
+
375
+ def image?(carrier_wave_sanitized_file)
376
+ true
377
+ end
378
+ end
379
+ ```
380
+
381
+ ### Nested versions
382
+
329
383
  It is possible to nest versions within versions:
330
384
 
331
385
  ```ruby
@@ -362,7 +416,7 @@ private
362
416
  end
363
417
 
364
418
  def is_landscape? picture
365
- image = MiniMagick::Image.open(picture.path)
419
+ image = MiniMagick::Image.new(picture.path)
366
420
  image[:width] > image[:height]
367
421
  end
368
422
 
@@ -392,8 +446,27 @@ class MyUploader < CarrierWave::Uploader::Base
392
446
  end
393
447
  ```
394
448
 
395
- The option `:from_version` uses the file cached in the `:thumb` version instead
396
- of the original version, potentially resulting in faster processing.
449
+ ### Customizing version filenames
450
+
451
+ CarrierWave supports [customization of filename](#changing-the-filename) by overriding an uploader's
452
+ #filename method, but this doesn't work for versions because of the limitation on how CarrierWave
453
+ re-constructs the filename on retrieval of the stored file.
454
+ Instead, you can override `#full_filename` with providing a version-aware name.
455
+
456
+ ```ruby
457
+ class MyUploader < CarrierWave::Uploader::Base
458
+ version :thumb do
459
+ def full_filename(for_file)
460
+ 'thumb.png'
461
+ end
462
+ process convert: 'png'
463
+ end
464
+ end
465
+ ```
466
+
467
+ Please note that `#full_filename` mustn't be constructed based on a dynamic value
468
+ that can change from the time of store and time of retrieval, since it will result in
469
+ being unable to retrieve a file previously stored.
397
470
 
398
471
  ## Making uploads work across form redisplays
399
472
 
@@ -478,6 +551,17 @@ failures automatically with attribute validation errors. If you aren't, or you
478
551
  disable CarrierWave's `validate_download` option, you'll need to handle those
479
552
  errors yourself.
480
553
 
554
+ ### Retry option for download from remote location
555
+ If you want to retry the download from the Remote URL, enable the download_retry_count option, an error occurs during download, it will try to execute the specified number of times.
556
+ This option is effective when the remote destination is unstable.
557
+
558
+ ```rb
559
+ CarrierWave.configure do |config|
560
+ config.download_retry_count = 3 # Default 0
561
+ config.download_retry_wait_time = 3 # Default 5
562
+ end
563
+ ```
564
+
481
565
  ## Providing a default URL
482
566
 
483
567
  In many cases, especially when working with images, it might be a good idea to
@@ -651,7 +735,6 @@ If you want to use fog you must add in your CarrierWave initializer the
651
735
  following lines
652
736
 
653
737
  ```ruby
654
- config.fog_provider = 'fog' # 'fog/aws' etc. Defaults to 'fog'
655
738
  config.fog_credentials = { ... } # Provider specific credentials
656
739
  ```
657
740
 
@@ -669,7 +752,6 @@ You can also pass in additional options, as documented fully in lib/carrierwave/
669
752
 
670
753
  ```ruby
671
754
  CarrierWave.configure do |config|
672
- config.fog_provider = 'fog/aws' # required
673
755
  config.fog_credentials = {
674
756
  provider: 'AWS', # required
675
757
  aws_access_key_id: 'xxx', # required unless using use_iam_profile
@@ -682,6 +764,9 @@ CarrierWave.configure do |config|
682
764
  config.fog_directory = 'name_of_bucket' # required
683
765
  config.fog_public = false # optional, defaults to true
684
766
  config.fog_attributes = { cache_control: "public, max-age=#{365.days.to_i}" } # optional, defaults to {}
767
+ # For an application which utilizes multiple servers but does not need caches persisted across requests,
768
+ # uncomment the line :file instead of the default :storage. Otherwise, it will use AWS as the temp cache store.
769
+ # config.cache_storage = :file
685
770
  end
686
771
  ```
687
772
 
@@ -695,6 +780,14 @@ end
695
780
 
696
781
  That's it! You can still use the `CarrierWave::Uploader#url` method to return the url to the file on Amazon S3.
697
782
 
783
+ **Note**: for Carrierwave to work properly it needs credentials with the following permissions:
784
+
785
+ * `s3:ListBucket`
786
+ * `s3:PutObject`
787
+ * `s3:GetObject`
788
+ * `s3:DeleteObject`
789
+ * `s3:PutObjectAcl`
790
+
698
791
  ## Using Rackspace Cloud Files
699
792
 
700
793
  [Fog](http://github.com/fog/fog) is used to support Rackspace Cloud Files. Ensure you have it in your Gemfile:
@@ -710,7 +803,6 @@ Using a US-based account:
710
803
 
711
804
  ```ruby
712
805
  CarrierWave.configure do |config|
713
- config.fog_provider = "fog/rackspace/storage" # optional, defaults to "fog"
714
806
  config.fog_credentials = {
715
807
  provider: 'Rackspace',
716
808
  rackspace_username: 'xxxxxx',
@@ -725,7 +817,6 @@ Using a UK-based account:
725
817
 
726
818
  ```ruby
727
819
  CarrierWave.configure do |config|
728
- config.fog_provider = "fog/rackspace/storage" # optional, defaults to "fog"
729
820
  config.fog_credentials = {
730
821
  provider: 'Rackspace',
731
822
  rackspace_username: 'xxxxxx',
@@ -756,31 +847,41 @@ end
756
847
  That's it! You can still use the `CarrierWave::Uploader#url` method to return
757
848
  the url to the file on Rackspace Cloud Files.
758
849
 
759
- ## Using Google Storage for Developers
850
+ ## Using Google Cloud Storage
760
851
 
761
- [Fog](http://github.com/fog/fog-google) is used to support Google Storage for Developers. Ensure you have it in your Gemfile:
852
+ [Fog](http://github.com/fog/fog-google) is used to support Google Cloud Storage. Ensure you have it in your Gemfile:
762
853
 
763
854
  ```ruby
764
855
  gem "fog-google"
765
- gem "google-api-client", "> 0.8.5", "< 0.9"
766
- gem "mime-types"
767
856
  ```
768
857
 
769
- You'll need to configure a directory (also known as a bucket), access key id and secret access key in the initializer.
858
+ You'll need to configure a directory (also known as a bucket) and the credentials in the initializer.
770
859
  For the sake of performance it is assumed that the directory already exists, so please create it if need be.
771
860
 
772
861
  Please read the [fog-google README](https://github.com/fog/fog-google/blob/master/README.md) on how to get credentials.
773
862
 
863
+ For Google Storage JSON API (recommended):
864
+ ```ruby
865
+ CarrierWave.configure do |config|
866
+ config.fog_credentials = {
867
+ provider: 'Google',
868
+ google_project: 'my-project',
869
+ google_json_key_string: 'xxxxxx'
870
+ # or use google_json_key_location if using an actual file
871
+ }
872
+ config.fog_directory = 'google_cloud_storage_bucket_name'
873
+ end
874
+ ```
774
875
 
876
+ For Google Storage XML API:
775
877
  ```ruby
776
878
  CarrierWave.configure do |config|
777
- config.fog_provider = 'fog/google' # required
778
- config.fog_credentials = {
779
- provider: 'Google',
780
- google_storage_access_key_id: 'xxxxxx',
781
- google_storage_secret_access_key: 'yyyyyy'
782
- }
783
- config.fog_directory = 'name_of_directory'
879
+ config.fog_credentials = {
880
+ provider: 'Google',
881
+ google_storage_access_key_id: 'xxxxxx',
882
+ google_storage_secret_access_key: 'yyyyyy'
883
+ }
884
+ config.fog_directory = 'google_cloud_storage_bucket_name'
784
885
  end
785
886
  ```
786
887
 
@@ -833,67 +934,81 @@ CarrierWave.configure do |config|
833
934
  end
834
935
  ```
835
936
 
836
- ## Using RMagick
937
+ ## Manipulating images
837
938
 
838
939
  If you're uploading images, you'll probably want to manipulate them in some way,
839
- you might want to create thumbnail images for example. CarrierWave comes with a
840
- small library to make manipulating images with RMagick easier, you'll need to
841
- include it in your Uploader:
940
+ you might want to create thumbnail images for example.
941
+
942
+ ### Using MiniMagick
943
+
944
+ MiniMagick performs all the operations using the 'convert' CLI which is part of the standard ImageMagick kit.
945
+ This allows you to have the power of ImageMagick without having to worry about installing
946
+ all the RMagick libraries, it often results in higher memory footprint.
947
+
948
+ See the MiniMagick site for more details:
949
+
950
+ https://github.com/minimagick/minimagick
951
+
952
+ To install Imagemagick on OSX with homebrew type the following:
842
953
 
843
- ```ruby
844
- class AvatarUploader < CarrierWave::Uploader::Base
845
- include CarrierWave::RMagick
846
- end
954
+ ```
955
+ $ brew install imagemagick
847
956
  ```
848
957
 
849
- The RMagick module gives you a few methods, like
850
- `CarrierWave::RMagick#resize_to_fill` which manipulate the image file in some
851
- way. You can set a `process` callback, which will call that method any time a
852
- file is uploaded.
853
- There is a demonstration of convert here.
854
- Convert will only work if the file has the same file extension, thus the use of the filename method.
958
+ And the ImageMagick command line options for more for what's on offer:
959
+
960
+ http://www.imagemagick.org/script/command-line-options.php
961
+
962
+ Currently, the MiniMagick carrierwave processor provides exactly the same methods as
963
+ for the RMagick processor.
855
964
 
856
965
  ```ruby
857
966
  class AvatarUploader < CarrierWave::Uploader::Base
858
- include CarrierWave::RMagick
967
+ include CarrierWave::MiniMagick
859
968
 
860
969
  process resize_to_fill: [200, 200]
861
- process convert: 'png'
862
-
863
- def filename
864
- super.chomp(File.extname(super)) + '.png' if original_filename.present?
865
- end
866
970
  end
867
971
  ```
868
972
 
869
- Check out the manipulate! method, which makes it easy for you to write your own
870
- manipulation methods.
871
-
872
- ## Using MiniMagick
973
+ #### List of available processing methods:
873
974
 
874
- MiniMagick is similar to RMagick but performs all the operations using the 'mogrify'
875
- command which is part of the standard ImageMagick kit. This allows you to have the power
876
- of ImageMagick without having to worry about installing all the RMagick libraries.
975
+ - `convert` - Changes the image encoding format to the given format(eg. jpg). This operation is treated specially to trigger the change of the file extension, so it matches with the format of the resulting file.
976
+ - `resize_to_limit` - Resize the image to fit within the specified dimensions while retaining the original aspect ratio. Will only resize the image if it is larger than the specified dimensions. The resulting image may be shorter or narrower than specified in the smaller dimension but will not be larger than the specified values.
977
+ - `resize_to_fit` - Resize the image to fit within the specified dimensions while retaining the original aspect ratio. The image may be shorter or narrower than specified in the smaller dimension but will not be larger than the specified values.
978
+ - `resize_to_fill` - Resize the image to fit within the specified dimensions while retaining the aspect ratio of the original image. If necessary, crop the image in the larger dimension. Optionally, a "gravity" may be specified, for example "Center", or "NorthEast".
979
+ - `resize_and_pad` - Resize the image to fit within the specified dimensions while retaining the original aspect ratio. If necessary, will pad the remaining area with the given color, which defaults to transparent (for gif and png, white for jpeg). Optionally, a "gravity" may be specified, as above.
877
980
 
878
- See the MiniMagick site for more details:
981
+ See `carrierwave/processing/mini_magick.rb` for details.
879
982
 
880
- https://github.com/minimagick/minimagick
983
+ ### Using RMagick
881
984
 
882
- And the ImageMagick command line options for more for whats on offer:
985
+ CarrierWave also comes with support for RMagick, a well-known image processing library.
986
+ To use it, you'll need to include this in your Uploader:
883
987
 
884
- http://www.imagemagick.org/script/command-line-options.php
988
+ ```ruby
989
+ class AvatarUploader < CarrierWave::Uploader::Base
990
+ include CarrierWave::RMagick
991
+ end
992
+ ```
885
993
 
886
- Currently, the MiniMagick carrierwave processor provides exactly the same methods as
887
- for the RMagick processor.
994
+ The RMagick module gives you a few methods, like
995
+ `CarrierWave::RMagick#resize_to_fill` which manipulate the image file in some
996
+ way. You can set a `process` callback, which will call that method any time a
997
+ file is uploaded.
998
+ There is a demonstration of convert here.
888
999
 
889
1000
  ```ruby
890
1001
  class AvatarUploader < CarrierWave::Uploader::Base
891
- include CarrierWave::MiniMagick
1002
+ include CarrierWave::RMagick
892
1003
 
893
1004
  process resize_to_fill: [200, 200]
1005
+ process convert: 'png'
894
1006
  end
895
1007
  ```
896
1008
 
1009
+ Check out the manipulate! method, which makes it easy for you to write your own
1010
+ manipulation methods.
1011
+
897
1012
  ## Migrating from Paperclip
898
1013
 
899
1014
  If you are using Paperclip, you can use the provided compatibility module:
@@ -924,14 +1039,17 @@ errors:
924
1039
  carrierwave_processing_error: failed to be processed
925
1040
  carrierwave_integrity_error: is not of an allowed file type
926
1041
  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}"
1042
+ extension_allowlist_error: "You are not allowed to upload %{extension} files, allowed types: %{allowed_types}"
1043
+ extension_denylist_error: "You are not allowed to upload %{extension} files, prohibited types: %{prohibited_types}"
1044
+ content_type_allowlist_error: "You are not allowed to upload %{content_type} files, allowed types: %{allowed_types}"
1045
+ content_type_denylist_error: "You are not allowed to upload %{content_type} files"
1046
+ processing_error: "Failed to manipulate, maybe it is not an image?"
933
1047
  min_size_error: "File size should be greater than %{min_size}"
934
1048
  max_size_error: "File size should be less than %{max_size}"
1049
+ min_width_error: "Image width should be greater than %{min_width}px"
1050
+ max_width_error: "Image width should be less than %{max_width}px"
1051
+ min_height_error: "Image height should be greater than %{min_height}px"
1052
+ max_height_error: "Image height should be less than %{max_height}px"
935
1053
  ```
936
1054
 
937
1055
  The [`carrierwave-i18n`](https://github.com/carrierwaveuploader/carrierwave-i18n)
@@ -975,12 +1093,12 @@ end
975
1093
  Will add these callbacks:
976
1094
 
977
1095
  ```ruby
978
- after_save :store_avatar!
979
1096
  before_save :write_avatar_identifier
1097
+ after_save :store_previous_changes_for_avatar
980
1098
  after_commit :remove_avatar!, on: :destroy
981
1099
  after_commit :mark_remove_avatar_false, on: :update
982
- after_save :store_previous_changes_for_avatar
983
1100
  after_commit :remove_previously_stored_avatar, on: :update
1101
+ after_commit :store_avatar!, on: [:create, :update]
984
1102
  ```
985
1103
 
986
1104
  If you want to skip any of these callbacks (eg. you want to keep the existing
@@ -994,13 +1112,39 @@ class User
994
1112
  end
995
1113
  ```
996
1114
 
1115
+ ## Uploader Callbacks
1116
+
1117
+ In addition to the ActiveRecord callbacks described above, uploaders also have callbacks.
1118
+
1119
+ ```ruby
1120
+ class MyUploader < ::CarrierWave::Uploader::Base
1121
+ before :remove, :log_removal
1122
+ private
1123
+ def log_removal
1124
+ ::Rails.logger.info(format('Deleting file on S3: %s', @file))
1125
+ end
1126
+ end
1127
+ ```
1128
+
1129
+ Uploader callbacks can be `before` or `after` the following events:
1130
+
1131
+ ```
1132
+ cache
1133
+ process
1134
+ remove
1135
+ retrieve_from_cache
1136
+ store
1137
+ ```
1138
+
997
1139
  ## Contributing to CarrierWave
998
1140
 
999
1141
  See [CONTRIBUTING.md](https://github.com/carrierwaveuploader/carrierwave/blob/master/CONTRIBUTING.md)
1000
1142
 
1001
1143
  ## License
1002
1144
 
1003
- Copyright (c) 2008-2015 Jonas Nicklas
1145
+ The MIT License (MIT)
1146
+
1147
+ Copyright (c) 2008 Jonas Nicklas
1004
1148
 
1005
1149
  Permission is hereby granted, free of charge, to any person obtaining
1006
1150
  a copy of this software and associated documentation files (the
@@ -56,10 +56,11 @@ module CarrierWave
56
56
  :basename => lambda{|u, f| u.filename.gsub(/#{File.extname(u.filename)}$/, "") },
57
57
  :extension => lambda{|u, d| File.extname(u.filename).gsub(/^\.+/, "")},
58
58
  :class => lambda{|u, f| u.model.class.name.underscore.pluralize}
59
- }
59
+ }.freeze
60
60
 
61
61
  included do
62
62
  attr_accessor :filename
63
+
63
64
  class_attribute :mappings
64
65
  self.mappings ||= DEFAULT_MAPPINGS.dup
65
66
  end
@@ -92,7 +93,8 @@ module CarrierWave
92
93
  end
93
94
  end
94
95
 
95
- private
96
+ private
97
+
96
98
  def interpolate_paperclip_path(path)
97
99
  mappings.each_pair.inject(path) do |agg, pair|
98
100
  agg.gsub(":#{pair[0]}") { pair[1].call(self, self.paperclip_style).to_s }