OpenGraph Image Generator for October CMS
This plugin automatically generates OpenGraph images (og:image
) for your October CMS pages. When pages are shared on social media platforms, this ensures a visually appealing preview image is displayed, incorporating your site's branding and the page's title.
The plugin works by taking a background image and a font file you provide via the backend settings. It then dynamically overlays the page title (or a custom title you specify) onto the background using the chosen font, color, and text position. Generated images are cached for optimal performance.
Features
The plugin comes with a range of customisation for you to change and adapt.
- Choose text position from: horizontal: Left, Middle or Right and vertical positioning from: Top, Middle or Bottom.
- Change background image.
- Change font (ttf only)
- Clear the OpenGraph image cache.
- Translated into English, Russian, French and German.
- Really easy to use, drop in and use.
- You can pass custom variables to be used as the text displayed in the images, by default this.page.title is used.
Requirements
Before using the plugin, please ensure your server meets the following requirements:
- PHP >= 7.4 (Required by October CMS v3)
- PHP
imagick
Extension: The core image generation relies on the ImageMagick library and its PHP extension. This must be installed and enabled on your server. A warning will be displayed in the plugin settings if it's not detected. - Write Permissions: The web server needs write permissions for the
storage/app/media/
directory (and its subdirectories) as generated images are cached withinstorage/app/media/opengraph/generated/
.
Configuration
Navigate to the backend settings area: Settings > CMS > OpenGraph Settings.
Here you can configure the following:
- Background Image: Upload the base image you want text overlaid onto.
- Recommended size: 1200px wide by 630px high. Images will be resized to this dimension automatically.
- Font File: Upload the TrueType Font (
.ttf
) file to be used for the text. Only.ttf
format is supported. - Text Position: Select where the text should be placed on the image (e.g., Center Middle, Left Top, Right Bottom, etc.).
- Font Size (pixels): Enter the desired font size for the text. Defaults to
50
. - Font Color: Choose the color for the text using the color picker. Defaults to white (
#FFFFFF
). - Clear Generated Image Cache: Click this button to immediately delete all cached OpenGraph images. They will be regenerated the next time a page is visited.
(Note: If the imagick
PHP extension is not detected, a warning message will be displayed at the top of the settings page.)
Basic Usage (Component)
To enable OpenGraph image generation on your pages, add the OpenGraph Image component to your CMS layout or page. For site-wide use, adding it to your default layout is recommended.
- Go to the CMS > Layouts or CMS > Pages section.
- Open the layout or page you want to modify.
- Click the Components button in the sidebar.
- Find the OpenGraph Image component (under the "OpenGraph" group) and add it to the page/layout.
-
Place the component tag within the
<head>
section of your page/layout code:{% component 'openGraphImage' %}
This component doesn't render any visible HTML itself; it works in the background during page processing (onRender
) to generate the image URL and inject the necessary <meta property="og:image" ...>
tag into the page's head section. By default, it uses the current page's title (this.page.title
) as the text to overlay.
Advanced Usage (Custom Title)
If you don't want to use the default page title for a specific page's OpenGraph image, you can override it using the component's customTitle
property.
-
Example (in Twig):
{% component 'openGraphImage' customTitle="My Awesome Custom Title for Sharing" %}
-
Example (in Page/Layout Backend UI): When adding the component via the backend interface, you can directly set the
Custom Title
property field.
If the customTitle
property is set, its value will be used for the image text instead of this.page.title
. If left empty, it defaults back to the page title.
Caching
- Generated images are cached to improve performance and reduce server load.
- An image is only generated once for each unique combination of background image, font file, text content, text position, font size, and font color. Modification times of the source files are also considered.
- Subsequent requests for the same image configuration will serve the existing cached file.
- The cache is automatically invalidated if any relevant settings or source files are changed.
- Cached images are stored as JPEGs in
storage/app/media/opengraph/generated/
. You can manually clear this cache using the button in the settings area.
-
This plugin has not been reviewed yet.
-
1.0.1 |
Fixed composer.json file to match the required format of OctoberCMS plugins May 05, 2025 |
---|---|
1.0.0 |
Initialize plugin. Apr 28, 2025 |