imgproxy 1.0.4 → 2.0.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (36) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +236 -92
  3. data/lib/imgproxy.rb +78 -38
  4. data/lib/imgproxy/builder.rb +56 -39
  5. data/lib/imgproxy/config.rb +96 -25
  6. data/lib/imgproxy/extensions/active_storage.rb +10 -0
  7. data/lib/imgproxy/extensions/shrine.rb +10 -0
  8. data/lib/imgproxy/options.rb +87 -72
  9. data/lib/imgproxy/options_aliases.rb +43 -0
  10. data/lib/imgproxy/options_casters/adjust.rb +22 -0
  11. data/lib/imgproxy/options_casters/array.rb +12 -0
  12. data/lib/imgproxy/options_casters/base64.rb +12 -0
  13. data/lib/imgproxy/options_casters/bool.rb +12 -0
  14. data/lib/imgproxy/options_casters/crop.rb +23 -0
  15. data/lib/imgproxy/options_casters/extend.rb +26 -0
  16. data/lib/imgproxy/options_casters/float.rb +16 -0
  17. data/lib/imgproxy/options_casters/gif_options.rb +21 -0
  18. data/lib/imgproxy/options_casters/gravity.rb +23 -0
  19. data/lib/imgproxy/options_casters/group.rb +21 -0
  20. data/lib/imgproxy/options_casters/integer.rb +10 -0
  21. data/lib/imgproxy/options_casters/jpeg_options.rb +26 -0
  22. data/lib/imgproxy/options_casters/png_options.rb +23 -0
  23. data/lib/imgproxy/options_casters/resize.rb +21 -0
  24. data/lib/imgproxy/options_casters/size.rb +24 -0
  25. data/lib/imgproxy/options_casters/string.rb +10 -0
  26. data/lib/imgproxy/options_casters/trim.rb +28 -0
  27. data/lib/imgproxy/options_casters/watermark.rb +30 -0
  28. data/lib/imgproxy/trim_array.rb +11 -0
  29. data/lib/imgproxy/url_adapters.rb +0 -4
  30. data/lib/imgproxy/url_adapters/active_storage.rb +25 -0
  31. data/lib/imgproxy/url_adapters/shrine.rb +15 -5
  32. data/lib/imgproxy/version.rb +1 -1
  33. metadata +69 -24
  34. data/lib/imgproxy/url_adapters/active_storage_gcs.rb +0 -31
  35. data/lib/imgproxy/url_adapters/active_storage_s3.rb +0 -23
  36. data/lib/imgproxy/url_adapters/shrine_s3.rb +0 -20
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 3db053d563e38971499a20bcd383713612299136a80b6509f7124826f1350558
4
- data.tar.gz: '049f16f9fc61090577152846c0068353dbcb3eeaa241f54135bb181516296988'
3
+ metadata.gz: 55e93cacc2a68c479e9b76cfadbd45cbe6e0dabc3c12628de3eeef0519f4839b
4
+ data.tar.gz: e0ac82d77ea5ac64fbe47ed895aea1f48bf01de610bece8f344a6afb9c84c2e3
5
5
  SHA512:
6
- metadata.gz: 527be1d77dcac57b5f7170e805f74e7e2f331bc832a7c3d9b136c80e17f7ade7031f67d072511200a63b99320d847af785868a4c5449e649fdcc7a4f6261339b
7
- data.tar.gz: 378492ea2843c3f044a8c34c27a969dd952e1c20fc78eef355304352deb01faf9d050b178e54f9190bbe858444d0ba5ad3f56334b89ce0b7d8aec29acc5b4d13
6
+ metadata.gz: bf8141488c246b00affdb21d533987c7af1345e4fda278f5a08dcc53e2e7e47829f0ce0101502a125c76933a651f4fd9ad45721e08aac5832f6d6c08740c7732
7
+ data.tar.gz: cdf4c6d1d7173d75c6fd11c56c6ebb5242a557071d8e78280ec9b9f451e6ed2ffda5f896b7d4fb2f4fbcc6f4df0e50589b19b7be7cd3e801fc580ea061f1e83d
data/README.md CHANGED
@@ -7,11 +7,11 @@
7
7
 
8
8
  **[imgproxy](https://github.com/imgproxy/imgproxy)** is a fast and secure standalone server for resizing and converting remote images. The main principles of imgproxy are simplicity, speed, and security. It is a Go application, ready to be installed and used in any Unix environment—also ready to be containerized using Docker.
9
9
 
10
- imgproxy can be used to provide a fast and secure way to replace all the image resizing code of your web application (like calling ImageMagick or GraphicsMagick, or using libraries), while also being able to resize everything on the fly, fast and easy. imgproxy is also indispensable when handling lots of image resizing, especially when images come from a remote source.
10
+ imgproxy can be used to provide a fast and secure way to _get rid of all the image resizing code_ in your web application (like calling ImageMagick or GraphicsMagick, or using libraries), while also being able to resize everything on the fly on a separate server that only you control. imgproxy is fast, easy to use, and requires zero processing power or storage from the main application. imgproxy is indispensable when handling image resizing of epic proportions, especially when original images are coming from a remote source.
11
11
 
12
- **imgproxy.rb** is a Ruby Gem for imgproxy that is framework-agnostic, but includes proper support for Ruby on Rails' most popular image attachment options.
12
+ [imgproxy.rb](https://github.com/imgproxy/imgproxy.rb) is a framework-agnostic Ruby Gem for imgproxy that includes proper support for Ruby on Rails' most popular image attachment options: [Active Storage](https://edgeguides.rubyonrails.org/active_storage_overview.html) and [Shrine](https://github.com/shrinerb/shrine).
13
13
 
14
- imgproxy.rb provides easy configuration and URL generation as well as plug&play support for [Active Storage](https://edgeguides.rubyonrails.org/active_storage_overview.html) and [Shrine](https://github.com/shrinerb/shrine).
14
+ **NOTE:** this readme shows documentation for 2.x version. For version 1.x see the [v1.2.0](https://github.com/imgproxy/imgproxy.rb/tree/v1.2.0) tag. See [2.0-Upgrade.md](2.0-Upgrade.md) for the upgrade guide.
15
15
 
16
16
  <a href="https://evilmartians.com/?utm_source=imgproxy.rb">
17
17
  <img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54">
@@ -33,32 +33,81 @@ gem install imgproxy
33
33
 
34
34
  ## Configuration
35
35
 
36
- Next, some basic configuration. We will use a Ruby on Rails application as an example; place the following code to `config/initializers/imgproxy.rb`:
36
+ imgproxy.rb uses [anyway_config](https://github.com/palkan/anyway_config) to load configuration, so you can configure it in different ways.
37
+
38
+ - With a separate config file:
39
+
40
+ ```yaml
41
+ # <Rails root>/config/imgproxy.yml
42
+ development:
43
+ # Full URL to where your imgproxy lives.
44
+ endpoint: "http://imgproxy.example.com"
45
+ # Hex-encoded signature key and salt
46
+ key: "your_key"
47
+ salt: "your_salt"
48
+ production: ...
49
+ test: ...
50
+ ```
51
+
52
+ - With a `secrets.yml` entry for imgproxy:
53
+
54
+ ```yaml
55
+ # secrets.yml
56
+ production:
57
+ ...
58
+ imgproxy:
59
+ # Full URL to where your imgproxy lives.
60
+ endpoint: "http://imgproxy.example.com"
61
+ # Hex-encoded signature key and salt
62
+ key: "your_key"
63
+ salt: "your_salt"
64
+ ...
65
+ ```
66
+
67
+ - With environment variables:
68
+
69
+ ```bash
70
+ IMGPROXY_ENDPOINT="http://imgproxy.example.com"\
71
+ IMGPROXY_KEY="your_key"\
72
+ IMGPROXY_SALT="your_salt"\
73
+ rails s
74
+ ```
75
+
76
+ - ...or right in your application code:
37
77
 
38
78
  ```ruby
39
79
  # config/initializers/imgproxy.rb
40
80
 
41
81
  Imgproxy.configure do |config|
42
- # imgproxy endpoint
43
- #
44
82
  # Full URL to where your imgproxy lives.
45
83
  config.endpoint = "http://imgproxy.example.com"
46
-
47
- # Next, you have to provide your signature key and salt.
48
- # If unsure, check out https://github.com/imgproxy/imgproxy/blob/master/docs/configuration.md first.
49
-
50
- # Hex-encoded signature key
51
- config.hex_key = "your_key"
52
- # Hex-encoded signature salt
53
- config.hex_salt = "your_salt"
84
+ # Hex-encoded signature key and salt
85
+ config.key = "your_key"
86
+ config.salt = "your_salt"
54
87
  end
55
88
  ```
56
89
 
90
+ #### Configuration options
91
+
92
+ - **endpoint** (`IMGPROXY_ENDPOINT`) - Full URL to your imgproxy instance. Default: `nil`.
93
+ - **key** (`IMGPROXY_KEY`) - Hex-encoded signature key. Default: `nil`.
94
+ - **salt** (`IMGPROXY_SALT`) - Hex-encoded signature salt. Default: `nil`.
95
+ - **raw_key** (`IMGPROXY_RAW_KEY`) - Raw (not hex-encoded) signature key. Default: `nil`.
96
+ - **raw_salt** (`IMGPROXY_RAW_SALT`) - Raw (not hex-encoded) signature salt. Default: `nil`.
97
+ - **signature_size** (`IMGPROXY_SIGNATURE_SIZE`) - Signature size. See [URL signature](https://docs.imgproxy.net/#/configuration?id=url-signature) section of imgproxy docs. Default: 32.
98
+ - **use_short_options** (`IMGPROXY_USE_SHORT_OPTIONS`) - Use short processing options names (`rs` for `resize`, `g` for `gravity`, etc). Default: true.
99
+ - **base64_encode_urls** (`IMGPROXY_BASE64_ENCODE_URLS`) - Encode source URLs to base64. Default: false.
100
+ - **always_escape_plain_urls** (`IMGPROXY_ALWAYS_ESCAPE_PLAIN_URLS`) - Always escape plain source URLs even when ones don't need to be escaped. Default: false.
101
+ - **use_s3_urls** (`IMGPROXY_USE_S3_URLS`) - Use `s3://...` source URLs for Active Storage and Shrine attachments stored in Amazon S3. Default: false.
102
+ - **use_gcs_urls** (`IMGPROXY_USE_GCS_URLS`) - Use `gs://...` source URLs for Active Storage and Shrine attachments stored in Google Cloud Storage. Default: false.
103
+ - **gcs_bucket** (`IMGPROXY_GCS_BUCKET`) - Google Cloud Storage bucket name. Default: `nil`.
104
+ - **shrine_host** (`IMGPROXY_SHRINE_HOST`) - Shrine host for locally stored files.
105
+
57
106
  ## Usage
58
107
 
59
108
  ### Using with Active Storage
60
109
 
61
- imgproxy.rb comes with built-in Active Storage support. To enable it, modify your initializer at `config/initializers/imgproxy.rb`:
110
+ imgproxy.rb comes with the Active Storage support built-in. It is enabled _automagically_ if you load `imgproxy` gem after `rails` (basically, just put `gem "imgproxy"` after `gem "rails"` in your `Gemfile`). Otherwise, modify your initializer at `config/initializers/imgproxy.rb`:
62
111
 
63
112
  ```ruby
64
113
  # config/initializers/imgproxy.rb
@@ -72,29 +121,21 @@ Now, to add imgproxy processing to your image attachments, just use the `imgprox
72
121
  user.avatar.imgproxy_url(width: 250, height: 250)
73
122
  ```
74
123
 
75
- will give you an URL to your user's avatar, resized to 250x250px on the fly.
124
+ This method will return an URL to your user's avatar, resized to 250x250px on the fly.
76
125
 
77
- If you have configured both your imgproxy server and Active Storage to work with Amazon S3, you may want to use the short `s3://...` source URL scheme instead of the long one generated by Rails:
126
+ #### Amazon S3
78
127
 
79
- ```ruby
80
- # config/initializers/imgproxy.rb
81
-
82
- Imgproxy.extend_active_storage!(use_s3: true)
83
- ```
84
-
85
- You can do the same if you are using Google Cloud Storage:
128
+ If you have configured both your imgproxy server and Active Storage to work with Amazon S3, you can use `use_s3_urls` config option (or `IMGPROXY_USE_S3_URLS` env variable) to make imgproxy.rb use short `s3://...` source URLs instead of long ones generated by Rails.
86
129
 
87
- ```ruby
88
- # config/initializers/imgproxy.rb
130
+ #### Google Cloud Storage
89
131
 
90
- Imgproxy.extend_active_storage!(use_gcs: true, gcs_bucket: "my_bucket")
91
- ```
132
+ You can also enable `gs://...` URLs usage for the files stored in Google Cloud Storage with `use_gcs_urls` and `gcs_bucket` config options (or `IMGPROXY_USE_GCS_URLS` and `IMGPROXY_GCS_BUCKET` env variables).
92
133
 
93
- **Note** that you need to explicitly provide GCS bucket name since Active Storage "hides" the GCS config.
134
+ **NOTE** that you need to explicitly provide GCS bucket name since Active Storage "hides" the GCS config.
94
135
 
95
136
  ### Using with Shrine
96
137
 
97
- You can also use imgproxy.rb's built-in [Shrine](https://github.com/shrinerb/shrine) support. To enable it, modify your initializer at `config/initializers/imgproxy.rb`:
138
+ You can also use imgproxy.rb's built-in [Shrine](https://github.com/shrinerb/shrine) support. It is enabled automagically if you load `imgproxy` gem after `shrine` (basically, just put `gem "imgproxy"` after `gem "shrine"` in your `Gemfile`). Otherwise, modify your initializer at `config/initializers/imgproxy.rb`:
98
139
 
99
140
  ```ruby
100
141
  # config/initializers/imgproxy.rb
@@ -108,15 +149,9 @@ Now you can use `imgproxy_url` method of `Shrine::UploadedFile`:
108
149
  user.avatar.imgproxy_url(width: 250, height: 250)
109
150
  ```
110
151
 
111
- will give you an URL to your user's avatar, resized to 250x250px on the fly.
112
-
113
- **Note:** If you use `Shrine::Storage::FileSystem` as storage, uploaded file URLs won't include the hostname, so imgproxy server won't be able to access them. To fix this, use `host` option of `Imgproxy.extend_shrine!`:
152
+ This method will return an URL to your user's avatar, resized to 250x250px on the fly.
114
153
 
115
- ```ruby
116
- # config/initializers/imgproxy.rb
117
-
118
- Imgproxy.extend_shrine!(host: "http://your-host.test")
119
- ```
154
+ **NOTE:** If you use `Shrine::Storage::FileSystem` as storage, uploaded file URLs won't include the hostname, so imgproxy server won't be able to access them. To fix this, use `shrine_host` config.
120
155
 
121
156
  Alternatively, you can launch your imgproxy server with the `IMGPROXY_BASE_URL` setting:
122
157
 
@@ -124,13 +159,11 @@ Alternatively, you can launch your imgproxy server with the `IMGPROXY_BASE_URL`
124
159
  IMGPROXY_BASE_URL="http://your-host.test" imgproxy
125
160
  ```
126
161
 
127
- If you have configured both your imgproxy server and Shrine to work with Amazon S3, you may want to use the short `s3://...` source URL scheme instead of the long one generated by Rails:
162
+ #### Amazon S3
128
163
 
129
- ```ruby
130
- Imgproxy.extend_shrine!(use_s3: true)
131
- ```
164
+ If you have configured both your imgproxy server and Shrine to work with Amazon S3, you can use `use_s3_urls` config option (or `IMGPROXY_USE_S3_URLS` env variable) to make imgproxy.rb use short `s3://...` source URLs instead of long ones generated by Shrine.
132
165
 
133
- ### Usage in a framework-agnostic way
166
+ ### Usage imgproxy.rb in a framework-agnostic way
134
167
 
135
168
  If you use another gem for your attachment operations, you like to keep things minimal or Rails-free, or if you want to generate imgproxy URLs for pictures that did not originate from your application, you can use the `Imgproxy.url_for` method:
136
169
 
@@ -159,30 +192,163 @@ builder.url_for("http://images.example.com/images/image1.jpg")
159
192
  builder.url_for("http://images.example.com/images/image2.jpg")
160
193
  ```
161
194
 
162
- ### Available imgproxy options
195
+ ### Supported imgproxy processing options
196
+
197
+ - [resize](https://docs.imgproxy.net/#/generating_the_url_advanced?id=resize)
198
+ - [size](https://docs.imgproxy.net/#/generating_the_url_advanced?id=size)
199
+ - [resizing_type](https://docs.imgproxy.net/#/generating_the_url_advanced?id=resizing-type)
200
+ - [resizing_algorithm](https://docs.imgproxy.net/#/generating_the_url_advanced?id=resizing-algorithm) _(pro)_
201
+ - [width](https://docs.imgproxy.net/#/generating_the_url_advanced?id=width)
202
+ - [height](https://docs.imgproxy.net/#/generating_the_url_advanced?id=height)
203
+ - [dpr](https://docs.imgproxy.net/#/generating_the_url_advanced?id=dpr)
204
+ - [enlarge](https://docs.imgproxy.net/#/generating_the_url_advanced?id=enlarge)
205
+ - [extend](https://docs.imgproxy.net/#/generating_the_url_advanced?id=extend)
206
+ - [gravity](https://docs.imgproxy.net/#/generating_the_url_advanced?id=gravity)
207
+ - [crop](https://docs.imgproxy.net/#/generating_the_url_advanced?id=crop)
208
+ - [padding](https://docs.imgproxy.net/#/generating_the_url_advanced?id=padding)
209
+ - [trim](https://docs.imgproxy.net/#/generating_the_url_advanced?id=trim)
210
+ - [rotate](https://docs.imgproxy.net/#/generating_the_url_advanced?id=rotate)
211
+ - [quality](https://docs.imgproxy.net/#/generating_the_url_advanced?id=quality)
212
+ - [max_bytes](https://docs.imgproxy.net/#/generating_the_url_advanced?id=max-bytes)
213
+ - [background](https://docs.imgproxy.net/#/generating_the_url_advanced?id=background)
214
+ - [background_alpha](https://docs.imgproxy.net/#/generating_the_url_advanced?id=background-alpha) _(pro)_
215
+ - [adjust](https://docs.imgproxy.net/#/generating_the_url_advanced?id=adjust) _(pro)_
216
+ - [brightness](https://docs.imgproxy.net/#/generating_the_url_advanced?id=brightness) _(pro)_
217
+ - [contrast](https://docs.imgproxy.net/#/generating_the_url_advanced?id=contrast) _(pro)_
218
+ - [saturation](https://docs.imgproxy.net/#/generating_the_url_advanced?id=saturation) _(pro)_
219
+ - [blur](https://docs.imgproxy.net/#/generating_the_url_advanced?id=blur)
220
+ - [sharpen](https://docs.imgproxy.net/#/generating_the_url_advanced?id=sharpen)
221
+ - [pixelate](https://docs.imgproxy.net/#/generating_the_url_advanced?id=pixelate) _(pro)_
222
+ - [unsharpening](https://docs.imgproxy.net/#/generating_the_url_advanced?id=unsharpening) _(pro)_
223
+ - [watermark](https://docs.imgproxy.net/#/generating_the_url_advanced?id=watermark)
224
+ - [watermark_url](https://docs.imgproxy.net/#/generating_the_url_advanced?id=watermark-url) _(pro)_
225
+ - [style](https://docs.imgproxy.net/#/generating_the_url_advanced?id=style) _(pro)_
226
+ - [jpeg_options](https://docs.imgproxy.net/#/generating_the_url_advanced?id=jpeg-options) _(pro)_
227
+ - [png_options](https://docs.imgproxy.net/#/generating_the_url_advanced?id=png-options) _(pro)_
228
+ - [gif_options](https://docs.imgproxy.net/#/generating_the_url_advanced?id=gif-options) _(pro)_
229
+ - [page](https://docs.imgproxy.net/#/generating_the_url_advanced?id=page) _(pro)_
230
+ - [video_thumbnail_second](https://docs.imgproxy.net/#/generating_the_url_advanced?id=video-thumbnail-second) _(pro)_
231
+ - [preset](https://docs.imgproxy.net/#/generating_the_url_advanced?id=preset)
232
+ - [cachebuster](https://docs.imgproxy.net/#/generating_the_url_advanced?id=cachebuster)
233
+ - [strip_metadata](https://docs.imgproxy.net/#/generating_the_url_advanced?id=strip-metadata)
234
+ - [strip_color_profile](https://docs.imgproxy.net/#/generating_the_url_advanced?id=strip-color-profile)
235
+ - [auto_rotate](https://docs.imgproxy.net/#/generating_the_url_advanced?id=auto-rotate)
236
+ - [filename](https://docs.imgproxy.net/#/generating_the_url_advanced?id=filename)
237
+ - [format](https://docs.imgproxy.net/#/generating_the_url_advanced?id=format)
238
+
239
+ _See [imgproxy URL format guide](https://docs.imgproxy.net/#/generating_the_url_advanced?id=processing-options) for more info._
240
+
241
+ ### Complex processing options
242
+
243
+ Some of the processing options like `crop` or `gravity` may have multiple arguments, and you can define these arguments multiple ways:
244
+
245
+ #### Named arguments
246
+
247
+ First and the most readable way is to use a `Hash` with named arguments:
248
+
249
+ ```ruby
250
+ Imgproxy.url_for(
251
+ "http://images.example.com/images/image.jpg",
252
+ crop: {
253
+ width: 500,
254
+ height: 600,
255
+ gravity: {
256
+ type: :nowe,
257
+ x_offset: 10,
258
+ y_offset: 5
259
+ }
260
+ }
261
+ )
262
+ # => .../c:500:600:nowe:10:5/...
263
+ ```
264
+
265
+ All the argguments have the same names as in [imgproxy documentation](https://docs.imgproxy.net/#/generating_the_url_advanced?id=processing-options).
266
+
267
+ You can use named arguments even if the processing option is not supported by the gem. In this case the arguments won't be reordered nor formatted, so you should provide them in the same order and right the same way they should appear in the URL:
268
+
269
+ ```ruby
270
+ Imgproxy.url_for(
271
+ "http://images.example.com/images/image.jpg",
272
+ unsupported: {
273
+ arg1: 1,
274
+ nested1: {
275
+ arg2: 2,
276
+ nested2: {
277
+ arg3: 3
278
+ }
279
+ }
280
+ }
281
+ )
282
+ # => .../unsupported:1:2:3/...
283
+ ```
284
+
285
+ #### Unnamed arguments
163
286
 
164
- * `resizing_type` — defines how imgproxy will resize the image. See [URL format guide](https://github.com/imgproxy/imgproxy/blob/master/docs/generating_the_url_advanced.md#resizing-type) for available values.
165
- * `width` — defines the width of the resulting image.
166
- * `height` — defines the height of the resulting image.
167
- * `dpr` — when set, imgproxy will multiply the image dimensions according to this factor for HiDPI (Retina) devices.
168
- * `enlarge` — when true, imgproxy will enlarge the image if it is smaller than the given size.
169
- * `extend` — when true, imgproxy will extend the image if the resizing result is smaller than the given size.
170
- * `gravity` — defines gravity that will be used when imgproxy needs to cut some parts of the image. See [URL format guide](https://github.com/imgproxy/imgproxy/blob/master/docs/generating_the_url_advanced.md#gravity) for available values.
171
- * `gravity_x`, `gravity_y` — floating point numbers between 0 and 1 that define the coordinates of the center of the resulting image when `fp` gravity is used.
172
- * `quality` — defines the quality of the resulting image, percentage.
173
- * `background` — when set, imgproxy will fill the resulting image background with the specified color. Can be a hex-color string or an array of red, green and blue values (0-255).
174
- * `blur` — when set, imgproxy will apply the gaussian blur filter to the resulting image. Value is the size of a mask imgproxy will use.
175
- * `sharpen` — when set, imgproxy will apply the sharpen filter to the resulting image. Value is the size of a mask imgproxy will use.
176
- * `watermark_opacity` — when set, imgproxy will put a watermark on the resulting image. See [watermars guide](https://github.comimgproxym/imgproxy/blob/master/docs/watermark.md) for more info.
177
- * `watermark_position`, `watermark_x_offset`, `watermark_y_offset`, `watermark_scale` — additional watermark options described in the [watermars guide](https://github.com/imgproxy/imgproxy/blob/master/docs/watermark.md).
178
- * `preset` — array of names of presets that will be used by imgproxy. See [presets guide](https://github.com/imgproxy/imgproxy/blob/master/docs/presets.md) for more info.
179
- * `cachebuster` — defines cache buster that doesn't affect image processing but it's changing allows to bypass CDN, proxy server and browser cache.
180
- * `format` — specifies the resulting image format (`jpg`, `png`, `webp`).
181
- * `use_short_options` — per-call redefinition of `use_short_options` config.
287
+ The arguments of the complex options can be provided as an array of formatted values or even as a colon-separated string:
288
+
289
+ ```ruby
290
+ Imgproxy.url_for(
291
+ "http://images.example.com/images/image.jpg",
292
+ crop: [500, 600, :nowe, 10, 5],
293
+ trim: "10:aabbcc:1:1"
294
+ )
295
+ # => .../c:500:600:nowe:10:5/t:10:aabbcc:1:1/...
296
+ ```
182
297
 
183
- **See [imgproxy URL format guide](https://github.com/imgproxy/imgproxy/blob/master/docs/generating_the_url_advanced.md) for more info.**
298
+ #### Single required argument
184
299
 
185
- ### URL adapters
300
+ If a complex option has a single required argument, and you don't want to use the optional ones, you can just use its value:
301
+
302
+ ```ruby
303
+ Imgproxy.url_for(
304
+ "http://images.example.com/images/image.jpg",
305
+ gravity: :nowe,
306
+ trim: 10
307
+ )
308
+ # => .../g:nowe/t:10/...
309
+ ```
310
+
311
+ ### Base64 processing options arguments
312
+
313
+ Some of the processing options like `watermark_url` or `style` require their arguments to be base64-encoded. Good news is that imgproxy gem will encode them for you:
314
+
315
+ ```ruby
316
+ Imgproxy.url_for(
317
+ "http://images.example.com/images/image.jpg",
318
+ watermark_url: "http://example.com/watermark.jpg",
319
+ style: "color: rgba(255, 255, 255, .5)"
320
+ )
321
+ # => .../wmu:aHR0cDovL2V4YW1wbGUuY29tL3dhdGVybWFyay5qcGc/st:Y29sb3I6IHJnYmEoMjU1LCAyNTUsIDI1NSwgLjUp/...
322
+ ```
323
+
324
+ ### Special options:
325
+
326
+ - `base64_encode_url` — per-call redefinition of `base64_encode_urls` config.
327
+ - `escape_plain_url` — per-call redefinition of `always_escape_plain_urls` config.
328
+ - `use_short_options` — per-call redefinition of `use_short_options` config.
329
+
330
+ ## Getting the image info
331
+
332
+ If you're a happy user of imgproxy Pro, you may find useful it's [Getting the image info](https://docs.imgproxy.net/#/getting_the_image_info) feature. imgproxy.rb allows you to easily generate info URLs for your images:
333
+
334
+ ```ruby
335
+ # Framework-agnositic way
336
+ Imgproxy.info_url_for("http://images.example.com/images/image.jpg")
337
+ # Using Active Storage or Shrine
338
+ user.avatar.imgproxy_info_url
339
+
340
+ # You can also use base64_encode_url or escape_plain_url options
341
+ Imgproxy.info_url_for(
342
+ "http://images.example.com/images/image.jpg",
343
+ base64_encode_url: true
344
+ )
345
+ Imgproxy.info_url_for(
346
+ "http://images.example.com/images/image.jpg",
347
+ escape_plain_url: true
348
+ )
349
+ ```
350
+
351
+ ## URL adapters
186
352
 
187
353
  By default, `Imgproxy.url_for` accepts only `String` and `URI` as the source URL, but you can extend that behavior by using URL adapters.
188
354
 
@@ -209,35 +375,9 @@ Imgproxy.configure do |config|
209
375
  end
210
376
  ```
211
377
 
212
- **Note:** `Imgproxy` will use the first applicable URL adapter. If you need to add your adapter to the beginning of the list, use the `prepend` method instead of `add`.
213
-
214
- **Note:** imgproxy.rb provides built-inadapters for Active Storage and Shrine that are automatically added by `Imgproxy.extend_active_storage!` and `Imgproxy.extend_shrine!`.
215
-
216
- ## Further configuration
217
-
218
- ### Using truncated signature
219
-
220
- By default, the imgproxy server uses a full-length signature (32 bytes), but you can set signature length with `IMGPROXY_SIGNATURE_SIZE` environment variable. If you have configured your imgproxy server to use truncated signatures, you need to configure the gem too:
221
-
222
- ```ruby
223
- # config/initializers/imgproxy.rb
224
-
225
- Imgproxy.configure do |config|
226
- config.signature_size = 5
227
- end
228
- ```
229
-
230
- ### Using full processing options names
231
-
232
- By default, imgproxy gem uses short processing options names (`rs` for `resize`, `g` for `gravity`, etc), but it can be configured to use full names:
233
-
234
- ```ruby
235
- # config/initializers/imgproxy.rb
378
+ **NOTE:** `Imgproxy` will use the first applicable URL adapter. If you need to add your adapter to the beginning of the list, use the `prepend` method instead of `add`.
236
379
 
237
- Imgproxy.configure do |config|
238
- config.use_short_options = false
239
- end
240
- ```
380
+ **NOTE:** imgproxy.rb provides built-in adapters for Active Storage and Shrine that are automatically added when Active Storage or Shrine support is enabled.
241
381
 
242
382
  ## Contributing
243
383
 
@@ -248,3 +388,7 @@ If you are having any problems with image processing of imgproxy itself, be sure
248
388
  ## License
249
389
 
250
390
  The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
391
+
392
+ ## Security Contact
393
+
394
+ To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security). Tidelift will coordinate the fix and disclosure.
data/lib/imgproxy.rb CHANGED
@@ -19,8 +19,8 @@ module Imgproxy
19
19
  #
20
20
  # Imgproxy.configure do |config|
21
21
  # config.endpoint = "http://imgproxy.example.com"
22
- # config.hex_key = "your_key"
23
- # config.hex_salt = "your_salt"
22
+ # config.key = "your_key"
23
+ # config.salt = "your_salt"
24
24
  # config.use_short_options = true
25
25
  # end
26
26
  #
@@ -38,72 +38,112 @@ module Imgproxy
38
38
  # width: 500,
39
39
  # height: 400,
40
40
  # resizing_type: :fill,
41
- # sharpen: 0.5
41
+ # sharpen: 0.5,
42
+ # gravity: {
43
+ # type: :soea,
44
+ # x_offset: 10,
45
+ # y_offset: 5,
46
+ # },
47
+ # crop: {
48
+ # width: 2000,
49
+ # height: 1000,
50
+ # gravity: {
51
+ # type: :nowe,
52
+ # x_offset: 20,
53
+ # y_offset: 30,
54
+ # },
55
+ # },
42
56
  # )
43
57
  #
44
58
  # @return [String] imgproxy URL
45
59
  # @param [String,URI, Object] image Source image URL or object applicable for
46
60
  # the configured URL adapters
47
61
  # @param [Hash] options Processing options
62
+ # @option options [Hash|Array|String] :resize
63
+ # @option options [Hash|Array|String] :size
48
64
  # @option options [String] :resizing_type
65
+ # @option options [String] :resizing_algorithm supported only by imgproxy pro
49
66
  # @option options [Integer] :width
50
67
  # @option options [Integer] :height
51
68
  # @option options [Float] :dpr
52
69
  # @option options [Boolean] :enlarge
53
- # @option options [Boolean] :extend
54
- # @option options [String] :gravity
55
- # @option options [Float] :gravity_x
56
- # @option options [Float] :gravity_y
70
+ # @option options [Hash|Array|Boolean|String] :extend
71
+ # @option options [Hash|Array|String] :gravity
72
+ # @option options [Hash|Array|String] :crop
73
+ # @option options [Array] :padding
74
+ # @option options [Hash|Array|String] :trim
75
+ # @option options [Integer] :rotate
57
76
  # @option options [Integer] :quality
58
- # @option options [Array] :background
77
+ # @option options [Integer] :max_bytes
78
+ # @option options [Array|String] :background
79
+ # @option options [Float] :background_alpha supported only by imgproxy pro
80
+ # @option options [Hash|Array|String] :adjust
81
+ # @option options [Integer] :brightness supported only by imgproxy pro
82
+ # @option options [Float] :contrast supported only by imgproxy pro
83
+ # @option options [Float] :saturation supported only by imgproxy pro
59
84
  # @option options [Float] :blur
60
85
  # @option options [Float] :sharpen
61
- # @option options [Float] :watermark_opacity
62
- # @option options [String] :watermark_position
63
- # @option options [Integer] :watermark_x_offset
64
- # @option options [Integer] :watermark_y_offset
65
- # @option options [Float] :watermark_scale
86
+ # @option options [Integer] :pixelate supported only by imgproxy pro
87
+ # @option options [String] :unsharpening supported only by imgproxy pro
88
+ # @option options [Hash|Array|Float|String] :watermark
89
+ # @option options [String] :watermark_url supported only by imgproxy pro
90
+ # @option options [String] :style supported only by imgproxy pro
91
+ # @option options [Hash|Array|String] :jpeg_options supported only by imgproxy pro
92
+ # @option options [Hash|Array|String] :png_options supported only by imgproxy pro
93
+ # @option options [Hash|Array|String] :gif_options supported only by imgproxy pro
94
+ # @option options [Integer] :page supported only by imgproxy pro
95
+ # @option options [Integer] :video_thumbnail_second supported only by imgproxy pro
66
96
  # @option options [Array] :preset
67
97
  # @option options [String] :cachebuster
98
+ # @option options [Boolean] :strip_metadata
99
+ # @option options [Boolean] :strip_color_profile
100
+ # @option options [Boolean] :auto_rotate
101
+ # @option options [String] :filename
68
102
  # @option options [String] :format
69
103
  # @option options [Boolean] :use_short_options
70
- # @see https://github.com/DarthSim/imgproxy/blob/master/docs/generating_the_url_advanced.md
71
- # imgproxy URL format documentation
104
+ # @option options [Boolean] :base64_encode_urls
105
+ # @option options [Boolean] :escape_plain_url
106
+ # @see https://docs.imgproxy.net/#/generating_the_url_advanced?id=processing-options
107
+ # Available imgproxy URL processing options and their arguments
72
108
  def url_for(image, options = {})
73
109
  Imgproxy::Builder.new(options).url_for(image)
74
110
  end
75
111
 
76
- # Extends ActiveStorage::Blob with {Imgproxy::Extensions::ActiveStorage.imgproxy_url} method
77
- # and adds URL adapters for ActiveStorage
112
+ # Genrates imgproxy info URL. Supported only by imgproxy pro
78
113
  #
79
- # @return [void]
80
- # @param use_s3 [Boolean] enable Amazon S3 source URLs
81
- # @param use_gcs [Boolean] enable Google Cloud Storage source URLs
82
- # @param gcs_bucket [String] Google Cloud Storage bucket name
83
- def extend_active_storage!(use_s3: false, use_gcs: false, gcs_bucket: nil)
84
- ActiveSupport.on_load(:active_storage_blob) do
85
- ::ActiveStorage::Blob.include Imgproxy::Extensions::ActiveStorage
114
+ # Imgproxy.info_url_for("http://images.example.com/images/image.jpg")
115
+ #
116
+ # @return [String] imgproxy info URL
117
+ # @param [String,URI, Object] image Source image URL or object applicable for
118
+ # the configured URL adapters
119
+ # @param [Hash] options Processing options
120
+ # @option options [Boolean] :base64_encode_urls
121
+ # @option options [Boolean] :escape_plain_url
122
+ def info_url_for(image, options = {})
123
+ Imgproxy::Builder.new(options).info_url_for(image)
124
+ end
86
125
 
87
- url_adapters = Imgproxy.config.url_adapters
126
+ # Extends +ActiveStorage::Blob+ with {Imgproxy::Extensions::ActiveStorage.imgproxy_url} method
127
+ # and adds URL adapters for ActiveStorage
128
+ def extend_active_storage!
129
+ return unless defined?(ActiveSupport) && ActiveSupport.respond_to?(:on_load)
88
130
 
89
- url_adapters.add(Imgproxy::UrlAdapters::ActiveStorageS3.new) if use_s3
90
- url_adapters.add(Imgproxy::UrlAdapters::ActiveStorageGCS.new(gcs_bucket)) if use_gcs
91
- url_adapters.add(Imgproxy::UrlAdapters::ActiveStorage.new)
131
+ ActiveSupport.on_load(:active_storage_blob) do
132
+ ::ActiveStorage::Blob.include Imgproxy::Extensions::ActiveStorage
133
+ Imgproxy.config.url_adapters.add(Imgproxy::UrlAdapters::ActiveStorage.new)
92
134
  end
93
135
  end
94
136
 
95
- # Extends Shrine::UploadedFile with {Imgproxy::Extensions::Shrine.imgproxy_url} method
137
+ # Extends +Shrine::UploadedFile+ with {Imgproxy::Extensions::Shrine.imgproxy_url} method
96
138
  # and adds URL adapters for Shrine
97
- #
98
- # @return [void]
99
- # @param use_s3 [Boolean] enable Amazon S3 source URLs
100
- def extend_shrine!(host: nil, use_s3: false)
101
- ::Shrine::UploadedFile.include Imgproxy::Extensions::Shrine
102
-
103
- url_adapters = Imgproxy.config.url_adapters
139
+ def extend_shrine!
140
+ return unless defined?(::Shrine::UploadedFile)
104
141
 
105
- url_adapters.add(Imgproxy::UrlAdapters::ShrineS3.new) if use_s3
106
- url_adapters.add(Imgproxy::UrlAdapters::Shrine.new(host: host))
142
+ ::Shrine::UploadedFile.include Imgproxy::Extensions::Shrine
143
+ Imgproxy.config.url_adapters.add(Imgproxy::UrlAdapters::Shrine.new)
107
144
  end
108
145
  end
109
146
  end
147
+
148
+ Imgproxy.extend_active_storage!
149
+ Imgproxy.extend_shrine!