Skip to content

Commit c3f6820

Browse files
jasonvargajackmcdade
jasonvarga
and
jackmcdade
authored
Improve glide docs (statamic#791)
Co-authored-by: Jack McDade <[email protected]>
1 parent 9f381c8 commit c3f6820

File tree

6 files changed

+327
-41
lines changed

6 files changed

+327
-41
lines changed

‎content/collections/docs/image-manipulation.md

+169
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
---
2+
id: 245068a1-1900-4774-a3ba-29192dc9acff
3+
blueprint: page
4+
title: 'Image Manipulation (Glide)'
5+
intro: Statamic uses [Glide](https://glide.thephpleague.com) to manipulate images – from resizing and cropping to adjustments (like sharpness and contrast) and image effects (like pixelate and sepia).
6+
---
7+
## Route
8+
The route controls where your Glide images will be served.
9+
10+
```php
11+
'image_manipulation' => [
12+
'route' => 'img'
13+
]
14+
```
15+
16+
By default your Glide images will be served from `'/img/...'` but you are free to change that. Perhaps if you intend to have some actual images stored in the `img` directory.
17+
18+
:::tip
19+
This route setting may become irrelevant when using customizing [caching options](#caching) explained further down this page.
20+
:::
21+
22+
## Presets
23+
24+
Glide Presets are pre-configured manipulations that will be automatically generated when new image assets are uploaded. These presets are managed in `config/statamic/assets.php` as an array that holds a list of named presets and their desired parameters.
25+
26+
```php
27+
'image_manipulation' => [
28+
'presets' => [
29+
'thumbnail' => [ 'w' => 300, 'h' => 300, 'q' => 75],
30+
'hero' => [ 'w' => 1440 'h' => 600, 'q' => 90 ],
31+
],
32+
],
33+
```
34+
35+
All standard Glide API parameters are available for use in presets. (Not the tag aliases like `width`. You'll need to use `w`.)
36+
37+
Each named preset can be referenced with the `preset` parameter on the [Glide tag][glide-tag] and since all transformations and manipulations are performed at time of upload, there shouldn't be any additional overhead on the initial request.
38+
39+
**Example:**
40+
41+
```
42+
{{ glide:thumbnail preset="thumbnail" }}
43+
<!-- width: 300px, height: 300px, quality: 75% -->
44+
45+
{{ glide:hero_image preset="hero" }}
46+
<!-- width: 1440px, height: 600px, quality: 90% -->
47+
```
48+
49+
## Caching
50+
51+
Out of the box, Glide will "just work". However you may want to adjust its caching methods for better performance.
52+
53+
In the context of Glide, the "source" is the filesystem where the original images are kept, and the "cache" is the filesystem where it saves the manipulated images.
54+
55+
### Default (Dynamic)
56+
57+
The default behavior is for the cache to be "disabled" or "dynamic".
58+
59+
```php
60+
// config/statamic/assets.php
61+
'image_manipulation' => [
62+
'route' => 'img',
63+
'cache' => false,
64+
]
65+
```
66+
67+
From a user's point of view, the "cache" is disabled, however technically it's just located at `storage/statamic/glide`.
68+
69+
The [Glide tag][glide-tag] will output URLs to the configured Glide [route](#route). When one of these URLs are visited, Statamic will use Glide to perform the transformation.
70+
71+
:::tip
72+
When using this method, since the Glide tag only needs to generate URLs, the load time of the page will be faster, but the initial load time of each image request will be slower.
73+
:::
74+
75+
### Custom Path (Static)
76+
77+
The next level of caching would be to specify a custom, publicly accessible location for the images to be generated.
78+
79+
``` php
80+
// config/statamic/assets.php
81+
82+
'image_manipulation' => [
83+
'route' => 'img',
84+
'cache' => true,
85+
'cache_path' => public_path('img'),
86+
]
87+
```
88+
89+
When using this setting, the [Glide tag][glide-tag] will _actually generate_ the images instead of just outputting a URL.
90+
91+
Since the images are generated to a publicly accessible location, the next time a user visits the image URL, the static image would be served directly by the server, and would not need to be touched by PHP or Statamic.
92+
93+
:::tip
94+
When using this method, since the Glide tag has to generate the images, the initial load time of the page will be slower.
95+
:::
96+
97+
### Custom Disk (CDN)
98+
99+
You may choose to save your cached Glide images to somewhere CDN based, like Amazon S3 or DigitalOcean Spaces. Instead of specifying `true` as mentioned above, you can point to a filesystem disk.
100+
101+
```php
102+
// config/statamic/assets.php
103+
104+
'image_manipulation' => [
105+
'cache' => 'glide',
106+
],
107+
```
108+
109+
```php
110+
// config/filesystems.php [tl! **]
111+
112+
'disks' => [ // [tl! **]
113+
'glide' => [ // [tl! **]
114+
'driver' => 's3', // [tl! **]
115+
'key' => env('AWS_ACCESS_KEY_ID'),
116+
'secret' => env('AWS_SECRET_ACCESS_KEY'),
117+
'region' => env('AWS_DEFAULT_REGION'),
118+
'bucket' => env('AWS_BUCKET'),
119+
'url' => env('AWS_URL'), // [tl! **]
120+
'endpoint' => env('AWS_ENDPOINT'),
121+
'use_path_style_endpoint' => env('AWS_USE_PATH_STYLE_ENDPOINT', false),
122+
'visibility' => 'public', // [tl! **]
123+
],
124+
]
125+
```
126+
127+
:::tip
128+
Make sure that the `visibility` is `public` and that the `url` points to the correct location.
129+
:::
130+
131+
:::warning
132+
Don't use the same disk or bucket as your source images. If you were you to clear your Glide cache (e.g. when using the `glide:clear` command) the whole disk will be emptied.
133+
:::
134+
135+
## Path Cache Store
136+
137+
Before Glide tries to generate an image, it will look into the filesystem to determine whether the image has already been generated. This will prevent the need for the image to be needlessly re-generated.
138+
139+
However, when using the [Custom Disk CDN](#custom-disk-cdn) caching option with a service like Amazon S3 for example, Glide will need to make an API call just to be able to check if a file exists. This would cause a slowdown.
140+
141+
To alleviate this problem, Statamic will keep track of whether the images have already been generated in its own separate cache.
142+
143+
This cache is separate from your application cache. Running `php artisan cache:clear` will **not** clear this Glide cache. This allows the Glide cache to persist through deployments or other scenarios where you might clear your application cache. It will be cleared when running `php please glide:clear`.
144+
145+
By default, this cache will be located in your filesystem with the storage directory.
146+
147+
If you would like to customize it, you can create a new store named `glide` in your `config/cache.php` configuration file. For example:
148+
149+
```php
150+
'stores' => [
151+
'file' => [
152+
'driver' => 'redis',
153+
'connection' => 'glide',
154+
],
155+
]
156+
```
157+
158+
## Clearing the cache
159+
160+
You may manually clear the Glide cache by running the following command:
161+
162+
```
163+
php artisan glide:clear
164+
```
165+
166+
This will **delete all the files** within your Glide cache filesystem location, as well as clearing the [path cache](#path-cache-store).
167+
168+
169+
[glide-tag]: /tags/glide

‎content/collections/tags/glide.md

+128-41
Original file line numberDiff line numberDiff line change
@@ -124,6 +124,45 @@ filters:
124124
type: string
125125
description: >
126126
Applies a filter effect to the image. Accepts `greyscale` or `sepia`.
127+
other:
128+
-
129+
name: preset
130+
type: string
131+
description: >
132+
Applies a [preset manipulation](/image-manipulation#presets) as defined in the config.
133+
-
134+
name: mark
135+
type: string
136+
description: >
137+
The source of a [watermark](#watermarks).
138+
-
139+
name: markw
140+
type: string
141+
description: The width of the watermark.
142+
-
143+
name: markh
144+
type: string
145+
description: The height of the watermark.
146+
-
147+
name: markfit
148+
type: string
149+
description: The fit of the watermark. [See Glide docs](https://glide.thephpleague.com/2.0/api/watermarks/#fit-markfit)
150+
-
151+
name: markx
152+
type: string
153+
description: How far the watermark is away from the left and right edges.
154+
-
155+
name: marky
156+
type: string
157+
description: How far the watermark is away from the top and bottom edges.
158+
-
159+
name: markpad
160+
type: string
161+
description: How far the watermark is away from all edges. A shortcut for using markx and marky.
162+
-
163+
name: markpos
164+
type: string
165+
description: Sets where the watermark is positioned. Accepts `top-left`, `top`, `top-right`, `left`, `center`, `right`, `bottom-left`, `bottom`, `bottom-right`. Default is `bottom-right`.
127166
variables:
128167
-
129168
name: url
@@ -137,21 +176,55 @@ variables:
137176
name: height
138177
type: integer
139178
description: The height of the resized image.
179+
-
180+
name: asset data
181+
type: mixed
182+
description: If your source was an asset, you will also have all of its fields available. e.g. `alt`
140183
id: b70a3d9a-6605-446e-b278-de99ba561fe0
141184
---
142-
## Overview
185+
## Setting up Glide
186+
Glide is ready to go out of the box with no setup required. However, you may customize its behavior. You can read about it on the [image manipulation](/image-manipulation) page.
143187

144-
The Glide tag leverages the fantastic [Glide](http://glide.thephpleague.com/) PHP library to give you on-demand image manipulation, similar to cloud image processing services like [Imgix](https://www.imgix.com/) and [Cloudinary](https://cloudinary.com/).
188+
## Basic Usage
145189

190+
Manipulate images by passing an image [source](#sources) and adding the desired [parameters](#parameters) like `height`, `crop`, or `quality`.
191+
192+
```
193+
{{ glide src="image.jpg" width="1280" height="800" }}
194+
```
195+
```output
196+
/img/image.jpg?w=1280&h=800
197+
```
146198

147-
Manipulate images by passing a variable or an explicit URL and adding the desired [parameters](#parameters) like `height`, `crop`, or `quality`.
199+
The Glide tag outputs a URL of the transformed image, so you'll likely want to use it as the `src` for an `<img />` HTML tag.
148200

149201
```
150-
// Variable
151-
<img src="{{ glide:hero_image width="1280" height="800" }}">
202+
<img src="{{ glide ... }}" />
203+
```
204+
205+
## Sources
206+
207+
There are a number of options when it comes to what you can use as an image source.
208+
209+
### Asset
210+
You can pass along an asset object by using an asset field by reference:
152211

153-
// URL
154-
<img src="{{ glide src="/img/heroes/slime.jpg" width="1280" height="800" }}">
212+
```
213+
{{ glide :src="asset_field" w="100" }} // /img/asset/6f75d8as?w=100
214+
```
215+
216+
### Relative path/URL
217+
You can pass a string of a path located within your `public` directory.
218+
219+
```
220+
{{ glide src="image.jpg" w="100" }} // img/image.jpg?w=100
221+
```
222+
223+
### External URL
224+
You can pass a string of a URL on another site.
225+
226+
```
227+
{{ glide src="http://anothersite.com/image.jpg" w="100" }} // /img/http/6f75d8as?w=100
155228
```
156229

157230

@@ -160,36 +233,68 @@ Manipulate images by passing a variable or an explicit URL and adding the desire
160233
If you use the tag as a pair, you'll have access to `url`, `height`, and `width` variables inside to do with as you wish.
161234

162235
```
163-
{{ glide:image width="600" }}
236+
{{ glide src="image.jpg" width="600" }}
164237
<img src="{{ url }}" width="{{ width }}" height="{{ height }}">
165-
{{ /glide:image }}
238+
{{ /glide }}
239+
```
240+
241+
You may also use the tag pair to loop over multiple sources. For example, you may provide it with an `assets` field.
242+
243+
```
244+
{{ glide :src="multiple_assets" width="600" }}
245+
...
246+
{{ /glide }}
166247
```
167248

168-
## Presets
249+
:::tip
250+
The tag pair is also available as `{{ glide:generate }}`. You may need to use this version if you're using [Blade](#usage-in-blade).
251+
:::
169252

170-
Glide Presets are pre-configured manipulations that will be automatically generated when new image assets are uploaded. These presets are managed in `config/statamic/assets.php` as an array that holds a list of named presets and their desired parameters.
253+
:::tip
254+
Normally, the Glide tag only generates a URL. The image itself is generated when the URL is visited. When using the tag pair, your Glide images will be generated when the page is rendered. This will result in an initial longer load time.
255+
:::
171256

172-
```php
173-
'presets' => [
174-
'thumbnail' => [ 'w' => 300, 'h' => 300, 'q' => 75],
175-
'hero' => [ 'w' => 1440 'h' => 600, 'q' => 90 ],
176-
],
257+
258+
## Shorthand Tag
259+
260+
Rather than using the `src` parameter, you may choose to use a variable name as the second part of the tag.
261+
262+
```
263+
{{ glide:my_var w="100" }}
264+
```
265+
266+
You may also use the shorthand as a tag pair:
267+
268+
```
269+
{{ glide:my_var }} ... {{ /glide:my_var }}
177270
```
178271

179-
All [parameters](#parameters) are available for use in presets.
180272

181-
Each named preset can be referenced with the `preset` tag parameter and since all transformations and manipulations are performed at time of upload, there shouldn't be any additional overhead on the initial request.
273+
## Watermarks
182274

183-
**Example:**
275+
You may use Glide's [watermarking feature](https://glide.thephpleague.com/2.0/api/watermarks/) by passing in a [source](#sources) to the `mark` parameter, and then manipulate it using the various watermark parameters (`markw`, `markh`, `markfit`, etc).
184276

185277
```
186-
{{ glide:thumbnail preset="thumbnail" }}
187-
<!-- width: 300px, height: 300px, quality: 75% -->
278+
{{ glide src="image.jpg" mark="watermark.jpg" markw="30" }}
279+
```
280+
281+
:::tip
282+
You don't need to worry about setting up a watermark filesystem yourself. Statamic will take care of that automatically based on the source you provide.
283+
:::
284+
285+
286+
## Usage in Blade
287+
288+
To use the Glide tag within Blade, you should use the `generate` tag, which follows the same rules as the [tag pair](#tag-pair).
188289

189-
{{ glide:hero_image preset="hero" }}
190-
<!-- width: 1440px, height: 600px, quality: 90% -->
290+
```blade
291+
@foreach (Statamic::tag('glide:generate')->src($source)->width(100) as $image)
292+
<img src="{{ $image['url'] }} width="{{ $image['width'] }}" />
293+
@endforeach
191294
```
192295

296+
You should use a `@foreach` loop even if you are only providing a single source.
297+
193298
## Focal Point Cropping
194299

195300
Focal point cropping helps ensure the important bits of an image stay in the bounds of any crops you perform.
@@ -240,21 +345,3 @@ images:
240345
<img src="/img/image.jpg?w=600" />
241346
<img src="/assets/image.svg" />
242347
```
243-
244-
## Serving Cached Images Directly
245-
246-
The default Glide tag behavior is to simply output a URL. When a URL is visited, Glide analyzes the URL and manipulates the image. However, if there are a lot of manipulations on any given page request, the total execution time can soon start to add up.
247-
248-
You can avoid these slowdowns by generating static images. Your server will load images directly instead of handing the work over to the Glide process each time. You can enable this behavior in your assets config file.
249-
250-
``` php
251-
// config/statamic/assets.php
252-
253-
'cache' => true,
254-
```
255-
256-
## Using Glide with Locales
257-
258-
When using Glide with multiple locales, the generated image path will include the proper `site_root` as dictated by the locale, but the actual asset will be stored wherever you have set the `cache_path`.
259-
260-
To serve these assets when on a localized version, you'll need to create a symlink from your `/$locale/cache_path` to `cache_path`.

‎content/trees/collections/docs.yaml

+2
Original file line numberDiff line numberDiff line change
@@ -147,6 +147,8 @@ tree:
147147
entry: 2e0d2f8f-319d-4cce-bd90-16d6ad32ad37
148148
-
149149
entry: fc564ddf-80c1-4d87-8675-4a41f13c7774
150+
-
151+
entry: 245068a1-1900-4774-a3ba-29192dc9acff
150152
-
151153
entry: c095fb87-4c02-462c-9e6f-dfe0b6889248
152154
-

0 commit comments

Comments
 (0)