Thumbor'd Silverstripe 4 Images including support for protected image assets
This module pushes image thumbnail generation to a Thumbor open source image server.
Images generated by Thumbor bypass the standard Intervention backend provided by Silverstripe and are instead generated and served from a Thumbor server. Original images are uploaded and stored in the standard assets location in a Silverstripe installation.
SilverStripe 3 compatible version - v0.1
Future releases for SilverStripe 4 will be tagged v0.2 and up.
This is a new module, considered pre-release at the moment
From the Thumbor website itself:
Thumbor is a smart imaging service. It enables on-demand crop, resizing and flipping of images. It features a very smart detection of important points in the image for better cropping and resizing, using state-of-the-art face and feature detection algorithms
Thumbor is written in Python and is easily installed via PIP and configured using a standard configuration file.
Thumbor takes the load off your SilverStripe website. Your web stack is busy processing requests and shouldn't be resizing images on demand.
With this module, your users upload images via the usual SilverStripe upload process (e.g FileField, UploadField) and the system then hands off resizing and cropping to Thumbor, via a specific URL.
The Thumbor server can exist anywhere, provided the URLs for the Thumbor generated images point to it and the Thumbor server can access source images. You can have multiple Thumbor servers each with multiple upstreams all handling requests.
Other advantages:
- Thumbor supports webp output using the
formatfilter - Apply multiple filters on the go to a single image
- Apply a cache lifetime to generated thumbnails
- Use a variety of backends to store generated images (e.g Redis, Mongo, S3) or implement your own.
- Put a frontend cache in front of Thumbor image servers.
- Is compatible with Pagespeed
http(s)://*thumbor-server*/hmac/trim/AxB:CxD/fit-in/-Ex-F/HALIGN/VALIGN/smart/filters:FILTERNAME(ARGUMENT):FILTERNAME(ARGUMENT)/*image-uri*
Where:
- http(s) - there is no reason why you shouldn't be using https
- thumbor-server - your Thumbor server host name
- hmac - signature of the request, so your disks don't get filled up with thumbs!
- trim - removes surrounding space
- AxB:CxD means manually crop the image at left-top point AxB and right-bottom point CxD;
- fit-in means that the generated image should not be auto-cropped and otherwise just fit in an imaginary box specified by ExF;
- -Ex-F means resize the image to be ExF of width per height size. The minus signs mean flip horizontally and vertically;
- HALIGN is horizontal alignment of crop;
- VALIGN is vertical alignment of crop;
- smart means using smart detection of focal points;
- filters can be applied sequentially to the image before returning;
- image-uri is the public URI for the image you want resized.
Best read the docs: https://thumbor.readthedocs.io/
See Protected Assets
The following standard image manipulation methods are provided for use in templates:
- ScaleWidth
- ScaleHeight
- Fill
- Pad
- Fit
- ResizedImage
- CMSThumbnail, AssetLibraryThumbnail, AssetLibraryPreview, StripThumbnail
Note that ResizedImage in this module preserves aspect ratio.
The module also provides some extra image manipulation methods in templates:
- FlipVertical - flip an original image vertically e.g
$Image.FlipVertical - FlipHorizontal - flip an original image horizontally e.g
$Image.FlipHorizontal - ScaleWidthFlipVertical - scale the image by width and flip it vertically e.g
$Image.ScaleWidthFlipVertical(360) - ScaleWidthFlipHorizontal - scale the image by width and flip it horizontally e.g
$Image.ScaleWidthFlipHorizontal(360) - ScaleHeightFlipVertical - scale the image by height and flip it vertically e.g
$Image.ScaleHeightFlipVertical(360) - ScaleHeightFlipHorizontal - scale the image by height and flip it horizontally e.g
$Image.ScaleHeightFlipHorizontal(360) - ManualCropFromCorners - manually crop and image from its corners e.g
$Image.ManualCropFromCorners(left px, top px, right px, bottom px) - Focal - crop an image around a Focal point e.g
$Image.Focal(left px, top px, right px, bottom px) - CroppedFocus - crop an image on a focal point based on stored crop data e.g
$Image.CroppedFocus - ManualCrop - crop the image to the exact dimensions returned from the cropping tool
Filters are provided via the Filter method and can be chained, for example the following template code:
$Image.Filter('brightness', 20).Filter('saturation', 3).Filter('sharpen', 8).ScaleWidth(360)
... will increase the brightness by 20%, increase saturation by 3%, sharpen with an amount of 8, then scale the image to 360px width. Images are not generated until the URL is requested by the web browser/client.
Filters are extremely powerful, the full list is available here. To use a filter in a template, use the parameters in the same order as described on the relevant Thumbor filter page.
For Sharpen, adding $Image.Filter('sharpen', 7, 1, true) to your template will display a sharpened version of the image with a sharpen_amount=7, sharpen_radius=1 and sharpening of the luminance channel only turned on.
When you want to manipulate the same image mutiple times in a template, you will need to reset filters on the image:
Compare:
$TestImage.Restart().Pad(500,300, 'fc0')
$TestImage.Restart().Align('left','top').Fill(160,160)
With:
$TestImage.Pad(500,300, 'fc0')
// this version will retain the Pad filter
$TestImage.Align('left','top').Fill(160,160)
Some filters require others to return the relevant image URL.
Return the current filter instance by calling Original in the template. This is only required for specific filter actions that do not return the Thumbor image URL.
// This will return the original image
$TestImage.ManualCrop
// This will return a Thumbor URL - manually cropped image to 600px width
$TestImage.ManualCrop.ScaleWidth(600)
// This will return the manually cropped Thumbor image URL
$TestImage.ManualCrop.Original
Check out the module docs here
The module ships with the configuration to handle image manipulation via Thumbor turned off. This allows you to switch back to the default Silverstripe image handling by removing project configuration.
If you view the module Yaml config, a number of configuration options are commented out, use these in your own project configuration. To use the module, create the configuration in your own project Yaml, based on the module configuration:
The below example config shows a basic setup. You will need to have a running Thumbor server before enabling the configuration.
---
Name: local_thumbor_config
After:
- '#thumbor_config'
---
# Example config for creating images
Codem\Thumbor\Config:
# from /etc/thumbor/thumbor.conf (MY_SECURE_KEY is the default, you shouldn't use this)
thumbor_generation_key: 'xxxxxx'
# for signing tokens for protected images, make it complex
signing_key: 'xxx'
salt: 'a salt'
use_https : false
# protected image expiry time (s)
expiry_time: 2
# if serving off a directory
backend_path : ''
# list all backends you have configured here, as many as you want, the module will pick one at random
backends:
- 'img1.cdn.example.com'
- 'img2.cdn.example.com'
- 'img3.cdn.example.com'
protected_backends:
- 'protected.example.com'
---
Name: local_thumbor_injection
After:
- '#thumbor_injection'
---
SilverStripe\Core\Injector\Injector:
SilverStripe\Assets\Image:
class: 'Codem\Thumbor\Image'
SilverStripe\Assets\Image_Backend:
class: Codem\Thumbor\ThumbyllaImageBackend
SilverStripe\AssetAdmin\Model\ThumbnailGenerator.graphql:
class: Codem\Thumbor\ThumbnailGenerator
SilverStripe\AssetAdmin\Model\ThumbnailGenerator.assetadmin:
class: Codem\Thumbor\ThumbnailGenerator
SilverStripe\Assets\Storage\AssetStore:
class: Codem\Thumbor\ThumbyllaAssetStore
---
Name: local_thumbor_mapping_config
After:
- '#thumbor_mapping_config'
---
# reset image handling classes
SilverStripe\Assets\File:
class_for_file_extension:
'jpg': 'Codem\Thumbor\Image'
'jpeg': 'Codem\Thumbor\Image'
'gif': 'Codem\Thumbor\Image'
'png': 'Codem\Thumbor\Image'
'webp': 'Codem\Thumbor\Image'
Documentation is updated from time-to-time
Please use the Github Issue Tracker to ask questions/report bugs.
This module makes use of cropperjs and react-cropper for image cropping and focal point handling.
All required assets are in client/dist/js|styles. If you want to build your own you will need Node and Yarn, then:
$ cd vendor\codem\thumbylla
$ yarn install
You can then run yarn run build or yarn run watch, for instance.
See LICENCE