README

Fast, 100% self-hosted, automatic Open Graph image generator (1200x630px) for Statamic 5 & 6 built natively in pure PHP via Intervention Image v3/v4.

💡 Why Local OG Images Generator?

Every post shared across social media networks (Twitter/X, LinkedIn, Facebook, Discord, Slack) requires an engaging Open Graph share image formatted to 1200x630px.

Current alternative solutions introduce major friction:

❌ Paid SaaS Services (Bannerbear, html2img): Recurring fees per image, external API latency, API key management.
❌ Puppeteer / Browsershot: Heavy RAM/CPU footprint, requires Node.js and Chromium binaries on your web server.
❌ Manual Figma Design: Time-consuming manual work for content editors.

Local OG Images Generator solves this completely: 100% self-hosted, local, and zero recurring costs. It renders high-end pixel-perfect social card images directly on your PHP server in milliseconds.

✨ Key Features

🎨 9 Premium Native Layout Templates:
- Minimalist Bold (minimalist): Dark/light contrast canvas, structured typography, colored accent bar.
- Editorial Split (split): 50/50 layout with cover image on one side and content card on the other.
- Card Overlay (card_overlay): Blurred image background (blur), soft overlay, and elevated surface card.
- Gradient Mesh (gradient_mesh): Organic vibrant gradients, luminous ambient light orbs, clean card layout.
- Modern Minimal (modern_minimal): Sleek typography, quote accent background, top accent border.
- Tech & Code Hero (code_hero): Developer IDE terminal layout with macOS traffic light buttons (#FF5F56, #FFBD2E, #27C93F).
- Glassmorphism Blur (glassmorphic_blur): Frosted glass panel overlay with background blur effects.
- Magazine Cover (magazine_cover): Editorial magazine cover layout with site title header & clean dividing rule.
- Cyber Neon (neon_dark): Cyberpunk double neon border glow with corner light accents.
🎨 Pure Layout Architecture: Templates adapt automatically to user-selected background and accent colors with WCAG contrast detection.
⚡ Live Control Panel Preview: Reactive Vue 3 Control Panel preview component (OgImagePreview.vue) with instant update on field changes.
🔤 Advanced Typography & Google Fonts: Local .ttf/.otf font resolution plus automatic Google Fonts downloader.
📐 Parametric Font Scaling: Adjust text size scale dynamically (0.75x, 1.0x, 1.25x, 1.5x, 2.0x).
👁️ Site Name & Date Toggles: Enable/disable site name and publication date globally or per collection.
🔌 SEO Integration: Direct write mode into SEO plugin fields (e.g. SEO Pro og_image) or standalone Antlers tags.
🏷️ Complete Antlers Tags:
- {{ local_og_image }} or {{ local_og_image:url }}: Returns the public OG image URL.
- {{ local_og_image:meta }}: Renders full Open Graph & Twitter Cards <meta> tags (og:image, og:image:width, og:image:height, twitter:card, twitter:image).
💻 CLI Command (Artisan / Please): Bulk image generation for entries.
🧪 Full Test Suite: PHPUnit integration tests via Orchestra Testbench.

🛠️ System Requirements

PHP: ^8.2
Statamic CMS: ^5.0 || ^6.0
PHP Extensions: ext-gd or ext-imagick

🚀 Installation

1. Install via Composer

Add the package to your Statamic project:

composer require michaelravedoni/statamic-local-og-images

2. Publish Configuration & Assets

Publish all addon assets and configuration with a single command:

php artisan vendor:publish --provider="MichaelRavedoni\StatamicLocalOgImages\ServiceProvider"

Or publish items selectively using tags:

# Publish configuration file (config/local-og-images.php)
php artisan vendor:publish --tag="local-og-images-config"

# Publish Control Panel JS/CSS assets
php artisan vendor:publish --tag="local-og-images-assets"

# Or publish all Statamic addon assets natively
php artisan statamic:assets:publish

⚙️ Configuration

The config/local-og-images.php file defines standard defaults for the addon:

return [
    // Graphics driver ('gd' or 'imagick')
    'driver' => env('OG_IMAGE_DRIVER', 'gd'),

    // Integration mode ('seo_field' or 'standalone')
    'integration_mode' => 'seo_field',

    // Target SEO field handle (e.g. 'og_image' for SEO Pro)
    'target_field' => 'og_image',

    // Storage mode ('public' disk or 'assets' Statamic container)
    'storage_disk' => 'public',
    'asset_container' => 'assets',
    'storage_path' => 'og-images',

    // Default template handle
    'default_template' => 'minimalist',

    // Typography (Google Fonts or local .ttf/.otf paths)
    'fonts' => [
        'title' => 'Outfit',
        'body' => 'Inter',
    ],

    // Default color palette
    'colors' => [
        'background' => '#0F172A',
        'accent' => '#38BDF8',
        'title' => '#F8FAFC',
        'excerpt' => '#94A3B8',
    ],

    // Display toggles
    'show_site_name' => true,
    'show_date' => true,

    // Per-collection mapping & rules
    'collections' => [
        'blog' => [
            'enabled' => true,
            'template' => 'split',
            'show_site_name' => true,
            'show_date' => true,
            'mapping' => [
                'title' => 'title',
                'excerpt' => 'excerpt',
                'featured_image' => 'hero_image',
                'author' => 'author',
            ],
        ],
    ],
];

📖 Usage

A. Statamic Control Panel (CP)

Access settings via Tools > OG Images or at /cp/addons/statamic-local-og-images/settings.

For enabled collections, an OG Images section is injected into entry blueprints with the live preview and custom image override field (og_image_override).

B. Antlers Templates

Place these tags inside your template <head> section:

{{# Render all Open Graph & Twitter Cards meta tags #}}
{{ local_og_image:meta }}

{{# Or fetch the image URL directly #}}
<meta property="og:image" content="{{ local_og_image:url }}" />

C. CLI Command

# Generate missing OG images
php please og-images:generate

# Filter by specific collection
php please og-images:generate --collection=blog

# Force full regeneration
php please og-images:generate --force

🎨 Creating Custom Templates

You can create object-oriented custom PHP templates by extending AbstractTemplate:

1. Create Template Class

Create a PHP file (e.g., app/OgTemplates/BrandCustomTemplate.php):

namespace App\OgTemplates;

use Intervention\Image\Image;
use MichaelRavedoni\StatamicLocalOgImages\Templates\AbstractTemplate;

class BrandCustomTemplate extends AbstractTemplate
{
    public function getName(): string
    {
        return 'Brand Custom Layout';
    }

    public function render(array $data, array $config = []): Image
    {
        $manager = $this->createImageManager($config);
        $colors = $this->getResolvedColors($config, '#0F172A');
        $canvas = $this->createCanvas($manager, $colors['bg']);

        // Draw top brand bar
        $canvas->drawRectangle(0, 0, function ($rectangle) use ($colors) {
            $rectangle->size(1200, 10);
            $rectangle->background($colors['accent']);
        });

        // Wrap & draw title
        $titleFont = $this->fontResolver->resolve('Outfit');
        $lines = $this->textWrapper->wrap($data['title'], 44, $titleFont, 1000, 3);
        $this->drawTextBlock($canvas, $lines, 80, 120, 44, $titleFont, $colors['title']);

        return $canvas;
    }
}

2. Register Template

In your app/Providers/AppServiceProvider.php:

use MichaelRavedoni\StatamicLocalOgImages\Services\ImageGenerator;
use App\OgTemplates\BrandCustomTemplate;

public function boot(): void
{
    app(ImageGenerator::class)->registerTemplate('brand_custom', BrandCustomTemplate::class);
}

Once registered, 'brand_custom' appears in your settings dropdown and configuration options.

🔧 Local Addon Development

To develop and test this addon locally inside your Statamic application without publishing to Packagist:

1. Register Local Path Repository

In your Statamic project's composer.json, add the relative or absolute path to the local addon folder under repositories:

"repositories": [
    {
        "type": "path",
        "url": "../statamic-local-og-images"
    }
]

2. Configure Minimum Stability & Require Package

Set "minimum-stability": "dev", "prefer-stable": true, and require the package using the * or @dev wildcard version:

{
    "minimum-stability": "dev",
    "prefer-stable": true,
    "require": {
        "michaelravedoni/statamic-local-og-images": "*"
    }
}

3. Install Symlinked Package

Run composer update to symlink the package into your project:

composer update michaelravedoni/statamic-local-og-images

Composer will create a symlink to your local addon directory, allowing instant live testing of all code changes!

🧪 Running Tests

Run unit tests via PHPUnit:

composer test

📄 License

This project is open-sourced software licensed under the MIT license. Created by Michael Ravedoni.

michaelravedoni / statamic-local-og-images

Maintainers

Package info

Statistics

Security