Download the PHP package simonhamp/the-og without Composer

The OG

An OpenGraph image generator written purely in PHP, so you don't need to install another runtime somewhere or a whole browser instance just to create a dynamic PNG.

Sponsorship

The OG is completely free to use for personal or commercial use. If it's making your job easier, or you just want to make sure it keeps being supported and improved, I'd really appreciate your donations!

Donate now via GitHub Sponsors

If you're using The OG, I'd love to see your creations! Please send me a tweet/toot (@simonhamp, @[email protected]) with some links so I can see how you're using The OG in the wild.

Thank you 🙏

Sponsors

Laradir - Connecting the best Laravel Developers with the best Laravel Teams.
quantumweb - A bare-metal web agency. Less layers, better results.
RedGalaxy - A web application development studio based in Cambridgeshire, building solutions to help businesses improve efficiency and profitability.
Sevalla - Host and manage your applications, databases, and static sites in a single, intuitive platform.

Installation

Install via Composer:

Usage

Using The OG is really simple. Here's a basic example:

And here's the image that generates:

The Image class provides an elegant and fluent API for configuring the content, style and layout of your image, as well as helpers to render the image and save it to a file.

Checking your images

Want to see how your images will look when shared on social media? Check out SEOToolkit's Social Share preview

Storing images

Conveniently, you can use the save() method to store your image on the local filesystem:

If you prefer to store your image somewhere other than the local filesystem (e.g. storing it on Amazon S3) you can use the toString() method.

toString() will return the rendered image as a binary string:

This will send the raw binary data directly to the external service without needing to write the image to a file on the local disk first.

Image formats

By default, The OG encodes images in PNG format.

If you wish to use a different format, however, you can! Simply pass an instance of the relevant intervention/image encoder to the save() or toString() methods:

Colors

Throughout The OG, colors can be expressed as hex codes, rgba, or HTML named colors.

Backgrounds

The OG comes with a number of built-in background patterns that you can use to add some texture to your image. You can find all of these defined in the Background enum.

Backgrounds can be set to Repeat or Cover and have opacity too:

It also supports custom background images from local or remote sources. See the Custom Background Images section below.

Borders

Borders provide a subtle variation of color and texture to your image by framing one, or multiple edges of the image with a single band of color—usually the theme's accentColor.

Borders are usually defined as part of the theme, but you can override the border position, color and size on the image itself:

The available border positions are:

• BorderPosition::All - All 4 edges will be bordered
• BorderPosition::Bottom - The bottom edge will be bordered
• BorderPosition::Left - The left edge will be bordered
• BorderPosition::Right - The right edge will be bordered
• BorderPosition::None - No edges will be bordered
• BorderPosition::Top - The top edge will be bordered
• BorderPosition::X - Combines BorderPosition::Top and BorderPosition::Bottom
• BorderPosition::Y - Combines BorderPosition::Left and BorderPosition::Right

Removing default borders

You can remove the default border from the image by chaining the border() method with the position argument set to BorderPosition::None:

Themes

Themes set the colors, fonts, and styles for your image. There are currently 2 themes available: Light and Dark.

The default theme is Light.

You can set the theme on your image at any point before it's rendered:

Creating themes

Themes are simple classes that implement the Theme interface.

However, you can create your own theme most easily by simply instantiating the Theme class:

Fonts

Currently, there are 2 fonts available (each with 4 variants):

• Inter
• RobotoSlab

If you think a particular font will make sense added to the core of this package, please consider contributing and open a Pull Request.

Custom fonts

You can load custom fonts by creating a class that implements the Font interface:

Then you can load this font when defining your theme:

Custom background images

If the built-in background patterns don't tickle your fancy, you can load your own simply by instantiating the Background class:

Then you can pass the background to your custom theme, or directly to your image:

If you want more customization of the background, you may create your own background classes that implement the Background interface.

Overriding theme settings

You can override some theme settings, such as the accent color, background and background color, without having to create a whole new theme.

Layouts

While themes govern the colors and styles used within your images, layouts govern the size of your images and the size and position of the image's elements (text blocks, other images etc.), called features.

Different layouts provide different features.

There are currently 3 layouts:

• Standard
• GitHubBasic
• TwoUp

The default layout is Standard.

More layouts are coming.

Creating layouts

Layouts are simple classes with some basic settings and features() method to define all of your image's features.

Each layout class must implement the Layout interface

Take a look at the Standard layout, or any of the other built-in layouts, as an example.

In it, you'll see the basic settings for the layout, such as the dimensions of the canvas, the border size and location, and any padding.

All sizes are in pixels.

Features

Features are the individual elements that make up your image, such as the Title, Description, URL etc.

All layouts support a background (which is always rendered first) and a border (which is always rendered last), so you do not normally need to define these as distinct features.

Beyond that, the features of the image are entirely defined by the Layout. The order in which they are defined determines their rendering order and, therefore, their layering.

Available built-in features:

• TextBox Allows you to render a constrained block of text. The size of the box serves to constrain the text; the final size of the box is determined by the length, font, size, and line height of the rendered text.
• PictureBox Allows you to render an image.

See the built-in layouts for examples of how to use these features and add them to a layout.

Positioning features

Features can be positioned absolutely anywhere on the canvas or relatively to another feature on the canvas.

To use relative positioning, it's helpful to give your target feature a unique name, which is used when other features need to reference its final rendered position.

See the built-in layouts for examples of how to position features.

Creating features

All features must implement the Box interface.

The key method of any feature is the render() method, which is responsible for rendering the feature onto the image. This method receives an instance of the underlying Intervention\Image\Image class, allowing you to use Intervention's own modifiers directly, e.g.:

You should, however, extend the Box class as this provides a number of useful conveniences, especially if you want to use relative positioning.

Testing

The OG uses PHPUnit with snapshot testing.

To run the integration tests, you need to install all Composer dependencies:

You will also need Node.js (version 20 or above) and to install the NPM dependencies:

Once done, you can execute the tests:

Contributing

I'd really appreciate and welcome any PRs to help improve this package!

Support

All support is handled via GitHub Issues.

License

The MIT License (MIT). Please see LICENSE for more details.