https://github.com/moritzebeling/kirby-headless-image-transformations
Kirby plugin for headless image transformations
https://github.com/moritzebeling/kirby-headless-image-transformations
headless kirby plugin thumbnail transformations
Last synced: about 1 month ago
JSON representation
Kirby plugin for headless image transformations
- Host: GitHub
- URL: https://github.com/moritzebeling/kirby-headless-image-transformations
- Owner: moritzebeling
- Created: 2023-05-08T10:21:08.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2023-05-09T07:12:21.000Z (almost 3 years ago)
- Last Synced: 2025-09-27T22:21:42.388Z (5 months ago)
- Topics: headless, kirby, plugin, thumbnail, transformations
- Language: PHP
- Homepage:
- Size: 21.5 KB
- Stars: 10
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Kirby Headless Image Transformations
This plugin adds a new route to your Kirby CMS installation that allows you to transform images on the fly. This is useful when you want to let the frontend decide what image size to load:
**Schema**
```
https://your-kirby-website.com/thumbs/{image-id}.{ext}?{transformations}
```
**Original image**
```
https://your-kirby-website.com/thumbs/{image-id}.{ext}
```
**Thumbnail with 640px width and auto height**
```
https://your-kirby-website.com/thumbs/{image-id}.{ext}?width=640
```
**Cropped thumbnail with 640px width and height**
```
https://your-kirby-website.com/thumbs/{image-id}.{ext}?width=640&height=640&crop=true
```
## Installation
```bash
composer require moritzebeling/kirby-headless-image-transformations
```
Or download/clone this repo into `site/plugins` of your Kirby project.
## URL Query parameters
You can use all options offered by the [Kirby `thumb()` method](https://getkirby.com/docs/reference/objects/cms/file/thumb#options):
```js
let options = {
'autoOrient' => true, // bool
'crop' => false, // bool
'blur' => false, // bool
'grayscale' => false, // bool
'height' => null, // int
'quality' => 90, // int 0-100
'width' => null, // int
}
```
## Usage
This plugin can be helpful if you use Kirby as a Headless CMS and want to decide on your frontend which image size to load or to include in your srcset. You would only need the image id:
```php
$image_id = $file->id();
```
**Load single size:**
```js
function serializeObjectToQueryString( options = {} ){
const queryString = Object.keys(options).map(key => key + '=' + options[key]).join('&');
return queryString ? '?' + queryString : '';
}
const options = {
width: 640,
height: 640,
crop: true,
};
const host = 'https://your-kirby-website.com/thumbs';
const image_id = 'page-id/image-filename.jpg';
const thumb_url = `${host}/${image_id}${serializeObjectToQueryString( options )}`;
```
```html
```
**Load multiple widths for srcset:**
```js
// createQueryString, url_base, image_id same as in example above
const sizes = [240,480,960];
let src = `${host}/${image_id}${serializeObjectToQueryString({ width: sizes[0] })}`;
let srcset = sizes.map( size => {
const options = {
width: size
};
return `${host}/${image_id}${serializeObjectToQueryString( options )} ${size}w`;
}).join(', ');
```
```html
![]()
```
> Note that the html code above is just an example and wouln’t work in a vanilla setup, but require some type of templating engine, e.g. Svelte.
## Options and security considerations
Whenever a thumbnail is requested for the first time, Kirby will generate it and store it in the `media` folder. So whenever a thumb is requested for the first time, it will take a little longer.
This also means that people with bad intentions could exploit this to overwhelm your server and fill up your disk space. In order to prevent this, you should restrict the allowed transformations to only the ones you actually need.
**Default settings:**
```php
// site/config/config.php
return [
'moritzebeling.headless-image-transformations' => [
/*
These values can either be:
- false (not allowed, will be ignored and might fallback to Kirby's default settings)
- true (any value is allowed, do not use in production)
- array (list of allowed values)
*/
'allowed' => [
'autoOrient' => false,
'crop' => [true,false],
'blur' => false,
'grayscale' => false,
'height' => [40,80,160,240,360,480,640,720,960,1280,1440,1920,2560,3200],
'quality' => false,
'width' => [40,80,160,240,360,480,640,720,960,1280,1440,1920,2560,3200],
]
],
];
```
When sticking to the default options, it is only allowed to request thumbs with the specified widths and heights as well as cropping. If you need the other options, you should enable them via your `site/config/config.php` file.
You can also set some thumbnail option defaults for Kirby:
https://getkirby.com/docs/reference/system/options/thumbs
## Development
1. Install a fresh Kirby StarterKit
2. `cd site/plugins`
3. `git clone` this repo
Roadmap:
- [ ] Discuss if preset images sizes make sense
- [ ] Check if browser caching works as expected
## ☕️ Support
If you like this plugin, I would be glad if you would invite me for a coffee via [PayPal](http://more.moritzebeling.com/support).
If you have any ideas for further development or stumble upon any problems, please open an issue or PR. Thank you!
## Warranty
This plugin is work in progress and comes without any warranty. Use at your own risk.