medienbaecker / kirby-og-image

1.0.0 2026-11-06 15:23 UTC

Requires

• php: ^8.2
• ext-gd: *
• getkirby/cms: ^5.0 || ^6.0@beta
• getkirby/composer-installer: ^1.2
• vanderlee/syllable: ^1.9

Requires (Dev)

• phpunit/phpunit: ^11

MIT

• Thomas Günther

Published on Packagist.org on 2026-11-06 15:31 UTC

README

Social card images (1200 × 630) from page data, drawn with GD. An image in the page's og field wins.

Requires Kirby 5 or 6, PHP 8.2 and GD with FreeType.

composer require medienbaecker/kirby-og-image

<?php snippet('og-image') ?>

The snippet goes in <head> and outputs og:image with its size and alt text. For your own tags, use $page->ogImage() and $page->ogImageAlt().

og:
  type: files
  multiple: false

Designs

// site/config/config.php
'medienbaecker.og-image' => [
	'color'        => '#1d3b2a',
	'textColor'    => '#ffffff',
	'logo'         => 'assets/images/logo.png',
	'logoNegative' => 'assets/images/logo-white.png',
	'logoShade'    => true,
	'language'     => 'de',
	'cards'        => [
		'default' => fn ($card, $page) => $card->basic($page->cover()->toFile(), title: $page->title()->value()),
		'recipe'  => fn ($card, $page) => $card->basic($page->cover()->toFile(), [$page->time() . ' min']),
	],
],

Logos can be PNG, JPG, GIF or WebP. language sets hyphenation and t() on single-language sites.

Bigger designs go in the page model:

use Medienbaecker\OgImage\Card;

public function ogCard(): Card
{
	return (new Card($this))
		->image($this->cover()->toFile())
		->text($this->title()->esc(), 56, 400, 1088, 174, size: 72, color: '#ffffff', valign: 'bottom');
}

Card methods: background, image, box, shade, logo, text, fits, chips, alt, basic. text() takes inline HTML, so escape plain values. Long text shrinks, hyphenates, then gets cut with “…”.

Caching

Cards render on first request to media/og-image/pages/<page id>/ and replace the page's older card. Outdated URLs redirect to the current card.

Development

composer install
composer test