README

Open Graph Images Generator

Create Open Graph images (og:image, twitter:image, vk:image) for each (or some) site pages.

Use page title to create an eye-catching page preview when users share the link on social networks or instant messengers. Learn more about Open Graph.

Features:

Image generation with your text and site name
Fully customizable (see configuration)
Small image size (15-50 Kb) with high resolution and quality (check it)
Aspect ratios presets for popular social networks

▶ See examples

Requirements

PHP 7.4 - 8.3
The Imagick PHP extension

Installation

You can install the package via composer:

composer require abordage/og-images

💡 Using Laravel? Check out abordage/laravel-og-images

Quick start

use Abordage\OpenGraphImages\OpenGraphImages;

require __DIR__ . ' /vendor/autoload.php';

$config = ['app_name' => 'alice.wonderland'];
$text = 'The adventures first, explanations take such a dreadful time!';
$path = __DIR__ . '/your-name-for-image.png';

$openGraphImage = new OpenGraphImages($config);
$openGraphImage->make($text)->save($path);

Note
All images are encoded in PNG format as it provides the best ratio between size/quality. For the same reason, the package uses the Imagick driver - in tests, it showed an advantage in speed and final size of the generated images.

Usage

$openGraphImage = new OpenGraphImages($config);

// for <og:image>
$openGraphImage->make($text)->save($path);
// or
$openGraphImage->make($text, 'opengraph')->save($path);

// for <twitter:image>
$openGraphImage->make($text, 'twitter')->save($path);

// for <vk:image>
$openGraphImage->make($text, 'vk')->save($path);

// custom size
$openGraphImage->makeCustom($text, 600, 400)->save($path);

After generation, you need to somehow organize the relationship of images with a specific page (for example, attach to a model). If you already have a solution ready to accept an image and attach it to a specific page, you can get the image as a string instead of saving it:

$openGraphImage = new OpenGraphImages($config);
$imageBlob = $openGraphImage->make($text)->get();

If after generation you need to get sizes of the image, you can get it as follows:

$openGraphImage->make($text, 'twitter')->get();
$imageSizes = $openGraphImage->getImageSizes();
// return [
//    'width' => 1200,
//    'height' => 600
// ];

Configuration

$config = [
    /*
    |--------------------------------------------------------------------------
    | Background Color
    |--------------------------------------------------------------------------
    |
    | Supported: HEX, RGB or RGBA format
    |
    */
    'background_color' => '#474761',

    /*
    |--------------------------------------------------------------------------
    | Text Color
    |--------------------------------------------------------------------------
    |
    | Supported: HEX, RGB or RGBA format
    |
    */
    'text_color' => '#eee',

    /*
    |--------------------------------------------------------------------------
    | App Name
    |--------------------------------------------------------------------------
    |
    | Set null to disable
    |
    | Supported: string or null
    |
    */
    'app_name' => null,

    /*
    |--------------------------------------------------------------------------
    | App Name Text Color
    |--------------------------------------------------------------------------
    |
    | Supported: HEX, RGB or RGBA format
    |
    */
    'app_name_color' => '#eee',

    /*
    |--------------------------------------------------------------------------
    | App Name Decoration Color
    |--------------------------------------------------------------------------
    |
    | Supported: HEX, RGB or RGBA format
    |
    */
    'app_name_decoration_color' => '#fb3361',

    /*
    |--------------------------------------------------------------------------
    | Text Alignment
    |--------------------------------------------------------------------------
    |
    | Multiline text alignment
    |
    | Supported: "left", "center", "right"
    |
    */
    'text_alignment' => 'left',

    /*
    |--------------------------------------------------------------------------
    | Text Sticky
    |--------------------------------------------------------------------------
    |
    | Supported: "left", "center", "right"
    |
    */
    'text_sticky' => 'center',

    /*
    |--------------------------------------------------------------------------
    | App Name Position
    |--------------------------------------------------------------------------
    |
    | Supported: "top-left", "top-center", "top-right",
    |            "bottom-left", "bottom-center", "bottom-right"
    |
    */
    'app_name_position' => 'bottom-center',

    /*
    |--------------------------------------------------------------------------
    | App Name Decoration Style
    |--------------------------------------------------------------------------
    |
    | Set null to disable
    |
    | Supported: "line", "label", "rectangle", null
    |
    */
    'app_name_decoration_style' => 'line',

    /*
    |--------------------------------------------------------------------------
    | Font Size
    |--------------------------------------------------------------------------
    |
    */
    'font_size' => 55,

    /*
    |--------------------------------------------------------------------------
    | App Name Font Size
    |--------------------------------------------------------------------------
    |
    */
    'app_name_font_size' => 30,

    /*
    |--------------------------------------------------------------------------
    | Text Font
    |--------------------------------------------------------------------------
    |
    | If set null, will be used Preset Font (Roboto Regular)
    |
    | Supported: "absolute/path/to/your/font.ttf", null
    |
    */
    'font_path' => null,

    /*
    |--------------------------------------------------------------------------
    | App Name Font
    |--------------------------------------------------------------------------
    |
    | If set null, will be used Preset Font (Roboto Medium)
    |
    | Supported: "absolute/path/to/your/font.ttf", null
    |
    */
    'app_name_font_path' => null,
];

API Reference

Images aspect ratios

Roadmap

Add ability to use gradients and images for the background.

Testing

Run all tests

composer test:all

composer test:phpunit
composer test:phpstan
composer test:phpcs

or see https://github.com/abordage/og-images/actions/workflows/tests.yml

Feedback

Find a bug or have a feature request? Open an issue, or better yet, submit a pull request - contribution welcome!

Contributing

Please see CONTRIBUTING for details.

Credits

Pavel Bychko (abordage)
All Contributors

License

The MIT License (MIT). Please see License File for more information.

abordage / og-images

Maintainers

Details