PHPackages                             sunergos/og-pilot-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Image & Media](/categories/media)
4. /
5. sunergos/og-pilot-php

ActiveLibrary[Image & Media](/categories/media)

sunergos/og-pilot-php
=====================

PHP client for the OG Pilot Open Graph image generator with Laravel support.

v0.4.6(1mo ago)00MITPHPPHP ^8.1

Since Mar 17Pushed 1mo agoCompare

[ Source](https://github.com/sunergos-ro/og-pilot-php)[ Packagist](https://packagist.org/packages/sunergos/og-pilot-php)[ Docs](https://ogpilot.com)[ RSS](/packages/sunergos-og-pilot-php/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (3)Dependencies (4)Versions (4)Used By (0)

OG Pilot PHP
============

[](#og-pilot-php)

Important

An active [OG Pilot](https://ogpilot.com?ref=og-pilot-php) subscription is required to use this package.

A PHP client for generating OG Pilot Open Graph images via signed JWTs, with first-class Laravel support.

Requirements
------------

[](#requirements)

- PHP 8.1 or higher
- Composer

Installation
------------

[](#installation)

Install the package via Composer:

```
composer require sunergos/og-pilot-php
```

### Laravel

[](#laravel)

The package supports Laravel's auto-discovery, so the service provider and facade will be registered automatically.

Publish the configuration file:

```
php artisan vendor:publish --tag=og-pilot-config
```

Add your credentials to your `.env` file:

```
OG_PILOT_API_KEY=your-api-key
OG_PILOT_DOMAIN=your-domain.com
```

### Standalone PHP

[](#standalone-php)

For non-Laravel projects, configure the client directly:

```
use Sunergos\OgPilot\OgPilot;

OgPilot::setConfig([
    'api_key' => 'your-api-key',
    'domain' => 'your-domain.com',
    // 'strip_extensions' => true,
    // 'strip_query_parameters' => true,
]);
```

Or use environment variables `OG_PILOT_API_KEY` and `OG_PILOT_DOMAIN`.

Usage
-----

[](#usage)

### Laravel (using Facade)

[](#laravel-using-facade)

```
use Sunergos\OgPilot\Facades\OgPilot;

// Generate an image URL
$imageUrl = OgPilot::createImage([
    'template' => 'blog_post',
    'title' => 'How to Build Amazing OG Images',
    'description' => 'A complete guide to social media previews',
    'bg_color' => '#1a1a1a',
    'text_color' => '#ffffff',
    'author_name' => 'Jane Smith',
    'publish_date' => '2024-01-15',
]);

// With cache refresh (using iat)
$imageUrl = OgPilot::createImage([
    'template' => 'blog_post',
    'title' => 'My Blog Post',
], [
    'iat' => time(), // Refresh cache daily
]);

// Get JSON metadata instead
$data = OgPilot::createImage([
    'template' => 'page',
    'title' => 'Hello OG Pilot',
], [
    'json' => true,
]);
```

### Standalone PHP

[](#standalone-php-1)

```
use Sunergos\OgPilot\OgPilot;

// Configure once at application bootstrap
OgPilot::setConfig([
    'api_key' => 'your-api-key',
    'domain' => 'your-domain.com',
]);

// Generate an image URL
$imageUrl = OgPilot::createImage([
    'template' => 'blog_post',
    'title' => 'How to Build Amazing OG Images',
]);

// Or use the callback-style configuration
OgPilot::configure(function ($config) {
    $config->apiKey = 'your-api-key';
    $config->domain = 'your-domain.com';
});
```

### Using a Custom Client

[](#using-a-custom-client)

Create a dedicated client with custom configuration:

```
use Sunergos\OgPilot\OgPilot;
use Sunergos\OgPilot\Client;

// Using the factory method
$client = OgPilot::createClient([
    'api_key' => 'your-api-key',
    'domain' => 'your-domain.com',
    'connect_timeout' => 3.0,
    'timeout' => 8.0,
]);

$url = $client->createImage(['title' => 'Hello']);

// Or instantiate directly
$client = new Client([
    'api_key' => 'your-api-key',
    'domain' => 'your-domain.com',
]);
```

### Options

[](#options)

The `createImage` method accepts two arguments:

1. **params** (array): Image parameters sent to OG Pilot

    - `template`: Template name
    - `title`: Image title (required)
    - `description`: Image description
    - `path`: Request path for analytics (auto-resolved if not provided)
    - Any other template-specific parameters
2. **options** (array): Request options

    - `json`: Set to `true` to receive JSON metadata instead of a URL
    - `iat`: Timestamp for cache control (accepts Unix timestamp, DateTime, or milliseconds)
    - `headers`: Additional HTTP headers
    - `default`: Set to `true` to force path to "/" (useful for default OG images)

### HTTP behavior

[](#http-behavior)

- Requests are sent as `POST` to `https://ogpilot.com/api/v1/images` (or your configured `base_url`).
- Redirect responses are followed automatically.
- The signed JWT is still passed as the `token` query parameter.
- In URL mode (`json: false`), successful requests return the final redirected URL when available, otherwise the `Location` header, then the original signed request URL as a fallback.
- When `json` is `true`, the client sends `Accept: application/json`.
- If image creation fails (request/configuration/validation/etc.), `createImage` does not throw. It logs at error level and returns:
    - `null` in URL mode
    - `['image_url' => null]` in JSON mode

### Template helpers

[](#template-helpers)

`createImage` defaults to the `page` template when `template` is omitted. Supported templates: `page`, `blog_post`, `podcast`, `product`, `event`, `book`, `company`, `portfolio`, `github`.

Use these helpers to force a specific template:

- `createBlogPostImage(...)`
- `createPodcastImage(...)`
- `createProductImage(...)`
- `createEventImage(...)`
- `createBookImage(...)`
- `createCompanyImage(...)`
- `createPortfolioImage(...)`
- For `github`, use `createImage(['template' => 'github', ...])` (no dedicated helper yet).

These helpers are available on both `Sunergos\OgPilot\OgPilot` and `Sunergos\OgPilot\Client`.

```
$imageUrl = OgPilot::createBlogPostImage([
    'title' => 'How to Build Amazing OG Images',
    'author_name' => 'Jane Smith',
    'publish_date' => '2024-01-15',
]);
```

OG Image Examples
-----------------

[](#og-image-examples)

All sample payloads set explicit `bg_color`, `text_color`, and logo/avatar URLs to avoid default branding fallbacks.

For templates that support custom images, this set includes both `with_custom_image` and `without_custom_image` variants. (`github` currently has no custom image slot.)

Avatar-style fields (for example `author_avatar_url`) use DiceBear Avataaars, e.g. `https://api.dicebear.com/7.x/avataaars/svg?seed=JaneSmith`.

### Sample Gallery

[](#sample-gallery)

TemplateVariantPreview`page``with custom image`[![page_with_custom_image](https://camo.githubusercontent.com/a8981a40afb88000e26a41922e5ab89449a2acb2d194f1e58ee3f6378802b715/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f3166366f59343938493653694e667147446a7764484c4e70776d655532363474324f4c306b377459384d772f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f656f6f3576343564373636686632326a347232616c36306b74616c69)](https://camo.githubusercontent.com/a8981a40afb88000e26a41922e5ab89449a2acb2d194f1e58ee3f6378802b715/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f3166366f59343938493653694e667147446a7764484c4e70776d655532363474324f4c306b377459384d772f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f656f6f3576343564373636686632326a347232616c36306b74616c69)`page``without custom image`[![page_without_custom_image](https://camo.githubusercontent.com/a15c475233ac0003b6bf615cd131f0bc5c8b8e644e113ee6a6a327e5f7762bcd/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f394d5a6454635452794f6f527170544c6c6c5f5f457644696d6d676f6a5a4553665a576f6b447158655a4d2f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f77666139657332777576703662746a697269656b6b3533737770366e)](https://camo.githubusercontent.com/a15c475233ac0003b6bf615cd131f0bc5c8b8e644e113ee6a6a327e5f7762bcd/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f394d5a6454635452794f6f527170544c6c6c5f5f457644696d6d676f6a5a4553665a576f6b447158655a4d2f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f77666139657332777576703662746a697269656b6b3533737770366e)`blog_post``with custom image`[![blog_post_with_custom_image](https://camo.githubusercontent.com/7f8913840830b764db7274666c28e1c2560b0dac9b5fa0049c09cdfea76a9bd9/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f524242515a6e4272414b63566d466a4a673655744e71583850366e52525164474c726c4a4e5759696637492f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f6a6537706a3831366578756c39756d6879737a71706e6278656c6d64)](https://camo.githubusercontent.com/7f8913840830b764db7274666c28e1c2560b0dac9b5fa0049c09cdfea76a9bd9/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f524242515a6e4272414b63566d466a4a673655744e71583850366e52525164474c726c4a4e5759696637492f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f6a6537706a3831366578756c39756d6879737a71706e6278656c6d64)`blog_post``without custom image`[![blog_post_without_custom_image](https://camo.githubusercontent.com/08042cc7d9e27002846387ee318b02368636cd4adbfb5bfd523dc0bd71556190/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f79503142374f724c4f79394975394a44534e6b395665797333455343754353424d39696c327771313356342f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f3661656938667276756e366b76716f6a6f6f7231687161636b333179)](https://camo.githubusercontent.com/08042cc7d9e27002846387ee318b02368636cd4adbfb5bfd523dc0bd71556190/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f79503142374f724c4f79394975394a44534e6b395665797333455343754353424d39696c327771313356342f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f3661656938667276756e366b76716f6a6f6f7231687161636b333179)`podcast``with custom image`[![podcast_with_custom_image](https://camo.githubusercontent.com/e66e0945992d5e9214b55b94908294765b93078d8c42cf2a5130185fbc4d6244/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f727a4f4f743750574a34344f4577704b6e6e744d4c5a615076746c373644413379526c6a3642364e2d43632f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f666d6b65626c776572746e65757934703832666f65673572666c746c)](https://camo.githubusercontent.com/e66e0945992d5e9214b55b94908294765b93078d8c42cf2a5130185fbc4d6244/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f727a4f4f743750574a34344f4577704b6e6e744d4c5a615076746c373644413379526c6a3642364e2d43632f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f666d6b65626c776572746e65757934703832666f65673572666c746c)`podcast``without custom image`[![podcast_without_custom_image](https://camo.githubusercontent.com/f113e5e1081c251df8f173c776fa902fc49b81336ee463d4f7e0d41fdca0fd13/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f355557574647324a35624e52444f68446b4e39365a475f6730584939554c47444667516b7556546a4359512f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f7979686d6f376c616d6a316e393969326e366479747477756e676d71)](https://camo.githubusercontent.com/f113e5e1081c251df8f173c776fa902fc49b81336ee463d4f7e0d41fdca0fd13/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f355557574647324a35624e52444f68446b4e39365a475f6730584939554c47444667516b7556546a4359512f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f7979686d6f376c616d6a316e393969326e366479747477756e676d71)`product``with custom image`[![product_with_custom_image](https://camo.githubusercontent.com/f99311adfd8ec2d14121c8a9a7daeae7276b5d4c3c666f9e81a8c1335eab9500/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f6d7a6d48444d6a79415834566c704a616e4d54337a706d494a675375436c594935656f66684670534a4e512f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f386c73326c6567623331366c3976616b34306e75333838757a793274)](https://camo.githubusercontent.com/f99311adfd8ec2d14121c8a9a7daeae7276b5d4c3c666f9e81a8c1335eab9500/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f6d7a6d48444d6a79415834566c704a616e4d54337a706d494a675375436c594935656f66684670534a4e512f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f386c73326c6567623331366c3976616b34306e75333838757a793274)`product``without custom image`[![product_without_custom_image](https://camo.githubusercontent.com/4c665d77309265a30b1802411340efe3f43b5376928ff395204d75a35433593c/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f6b4b36643778553345575435574b43366a4b43773172684a446d7639627776526e32532d6e536856344e412f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f35326e73326c316c6c37686a686667307033776e3563397071747235)](https://camo.githubusercontent.com/4c665d77309265a30b1802411340efe3f43b5376928ff395204d75a35433593c/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f6b4b36643778553345575435574b43366a4b43773172684a446d7639627776526e32532d6e536856344e412f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f35326e73326c316c6c37686a686667307033776e3563397071747235)`event``with custom image`[![event_with_custom_image](https://camo.githubusercontent.com/154b66759a9060fb2112c620babcddae81f4053fa82b36e0f13c669701b992c3/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f41376e78486b597334784e346331506848324b5153576f4234414c774264705030485069417373395f37302f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f766a6b64663663783832647664786d686977747672766b6c39373664)](https://camo.githubusercontent.com/154b66759a9060fb2112c620babcddae81f4053fa82b36e0f13c669701b992c3/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f41376e78486b597334784e346331506848324b5153576f4234414c774264705030485069417373395f37302f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f766a6b64663663783832647664786d686977747672766b6c39373664)`event``without custom image`[![event_without_custom_image](https://camo.githubusercontent.com/be427e8cdc198b343275c7e8cc4260980be0f878c678895b436349c780ea3e4e/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f656c7066753238764a353758434778336e704b6843775871714a6e506f7177436d38416a35534c6b57734d2f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f767074653831386e76746567633630746139387137706d7739316338)](https://camo.githubusercontent.com/be427e8cdc198b343275c7e8cc4260980be0f878c678895b436349c780ea3e4e/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f656c7066753238764a353758434778336e704b6843775871714a6e506f7177436d38416a35534c6b57734d2f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f767074653831386e76746567633630746139387137706d7739316338)`book``with custom image`[![book_with_custom_image](https://camo.githubusercontent.com/f2411b095d975521a7fcc1284e8481cb75d6faa9a11754ef19e263fd4bace6ac/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f37706964536b76555f6c30527a593978424f4c536132782d6a445757767831344774762d4b4d4443474c772f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f63776e68623633316c73326f6c6b30797a6b756b6d7235646e663765)](https://camo.githubusercontent.com/f2411b095d975521a7fcc1284e8481cb75d6faa9a11754ef19e263fd4bace6ac/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f37706964536b76555f6c30527a593978424f4c536132782d6a445757767831344774762d4b4d4443474c772f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f63776e68623633316c73326f6c6b30797a6b756b6d7235646e663765)`book``without custom image`[![book_without_custom_image](https://camo.githubusercontent.com/3afffabfdd484cc9f3a49f422697db88c8e1afdf38eabde9a9243093b6966beb/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f46704d62424e3135534c67614b394645583037785863543564514957795a6b466448615a396935777833552f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f30727a6973666e32717377647a737a363431726c337332396e677539)](https://camo.githubusercontent.com/3afffabfdd484cc9f3a49f422697db88c8e1afdf38eabde9a9243093b6966beb/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f46704d62424e3135534c67614b394645583037785863543564514957795a6b466448615a396935777833552f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f30727a6973666e32717377647a737a363431726c337332396e677539)`portfolio``with custom image`[![portfolio_with_custom_image](https://camo.githubusercontent.com/fb40bbb1cd5581197208cc41d0ae8f1d7158d076654b751b97f20ffc8f0fcccb/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f6761756977324d4d634e4c4c53466e513037487133666c763453304c2d38396c6e6e6a554f4f30566759552f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f716f6b30346c6c713066663364326c6865727564776c687178736c6d)](https://camo.githubusercontent.com/fb40bbb1cd5581197208cc41d0ae8f1d7158d076654b751b97f20ffc8f0fcccb/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f6761756977324d4d634e4c4c53466e513037487133666c763453304c2d38396c6e6e6a554f4f30566759552f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f716f6b30346c6c713066663364326c6865727564776c687178736c6d)`portfolio``without custom image`[![portfolio_without_custom_image](https://camo.githubusercontent.com/66db53e1ad115084657f6871f8ffd9d93c92038426973dd1089717835d372ac3/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f6a56636b395344506c6569306761487134345f69744c6f567a6e3277494e724350335843545146335359732f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f6a786131733764746962616571616d68306673796d777a3775717278)](https://camo.githubusercontent.com/66db53e1ad115084657f6871f8ffd9d93c92038426973dd1089717835d372ac3/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f6a56636b395344506c6569306761487134345f69744c6f567a6e3277494e724350335843545146335359732f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f6a786131733764746962616571616d68306673796d777a3775717278)`company``with custom image`[![company_with_custom_image](https://camo.githubusercontent.com/1a53fd0e3804b68bf44db74764d5cdb2d0a69a3c371c2e9bf03b5fca070e005e/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f726a6937684e676f78524d314b4632476f66494f396771584a514e673543716c50576268624770523446412f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f32786c367a69337a676a6d3734697a723436656664757a686d627272)](https://camo.githubusercontent.com/1a53fd0e3804b68bf44db74764d5cdb2d0a69a3c371c2e9bf03b5fca070e005e/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f726a6937684e676f78524d314b4632476f66494f396771584a514e673543716c50576268624770523446412f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f32786c367a69337a676a6d3734697a723436656664757a686d627272)`company``without custom image`[![company_without_custom_image](https://camo.githubusercontent.com/ac9f416ab4df48d755fc2c13db78a78f7fb9cae96d9484088af5bf3e2aab55aa/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f5067476c39613678506d4730546e37714b6d5a5a55637a72763433634e4c787a79495373624847385f6f452f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f36676d6d366a67357238796132377233747232313565646664393732)](https://camo.githubusercontent.com/ac9f416ab4df48d755fc2c13db78a78f7fb9cae96d9484088af5bf3e2aab55aa/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f5067476c39613678506d4730546e37714b6d5a5a55637a72763433634e4c787a79495373624847385f6f452f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f36676d6d366a67357238796132377233747232313565646664393732)`github``default`[![github_activity](https://camo.githubusercontent.com/229875d6990f709651fcaa0d0a640e1424cc2ae0125ea4cd85c299ab2f19a155/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f3064786d38336454794e43673544715f475a46543453717352795457554f333164304851776a4971302d412f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f6a6c6877736b6a73783038783536617474616c6a7733636530703635)](https://camo.githubusercontent.com/229875d6990f709651fcaa0d0a640e1424cc2ae0125ea4cd85c299ab2f19a155/68747470733a2f2f696d672e6f6770696c6f742e636f6d2f3064786d38336454794e43673544715f475a46543453717352795457554f333164304851776a4971302d412f706c61696e2f73333a2f2f6f672d70696c6f742d646576656c6f706d656e742f6a6c6877736b6a73783038783536617474616c6a7733636530703635)### Parameters Used

[](#parameters-used)

Exact payloads for these samples```
[
  {
    "id": "page_with_custom_image",
    "template": "page",
    "variant": "with_custom_image",
    "params": {
      "title": "Acme Robotics Product Updates",
      "description": "See what shipped this week across the web app.",
      "logo_url": "https://www.google.com/s2/favicons?sz=128&domain_url=https%3A%2F%2Fwww.notion.so",
      "image_url": "https://images.unsplash.com/photo-1558655146-d09347e92766?w=1400&q=80",
      "bg_color": "#0B1220",
      "text_color": "#F8FAFC",
      "template": "page"
    },
    "image_url": "https://img.ogpilot.com/1f6oY498I6SiNfqGDjwdHLNpwmeU264t2OL0k7tY8Mw/plain/s3://og-pilot-development/eoo5v45d766hf22j4r2al60ktali"
  },
  {
    "id": "page_without_custom_image",
    "template": "page",
    "variant": "without_custom_image",
    "params": {
      "title": "Notion AI Workspace for Product Teams",
      "description": "Docs, specs, and roadmaps in one living workspace.",
      "logo_url": "https://www.google.com/s2/favicons?sz=128&domain_url=https%3A%2F%2Fwww.notion.so",
      "bg_color": "#111827",
      "text_color": "#E5E7EB",
      "template": "page"
    },
    "image_url": "https://img.ogpilot.com/9MZdTcTRyOoRqpTLll__EvDimmgojZESfZWokDqXeZM/plain/s3://og-pilot-development/wfa9es2wuvp6btjiriekk53swp6n"
  },
  {
    "id": "blog_post_with_custom_image",
    "template": "blog_post",
    "variant": "with_custom_image",
    "params": {
      "title": "How Stripe Reduced Checkout Abandonment by 18%",
      "logo_url": "https://www.google.com/s2/favicons?sz=128&domain_url=https%3A%2F%2Fstripe.com",
      "image_url": "https://images.unsplash.com/photo-1460925895917-afdab827c52f?w=1400&q=80",
      "author_name": "Maya Patel",
      "author_avatar_url": "https://api.dicebear.com/7.x/avataaars/svg?seed=MayaPatel",
      "publish_date": "2026-02-24",
      "bg_color": "#0F172A",
      "text_color": "#F8FAFC",
      "template": "blog_post"
    },
    "image_url": "https://img.ogpilot.com/RBBQZnBrAKcVmFjJg6UtNqX8P6nRRQdGLrlJNWYif7I/plain/s3://og-pilot-development/je7pj816exul9umhyszqpnbxelmd"
  },
  {
    "id": "blog_post_without_custom_image",
    "template": "blog_post",
    "variant": "without_custom_image",
    "params": {
      "title": "Inside Vercel's Edge Rendering Playbook",
      "logo_url": "https://www.google.com/s2/favicons?sz=128&domain_url=https%3A%2F%2Fvercel.com",
      "author_name": "Daniel Kim",
      "author_avatar_url": "https://api.dicebear.com/7.x/avataaars/svg?seed=DanielKim",
      "publish_date": "2026-02-18",
      "bg_color": "#111827",
      "text_color": "#E5E7EB",
      "template": "blog_post"
    },
    "image_url": "https://img.ogpilot.com/yP1B7OrLOy9Iu9JDSNk9Veys3ESCuCSBM9il2wq13V4/plain/s3://og-pilot-development/6aei8frvun6kvqojoor1hqack31y"
  },
  {
    "id": "podcast_with_custom_image",
    "template": "podcast",
    "variant": "with_custom_image",
    "params": {
      "title": "Indie Hackers Podcast: Pricing Experiments That Worked",
      "logo_url": "https://www.google.com/s2/favicons?sz=128&domain_url=https%3A%2F%2Fwww.spotify.com",
      "image_url": "https://images.unsplash.com/photo-1478737270239-2f02b77fc618?w=1400&q=80",
      "episode_date": "2026-02-21",
      "bg_color": "#18181B",
      "text_color": "#FAFAFA",
      "template": "podcast"
    },
    "image_url": "https://img.ogpilot.com/rzOOt7PWJ44OEwpKnntMLZaPvtl76DA3yRlj6B6N-Cc/plain/s3://og-pilot-development/fmkeblwertneuy4p82foeg5rfltl"
  },
  {
    "id": "podcast_without_custom_image",
    "template": "podcast",
    "variant": "without_custom_image",
    "params": {
      "title": "Shopify Masters: Building a 7-Figure DTC Brand",
      "logo_url": "https://www.google.com/s2/favicons?sz=128&domain_url=https%3A%2F%2Fwww.shopify.com",
      "episode_date": "2026-02-19",
      "bg_color": "#0B1120",
      "text_color": "#E2E8F0",
      "template": "podcast"
    },
    "image_url": "https://img.ogpilot.com/5UWWFG2J5bNRDOhDkN96ZG_g0XI9ULGDFgQkuVTjCYQ/plain/s3://og-pilot-development/yyhmo7lamj1n99i2n6dyttwungmq"
  },
  {
    "id": "product_with_custom_image",
    "template": "product",
    "variant": "with_custom_image",
    "params": {
      "title": "Allbirds Tree Dasher 3",
      "logo_url": "https://www.google.com/s2/favicons?sz=128&domain_url=https%3A%2F%2Fwww.allbirds.com",
      "image_url": "https://images.unsplash.com/photo-1542291026-7eec264c27ff?w=1400&q=80",
      "unique_selling_point": "Free shipping + 30-day returns",
      "bg_color": "#F8FAFC",
      "text_color": "#0F172A",
      "template": "product"
    },
    "image_url": "https://img.ogpilot.com/mzmHDMjyAX4VlpJanMT3zpmIJgSuClYI5eofhFpSJNQ/plain/s3://og-pilot-development/8ls2legb316l9vak40nu388uzy2t"
  },
  {
    "id": "product_without_custom_image",
    "template": "product",
    "variant": "without_custom_image",
    "params": {
      "title": "Bose QuietComfort Ultra",
      "logo_url": "https://www.google.com/s2/favicons?sz=128&domain_url=https%3A%2F%2Fwww.bose.com",
      "unique_selling_point": "Save $70 this weekend",
      "bg_color": "#111827",
      "text_color": "#F9FAFB",
      "template": "product"
    },
    "image_url": "https://img.ogpilot.com/kK6d7xU3EWT5WKC6jKCw1rhJDmv9bwvRn2S-nShV4NA/plain/s3://og-pilot-development/52ns2l1ll7hjhfg0p3wn5c9pqtr5"
  },
  {
    "id": "event_with_custom_image",
    "template": "event",
    "variant": "with_custom_image",
    "params": {
      "title": "Launch Week Berlin 2026",
      "logo_url": "https://www.google.com/s2/favicons?sz=128&domain_url=https%3A%2F%2Fwww.eventbrite.com",
      "image_url": "https://images.unsplash.com/photo-1540575467063-178a50c2df87?w=1400&q=80",
      "event_date": "2026-06-12/2026-06-14",
      "event_location": "Station Berlin",
      "bg_color": "#1E1B4B",
      "text_color": "#F5F3FF",
      "template": "event"
    },
    "image_url": "https://img.ogpilot.com/A7nxHkYs4xN4c1PhH2KQSWoB4ALwBdpP0HPiAss9_70/plain/s3://og-pilot-development/vjkdf6cx82dvdxmhiwtvrvkl976d"
  },
  {
    "id": "event_without_custom_image",
    "template": "event",
    "variant": "without_custom_image",
    "params": {
      "title": "RubyConf Chicago 2026",
      "logo_url": "https://www.google.com/s2/favicons?sz=128&domain_url=https%3A%2F%2Frubyconf.org",
      "event_date": "2026-11-17",
      "event_location": "Chicago, IL",
      "bg_color": "#312E81",
      "text_color": "#EEF2FF",
      "template": "event"
    },
    "image_url": "https://img.ogpilot.com/elpfu28vJ57XCGx3npKhCwXqqJnPoqwCm8Aj5SLkWsM/plain/s3://og-pilot-development/vpte818nvtegc60ta98q7pmw91c8"
  },
  {
    "id": "book_with_custom_image",
    "template": "book",
    "variant": "with_custom_image",
    "params": {
      "title": "Designing APIs for Humans",
      "description": "A practical handbook for product-minded engineers.",
      "logo_url": "https://www.google.com/s2/favicons?sz=128&domain_url=https%3A%2F%2Fwww.oreilly.com",
      "image_url": "https://images.unsplash.com/photo-1512820790803-83ca734da794?w=1400&q=80",
      "book_author": "Alex Turner",
      "book_series_number": "2",
      "book_genre": "Technology",
      "bg_color": "#172554",
      "text_color": "#EFF6FF",
      "template": "book"
    },
    "image_url": "https://img.ogpilot.com/7pidSkvU_l0RzY9xBOLSa2x-jDWWvx14Gtv-KMDCGLw/plain/s3://og-pilot-development/cwnhb631ls2olk0yzkukmr5dnf7e"
  },
  {
    "id": "book_without_custom_image",
    "template": "book",
    "variant": "without_custom_image",
    "params": {
      "title": "The Product Operating System",
      "description": "How modern teams ship with confidence.",
      "logo_url": "https://www.google.com/s2/favicons?sz=128&domain_url=https%3A%2F%2Fwww.penguinrandomhouse.com",
      "book_author": "Sofia Ramirez",
      "book_series_number": "1",
      "book_genre": "Business",
      "bg_color": "#1E293B",
      "text_color": "#F8FAFC",
      "template": "book"
    },
    "image_url": "https://img.ogpilot.com/FpMbBN15SLgaK9FEX07xXcT5dQIWyZkFdHaZ9i5wx3U/plain/s3://og-pilot-development/0rzisfn2qswdzsz641rl3s29ngu9"
  },
  {
    "id": "portfolio_with_custom_image",
    "template": "portfolio",
    "variant": "with_custom_image",
    "params": {
      "title": "Maya Chen • Product Designer",
      "description": "Fintech UX, design systems, and prototyping.",
      "logo_url": "https://api.dicebear.com/7.x/avataaars/svg?seed=MayaChen&size=64",
      "image_url": "https://images.unsplash.com/photo-1557672172-298e090bd0f1?w=1400&q=80",
      "bg_color": "#1F2937",
      "text_color": "#F9FAFB",
      "template": "portfolio"
    },
    "image_url": "https://img.ogpilot.com/gauiw2MMcNLLSFnQ07Hq3flv4S0L-89lnnjUOO0VgYU/plain/s3://og-pilot-development/qok04llq0ff3d2lherudwlhqxslm"
  },
  {
    "id": "portfolio_without_custom_image",
    "template": "portfolio",
    "variant": "without_custom_image",
    "params": {
      "title": "Arjun Rao • Frontend Engineer",
      "description": "React performance, accessibility, and DX.",
      "logo_url": "https://api.dicebear.com/7.x/avataaars/svg?seed=ArjunRao&size=64",
      "bg_color": "#0F172A",
      "text_color": "#E2E8F0",
      "template": "portfolio"
    },
    "image_url": "https://img.ogpilot.com/jVck9SDPlei0gaHq44_itLoVzn2wINrCP3XCTQF3SYs/plain/s3://og-pilot-development/jxa1s7dtibaeqamh0fsymwz7uqrx"
  },
  {
    "id": "company_with_custom_image",
    "template": "company",
    "variant": "with_custom_image",
    "params": {
      "title": "Notion",
      "description": "4 job openings",
      "logo_url": "https://www.google.com/s2/favicons?sz=128&domain_url=https%3A%2F%2Fwww.notion.so",
      "bg_color": "#111827",
      "text_color": "#F9FAFB",
      "template": "company"
    },
    "image_url": "https://img.ogpilot.com/rji7hNgoxRM1KF2GofIO9gqXJQNg5CqlPWbhbGpR4FA/plain/s3://og-pilot-development/2xl6zi3zgjm74izr46efduzhmbrr"
  },
  {
    "id": "company_without_custom_image",
    "template": "company",
    "variant": "without_custom_image",
    "params": {
      "title": "Linear",
      "description": "12 job openings",
      "company_logo_url": "https://www.google.com/s2/favicons?sz=256&domain_url=https%3A%2F%2Flinear.app",
      "bg_color": "#0B1220",
      "text_color": "#E5E7EB",
      "template": "company",
      "iss": "gitdigest.ai"
    },
    "image_url": "https://img.ogpilot.com/PgGl9a6xPmG0Tn7qKmZZUczrv43cNLxzyISsbHG8_oE/plain/s3://og-pilot-development/6gmm6jg5r8ya27r3tr215edfd972"
  },
  {
    "id": "github_activity",
    "template": "github",
    "variant": "default",
    "params": {
      "title": "rails/rails",
      "description": "Recent merged PRs, reviews, and commit activity.",
      "accent_color": "#22C55E",
      "bg_color": "#0B1220",
      "text_color": "#E5E7EB",
      "contributions": [
        {
          "date": "2025-10-28",
          "count": 6
        },
        {
          "date": "2025-11-01",
          "count": 3
        },
        {
          "date": "2025-11-05",
          "count": 9
        },
        {
          "date": "2025-11-08",
          "count": 12
        },
        {
          "date": "2025-11-12",
          "count": 7
        },
        {
          "date": "2025-11-16",
          "count": 11
        },
        {
          "date": "2025-11-20",
          "count": 5
        },
        {
          "date": "2025-11-24",
          "count": 14
        },
        {
          "date": "2025-11-28",
          "count": 8
        },
        {
          "date": "2025-12-02",
          "count": 4
        },
        {
          "date": "2025-12-06",
          "count": 10
        },
        {
          "date": "2025-12-10",
          "count": 15
        },
        {
          "date": "2025-12-14",
          "count": 6
        },
        {
          "date": "2025-12-18",
          "count": 9
        },
        {
          "date": "2025-12-22",
          "count": 13
        },
        {
          "date": "2025-12-26",
          "count": 4
        },
        {
          "date": "2025-12-30",
          "count": 7
        },
        {
          "date": "2026-01-03",
          "count": 11
        },
        {
          "date": "2026-01-07",
          "count": 16
        },
        {
          "date": "2026-01-11",
          "count": 12
        },
        {
          "date": "2026-01-15",
          "count": 6
        },
        {
          "date": "2026-01-19",
          "count": 8
        },
        {
          "date": "2026-01-23",
          "count": 14
        },
        {
          "date": "2026-01-27",
          "count": 9
        },
        {
          "date": "2026-01-31",
          "count": 5
        },
        {
          "date": "2026-02-04",
          "count": 13
        },
        {
          "date": "2026-02-08",
          "count": 17
        },
        {
          "date": "2026-02-12",
          "count": 10
        },
        {
          "date": "2026-02-16",
          "count": 7
        },
        {
          "date": "2026-02-20",
          "count": 12
        },
        {
          "date": "2026-02-24",
          "count": 9
        }
      ],
      "template": "github"
    },
    "image_url": "https://img.ogpilot.com/0dxm83dTyNCg5Dq_GZFT4SqsRyTWUO31d0HQwjIq0-A/plain/s3://og-pilot-development/jlhwskjsx08x56attaljw3ce0p65"
  }
]
```

Path Handling
-------------

[](#path-handling)

The `path` parameter enhances OG Pilot analytics by tracking which OG images perform better across different pages on your site. By capturing the request path, you get granular insights into click-through rates and engagement for each OG image.

The client automatically injects a `path` parameter on every request:

OptionBehavior`default: false`Uses the current request path when available (via framework auto-detection, request context, or `$_SERVER`), then falls back to `/``default: true`Forces the `path` parameter to `/`, regardless of the current request (unless `path` is provided explicitly)`path: "/..."`Uses the provided path verbatim (normalized to start with `/`), overriding auto-resolution### Automatic Framework Detection

[](#automatic-framework-detection)

The library automatically detects the current request path from popular PHP frameworks:

**Laravel** - Zero setup required! The library automatically uses Laravel's `request()` helper to get the current path. Just use OG Pilot anywhere in your Laravel application:

```
use Sunergos\OgPilot\Facades\OgPilot;

// In a controller, view, or anywhere in your Laravel app
$imageUrl = OgPilot::createImage([
    'template' => 'blog_post',
    'title' => 'My Blog Post',
]);
// path is automatically captured from the current request
```

### Manual Request Context (Other Frameworks)

[](#manual-request-context-other-frameworks)

For non-Laravel frameworks, set the current request context manually:

**Vanilla PHP:**

```
use Sunergos\OgPilot\OgPilot;

// At the start of your request handling
OgPilot::setCurrentRequest([
    'url' => $_SERVER['REQUEST_URI'] ?? '/'
]);

// Your application code...
$imageUrl = OgPilot::createImage(['title' => 'My Page']);
// path is automatically set from REQUEST_URI

// At the end of your request
OgPilot::clearCurrentRequest();
```

**Using withRequestContext (recommended):**

```
use Sunergos\OgPilot\OgPilot;

$imageUrl = OgPilot::withRequestContext(
    ['url' => $_SERVER['REQUEST_URI']],
    fn() => OgPilot::createImage(['title' => 'My Page'])
);
```

**Symfony Middleware:**

```
use Sunergos\OgPilot\OgPilot;
use Symfony\Component\HttpKernel\Event\RequestEvent;

class OgPilotListener
{
    public function onKernelRequest(RequestEvent $event): void
    {
        $request = $event->getRequest();
        OgPilot::setCurrentRequest([
            'path' => $request->getRequestUri()
        ]);
    }
}
```

### Manual Path Override

[](#manual-path-override)

```
$imageUrl = OgPilot::createImage([
    'template' => 'page',
    'title' => 'Hello OG Pilot',
    'path' => '/pricing?plan=pro'
]);
```

### Default Path

[](#default-path)

```
$imageUrl = OgPilot::createImage([
    'template' => 'blog_post',
    'title' => 'Default OG Image',
], [
    'default' => true
]);
// path is set to "/"
```

Configuration Options
---------------------

[](#configuration-options)

OptionEnvironment VariableDefaultDescription`api_key``OG_PILOT_API_KEY``null`Your OG Pilot API key`domain``OG_PILOT_DOMAIN``null`Your domain`base_url``OG_PILOT_BASE_URL``https://ogpilot.com`API base URL`connect_timeout``OG_PILOT_CONNECT_TIMEOUT``5.0`Connection timeout in seconds`timeout``OG_PILOT_TIMEOUT``10.0`Request timeout in seconds`strip_extensions``OG_PILOT_STRIP_EXTENSIONS``true`Strip file extensions from resolved paths (see [Strip extensions](#strip-extensions))`strip_query_parameters``OG_PILOT_STRIP_QUERY_PARAMETERS``false`Remove query strings from resolved paths before signing (see [Strip query parameters](#strip-query-parameters))### Strip extensions

[](#strip-extensions)

When `strip_extensions` is enabled, the client removes file extensions from the last segment of every resolved path. This ensures that `/docs`, `/docs.md`, `/docs.php`, and `/docs.html` all resolve to `"/docs"`, so analytics are consolidated under a single path regardless of the URL extension.

Multiple extensions are also stripped (`/archive.tar.gz` becomes `/archive`). Dotfiles like `/.hidden` are left unchanged. Query strings are preserved.

```
// Laravel (.env)
OG_PILOT_STRIP_EXTENSIONS=true

// Standalone PHP
OgPilot::setConfig([
    'api_key' => 'your-api-key',
    'domain' => 'your-domain.com',
    'strip_extensions' => true,
]);

// All of these resolve to path "/docs":
OgPilot::createImage(['title' => 'Docs', 'path' => '/docs']);
OgPilot::createImage(['title' => 'Docs', 'path' => '/docs.md']);
OgPilot::createImage(['title' => 'Docs', 'path' => '/docs.php']);

// Nested paths work too: /blog/my-post.html → /blog/my-post
// Query strings are preserved: /docs.md?ref=main → /docs?ref=main
// Dotfiles are unchanged: /.hidden stays /.hidden
```

### Strip query parameters

[](#strip-query-parameters)

When `strip_query_parameters` is enabled, the client removes the query string from resolved paths after normalization (and after extensions are stripped), so `/docs?ref=main`, `/docs?ref=prod`, and `/docs` all sign the same payload. This keeps analytics data grouped under a single path even when users append tracking parameters.

```
// Laravel (.env)
OG_PILOT_STRIP_QUERY_PARAMETERS=true

// Standalone PHP
OgPilot::setConfig([
    'api_key' => 'your-api-key',
    'domain' => 'your-domain.com',
    'strip_query_parameters' => true,
]);

// When enabled, /docs.md?ref=main resolves to /docs before signing.
```

Error Handling
--------------

[](#error-handling)

`createImage` is fail-safe and does not throw to your application on runtime failures. If generation fails for any reason (request/configuration/validation/etc.), the client logs an error and returns a fallback value.

```
$imageUrl = OgPilot::createImage(['title' => 'My Image']);
if ($imageUrl === null) {
    // Failed to generate image in URL mode
}

$json = OgPilot::createImage(['title' => 'My Image'], ['json' => true]);
if (($json['image_url'] ?? null) === null) {
    // Failed to generate image in JSON mode
}
```

In Laravel, errors are logged through `Log::error(...)`. In non-Laravel environments, the client falls back to PHP `error_log(...)`.

Framework Notes
---------------

[](#framework-notes)

This library is intended for **server-side usage only**. Keep your API key private and do not expose it in client-side code.

- **Laravel**: Use in controllers, jobs, or any server-side code
- **Symfony**: Use in controllers or services
- **WordPress**: Use in theme functions or plugins (server-side only)

Testing
-------

[](#testing)

```
composer test
```

License
-------

[](#license)

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

###  Health Score

33

—

LowBetter than 75% of packages

Maintenance89

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity34

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~3 days

Total

3

Last Release

55d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/ce7d2a2c5209d610d907d8b74564ddd9dab6df4e336ad9d454971016f05581de?d=identicon)[raulpopadineti](/maintainers/raulpopadineti)

---

Top Contributors

[![raulpopadineti](https://avatars.githubusercontent.com/u/1855287?v=4)](https://github.com/raulpopadineti "raulpopadineti (13 commits)")

---

Tags

laravelsocial mediaopengraphog-imageog-pilot

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/sunergos-og-pilot-php/health.svg)

```
[![Health](https://phpackages.com/badges/sunergos-og-pilot-php/health.svg)](https://phpackages.com/packages/sunergos-og-pilot-php)
```

###  Alternatives

[laravel/socialite

Laravel wrapper around OAuth 1 & OAuth 2 libraries.

5.7k96.9M674](/packages/laravel-socialite)[opentok/opentok

OpenTok is a platform for creating real time streaming video applications, created by TokBox.

1413.0M10](/packages/opentok-opentok)[omniphx/forrest

A Laravel library for Salesforce

2724.4M8](/packages/omniphx-forrest)[firefly-iii/data-importer

Firefly III Data Import Tool.

7545.8k](/packages/firefly-iii-data-importer)[vormkracht10/laravel-open-graph-image

Laravel package to generate dynamic Open Graph images

7217.7k](/packages/vormkracht10-laravel-open-graph-image)[spatie/laravel-og-image

Generate OG images for your Laravel app

305.2k](/packages/spatie-laravel-og-image)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)