sunergos/og-pilot-php

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

dev-main 2026-01-30 18:11 UTC

Requires

• php: ^8.1
• firebase/php-jwt: ^6.0
• guzzlehttp/guzzle: ^7.0

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0
• phpunit/phpunit: ^10.0

MIT

• Sunergos IT LLC
• Raul Popadineti

• opengraph
• laravel
• social-media
• og-image
• og-pilot

README

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

Requirements

• PHP 8.1 or higher
• Composer

Installation

Install the package via Composer:

composer require sunergos/og-pilot-php

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

For non-Laravel projects, configure the client directly:

use Sunergos\OgPilot\OgPilot;

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

Or use environment variables OG_PILOT_API_KEY and OG_PILOT_DOMAIN.

Usage

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

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

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

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
   • 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

Configuration Options

Option	Environment Variable	Default	Description
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

Error Handling

The package throws specific exceptions for different error scenarios:

use Sunergos\OgPilot\Exceptions\ConfigurationException;
use Sunergos\OgPilot\Exceptions\RequestException;
use Sunergos\OgPilot\Exceptions\OgPilotException;

try {
    $imageUrl = OgPilot::createImage(['title' => 'My Image']);
} catch (ConfigurationException $e) {
    // Missing or invalid configuration (API key, domain)
} catch (RequestException $e) {
    // HTTP request failed
    $statusCode = $e->getStatusCode();
} catch (OgPilotException $e) {
    // Base exception for all OG Pilot errors
}

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

composer test

License

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