PHPackages                             rokka/kirby - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Image & Media](/categories/media)
4. /
5. rokka/kirby

ActiveKirby-plugin[Image & Media](/categories/media)

rokka/kirby
===========

Rokka plugin for Kirby CMS

0.5.2(2y ago)167012[1 PRs](https://github.com/rokka-io/rokka-kirby-plugin/pulls)MITPHPCI passing

Since Jan 8Pushed 1mo ago2 watchersCompare

[ Source](https://github.com/rokka-io/rokka-kirby-plugin)[ Packagist](https://packagist.org/packages/rokka/kirby)[ Docs](https://github.com/rokka-io/rokka-kirby-plugin)[ RSS](/packages/rokka-kirby/feed)WikiDiscussions master Synced today

READMEChangelog (10)Dependencies (2)Versions (13)Used By (0)

Kirby Rokka
===========

[](#kirby-rokka)

[rokka](https://rokka.io) is digital image processing done right. Store, render and deliver images. Easy and blazingly fast. This plugin automatically uploads your pictures to rokka and delivers them in the right format, as light and as fast as possible. And you only pay what you use, no upfront and fixed costs.

Free account plans are available. Just install the plugin, register and use it.

WARNING
-------

[](#warning)

This is still beta software. We use this for our [Liip](https://liip.ch/) company webpage, so it's somehow battle tested. But there's still room for improvements and some behind the scene code will change, the kirby API will stay stable, hopefully. And input is always welcome.

Requirements
------------

[](#requirements)

- [PHP 7.1](https://php.net)
- [**Kirby**](https://getkirby.com/) 3.6+
- [Rokka API key](https://rokka.io/en/signup/) (free plan available).
- [Rokka PHP Client](https://github.com/rokka-io/rokka-client-php) 1.1+. Installed via composer, see below.

Installation
------------

[](#installation)

### Composer install

[](#composer-install)

The recommended way

```
composer require rokka/kirby

```

### Git Submodule

[](#git-submodule)

```
git submodule add https://github.com/rokka-io/rokka-kirby-plugin.git site/plugins/rokka
composer require rokka/client

```

### Copy and Paste

[](#copy-and-paste)

1. [Download](https://github.com/rokka-io/rokka-kirby-plugin/archive/master.zip) the contents of this repository as ZIP-file.
2. Rename the extracted folder to `rokka` and copy it into the `site/plugins/` directory in your Kirby project.
3. `composer require rokka/client`

Usage
-----

[](#usage)

In your `site/config.php` activate the plugin and set the [ROKKA API key](https://rokka.io/en/signup/) .

```
c::set('rokka.kirby.enabled', true);
c::set('rokka.kirby.organization', 'YOUR_ORG_NAME_HERE');
c::set('rokka.kirby.apikey', 'YOUR_API_KEY_HERE');
```

The following is also recommended for shorter, nicer image URLS (see below in "Defining Stacks"):

```
c::set('rokka.kirby.stacks', [
    'noop' => 'kirby_noop',
    'resize' => 'kirby_resize',
    'crop' => 'kirby_crop'
    'raw' => 'kirby_raw',
    'kirbytext' => 'kirby_text', // default stack for kirbytext image includes
    'resize-800x10000' => 'kirby_text' //images in kirbytext will have a width of 800px
]);

```

After having added that, you have to call `https://yourkirbysite.com/_rokka/create-stacks` (and be logged in) to create the actual stacks on the rokka server.

The plugin adds a `$myFile->rokkaCropUrl($width, $height, $format = "jpg")`, ` $myFile->rokkaResizeUrl($width, $height, $format = "jpg")` and a `$myFile->rokkaOriginalSizeUrl($format="jpg")` function to [$file objects](https://getkirby.com/docs/cheatsheet#file).

You can use them like the following in your templates:

```
// get any image/file object
$myFile = $page->file('image.jpg');

// get url (on your webserver) for optimized thumb
$url = $myFile->rokkaCropUrl(500,500);
```

There's also `$myFile->rokka($stackname, $extension)` for returning an html img tag with using a stack and `$myFile->rokkaGetHash()` for getting the rokka hash of an image.

Defining stacks
---------------

[](#defining-stacks)

Rokka has a concept of [stacks](https://rokka.io/documentation/references/stacks.html), which allow to have nicer URLs.

You can configure some stacks with the `rokka.kirby.stacks` configure option. If you for example use certain sizes a lot, you should use a stack. For example, if you do `$myFile->rokkaCropUrl(200,200)` and `$myFile->rokkaResizeUrl(300,300)`, then define a stack with

```
c::set('rokka.kirby.stacks', [
    `crop-200x200' => 'kirby_thumbnail',
    `resize-300x300' => 'kirby_resized',
    'noop' => 'kirby_noop',
    'resize' => 'kirby_resize',
    'crop' => 'kirby_crop',
    'raw' => 'kirby_raw',
]);

```

The value of the array (in this example www\_thumbnail) is the used stack name. It can be an ascii text, you can use there whatever you want.

The `noop`, `crop` and `resize` and `raw` keys have a special meaning and you should define them like in the example above, but you can change the name of the actual stacks

After you defined your stacks, open the URL `https://yourkirbysite.com/_rokka/create-stacks`, after you logged in into the Panel. This will create your stacks on the Rokka server. A panel option for this will come one day. You only have to do this once, but whenever you change some of the stack definitions.

You can also set stack options for those stacks with eg.

```
c::set('rokka.kirby.stacks.options', [
    'resize-300x300' => ['options' => ['webp.quality' => 80]],
    'crop-200x200' => ['options' => ['jpg.quality' => 85]],
    'resize-800x10000' => [
        'operations' => ['resize' => ['options' => ['upscale' => false]]], // don't upscale picture, if they're smaller than the width
        'options' => ['webp.quality' => 80]
    ],
]);

```

And if you want different settings for retina screens you can add an 'options-retina' key

```
c::set('rokka.kirby.stacks.options', [
    'resize-300x300' => [
        'options' => ['webp.quality' => 80],
        'options-retina' => ['webp.quality' => 60]
    ],
]);

```

All available Stack options can be found on the [rokka documentation](https://rokka.io/documentation/references/stacks.html).

Retina images
-------------

[](#retina-images)

To be more documented.

Get html attribute snippets with `Rokka::getSrcAttributes($url)``Rokka::getBackgroundImageStyle($url)`for `srcset` enabled tags with retina resolutions.

### kirbytext

[](#kirbytext)

This plugin overwrites the kirbytext `image` tag and serves pictures from rokka if that is used.

Disclaimer
----------

[](#disclaimer)

This plugin is provided "as is" with no guarantee. Use it at your own risk and always test it yourself before using it in a production environment. If you find any issues, please [create a new issue](https://github.com/rokka/kirby-rokka/issues/new).

License
-------

[](#license)

[MIT](https://opensource.org/licenses/MIT)

###  Health Score

40

—

FairBetter than 88% of packages

Maintenance60

Regular maintenance activity

Popularity24

Limited adoption so far

Community15

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 89.6% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~192 days

Recently: every ~66 days

Total

9

Last Release

776d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/803a02308898d7176ad6601cc9f1bc9b057a725d5b35f6c0c54995b02a97a977?d=identicon)[rokka](/maintainers/rokka)

---

Top Contributors

[![chregu](https://avatars.githubusercontent.com/u/47106?v=4)](https://github.com/chregu "chregu (60 commits)")[![LeBenLeBen](https://avatars.githubusercontent.com/u/793344?v=4)](https://github.com/LeBenLeBen "LeBenLeBen (3 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)")[![dulnan](https://avatars.githubusercontent.com/u/4155003?v=4)](https://github.com/dulnan "dulnan (1 commits)")[![mweibel](https://avatars.githubusercontent.com/u/307427?v=4)](https://github.com/mweibel "mweibel (1 commits)")[![stof](https://avatars.githubusercontent.com/u/439401?v=4)](https://github.com/stof "stof (1 commits)")

---

Tags

kirbyrokkaimagerokkarokka.ioimagemanipulationkirby3kirby3-pluginkirby3-cms

### Embed Badge

![Health badge](/badges/rokka-kirby/health.svg)

```
[![Health](https://phpackages.com/badges/rokka-kirby/health.svg)](https://phpackages.com/packages/rokka-kirby)
```

###  Alternatives

[fabianmichael/kirby-meta

Your all-in-one powerhouse for any SEO and metadata needs imaginable.

6910.7k1](/packages/fabianmichael-kirby-meta)[steirico/kirby-plugin-image-crop-field

A image cropping field for kirby.

152.9k](/packages/steirico-kirby-plugin-image-crop-field)[schnti/cachebuster

A plugin for Kirby 3 CMS to add modification timestamps to css and js files

108.3k1](/packages/schnti-cachebuster)[bnomei/kirby3-php-cachedriver

PHP based Cache-Driver

112.6k](/packages/bnomei-kirby3-php-cachedriver)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)