Skip to content

Create eye-catching Open Graph images for each (or some) site pages

License

Notifications You must be signed in to change notification settings

abordage/og-images

Repository files navigation

Open Graph Images Generator

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

Open Graph Images Generator

Packagist Version GitHub Tests Status GitHub Code Style Status Packagist PHP Version Support License

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

Method Returns Added in Changed in
make(string $text, string $preset = 'opengraph') self 0.1.0 0.2.0
makeCustom(string $text, int $width, int $height) self 0.2.0 -
get() string 0.1.0 -
save(string $path) boolean 0.1.0 -
getImageSizes() array 0.3.0 -

Images aspect ratios

Preset Aspect ratios Docs
make(string $text) 1200 x 630 (1.91:1)
make(string $text, 'opengraph') 1200 x 630 (1.91:1)
make(string $text, 'facebook') 1200 x 630 (1.91:1) fb
make(string $text, 'twitter') 1200 x 600 (2:1) twitter
make(string $text, 'vk') 1200 x 536 (2.2:1) vk

Roadmap

Add ability to use gradients and images for the background.

Testing

Run all tests

composer test:all

or

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

License

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