shareglint / laravel
Laravel integration for Shareglint — signed og:image URLs, a Blade component and queued OG image generation for Eloquent models
Requires
- php: ^8.2
- illuminate/contracts: ^11.0|^12.0|^13.0
- illuminate/database: ^11.0|^12.0|^13.0
- illuminate/queue: ^11.0|^12.0|^13.0
- illuminate/support: ^11.0|^12.0|^13.0
- illuminate/view: ^11.0|^12.0|^13.0
- shareglint/shareglint-php: ^1.0
Requires (Dev)
- orchestra/testbench: ^10.0|^11.0
- pestphp/pest: ^4.0|^5.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Open Graph images for Laravel with Shareglint: signed og:image URLs, a Blade
component, and a model trait that renders the image in a queued job when a post is published.
composer require shareglint/laravel
php artisan vendor:publish --tag=shareglint-config # optional
SHAREGLINT_ACCOUNT_ID=acc_… # dashboard or GET /v1/account SHAREGLINT_SIGNING_SECRET=sign_… # signs og:image URLs SHAREGLINT_KEY=sk_… # only for the queued job / API calls # SHAREGLINT_BASE_URL=https://shareglint.com # SHAREGLINT_TEMPLATE=blog-og SHAREGLINT_EXTENSION=png (jpg, webp, pdf) # SHAREGLINT_QUEUE_CONNECTION= SHAREGLINT_QUEUE=
Signed URLs — no API call, no queue
<head> <x-og-image template="blog-og" :fields="['title' => $post->title, 'author' => $post->author->name]" :alt="$post->title" /> </head>
Prints og:image (+ width/height, default 1200×630), optional og:image:alt, twitter:card and
twitter:image. The image renders on the first crawler hit and is cached; the same values never cost
quota twice. Elsewhere:
og_image('blog-og', ['title' => $post->title, 'locale' => 'en']); // helper Shareglint::url('blog-og', ['title' => $post->title], 'jpg'); // facade Shareglint::autoOgUrl(url()->current()); // /u/ auto-OG, no secret Shareglint::render('blog-og', ['title' => 'Hi']); // any SDK method (shareglint/shareglint-php)
null fields are left out, booleans become 1/0, dates Y-m-d.
One template → 6 sizes — og 1200×630, square 1080×1080, portrait 1080×1350, story
1080×1920, pinterest 1000×1500, youtube 1280×720:
<x-og-image template="blog-og" :fields="['title' => $post->title]" size="square" /> {{-- width/height follow the size --}}
og_image('blog-og', ['title' => $post->title], size: 'story'); // signed with the fields Shareglint::autoOgUrl(url()->current(), size: 'story'); Shareglint::renderSizes('blog-og', ['title' => 'Hi'], ['og', 'square']); // one render (and quota unit) per size
Animated GIF and MP4 — the template's CSS animations, recorded frame by frame (up to 5 s, long edge
1080 px, 5 renders of quota each). For posts, chat and email; keep a still extension in og:image,
where crawlers show only a GIF's first frame:
og_image('animated-countdown', ['number' => 12], 'gif', duration: 4); // duration and fps are signed too Shareglint::render('animated-countdown', ['number' => 12], format: 'mp4', duration: 3, fps: 30);
Stored images for models
use Shareglint\Laravel\Concerns\HasOgImage; use Shareglint\Laravel\Contracts\OgImageable; class Post extends Model implements OgImageable { use HasOgImage; public function ogImageFields(): array { return ['title' => $this->title, 'author' => $this->author->name, 'date' => $this->published_at]; } // Optional overrides: public function ogImageTemplate(): string { return 'blog-og'; } public function ogImageColumn(): ?string { return 'og_image'; } // a nullable string column public function ogImageWatched(): ?array { return ['title', 'author_id']; } // null = any change }
On create, and on an update that changes a watched attribute, GenerateOgImage is queued after the
transaction commits, renders through the API with an idempotency key derived from the fields (a
retry never charges twice), and writes the file URL with saveQuietly(). Until then
$post->ogImageUrl() — and <x-og-image :model="$post" /> — return the signed URL of the same image,
so no page goes out without one. A full quota fails the job without retries; a busy API releases it
for 15 seconds.
<x-og-image :model="$post" /> <x-og-image auto /> {{-- auto-OG of the current URL --}} <x-og-image page="https://yourblog.com/hello" extension="webp" />
Tests
sh test.sh (from packages/: npm run test:laravel) — Composer and Pest with Orchestra Testbench in
Docker. The job tests run the real PHP SDK against a stand-in API under php -S.
MIT