https://github.com/hosmelq/laravel-open-graph-image
Generate dynamic Open Graph images for Laravel applications using Blade templates and Tailwind CSS.
https://github.com/hosmelq/laravel-open-graph-image
meta-tags open-graph open-graph-image open-graph-protocol
Last synced: 10 months ago
JSON representation
Generate dynamic Open Graph images for Laravel applications using Blade templates and Tailwind CSS.
- Host: GitHub
- URL: https://github.com/hosmelq/laravel-open-graph-image
- Owner: hosmelq
- License: mit
- Created: 2025-09-01T18:34:46.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-09-01T19:46:08.000Z (11 months ago)
- Last Synced: 2025-09-01T20:16:27.033Z (11 months ago)
- Topics: meta-tags, open-graph, open-graph-image, open-graph-protocol
- Language: PHP
- Homepage:
- Size: 177 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Laravel Open Graph Image
Generate dynamic Open Graph images for Laravel applications using Blade templates and Tailwind CSS.
See it in action: a real Open Graph image generated from a Blade + Tailwind template.
Source: https://laravel-open-graph-image.hosmelq.com/open-graph-image?template=demo
## Introduction
Using this package, you can generate Open Graph images from Blade templates styled with Tailwind CSS. Whether you want to create preview images for blog posts, product cards, or event announcements, this package handles it all.
```php
{{-- In your Blade template --}}
```
The image is generated when accessed and cached for subsequent requests.
## Requirements
- PHP 8.2+
- Laravel 12+
- Node.js and npm
- PHP extension ext-fileinfo (required for @embedImage)
## Installation & setup
You can install the package via composer:
```bash
composer require hosmelq/laravel-open-graph-image
```
### Publishing the config file
Optionally, you can publish the config file with this command:
```bash
php artisan vendor:publish --tag="open-graph-image-config"
```
View the published config file.
```php
return [
/*
|--------------------------------------------------------------------------
| Browsershot Configuration
|--------------------------------------------------------------------------
|
| Here you may configure various Browsershot options that control how
| HTML content is converted into images. These settings will be passed
| to the underlying Browsershot instance during image generation.
|
*/
'browsershot' => [
'timeout' => (int) env('OPEN_GRAPH_IMAGE_BROWSERSHOT_TIMEOUT', 30),
],
/*
|--------------------------------------------------------------------------
| Cache Configuration
|--------------------------------------------------------------------------
|
| These settings determine the caching behavior for generated Open Graph
| images and rendered views. You may specify different cache stores and
| TTL values for images and views to optimize performance.
|
*/
'cache' => [
'images' => [
'enabled' => env('OPEN_GRAPH_IMAGE_CACHE_IMAGES_ENABLED', false),
'store' => env('OPEN_GRAPH_IMAGE_CACHE_IMAGES_STORE', 'file'),
'ttl' => (int) env('OPEN_GRAPH_IMAGE_CACHE_IMAGES_TTL', 604800),
],
'views' => [
'enabled' => env('OPEN_GRAPH_IMAGE_CACHE_VIEWS_ENABLED', false),
'store' => env('OPEN_GRAPH_IMAGE_CACHE_VIEWS_STORE', 'file'),
'ttl' => (int) env('OPEN_GRAPH_IMAGE_CACHE_VIEWS_TTL', 3600),
],
],
/*
|--------------------------------------------------------------------------
| CSS Configuration
|--------------------------------------------------------------------------
|
| Here you may specify the CSS configuration for styling your Open Graph
| images. These settings control how your generated images will be
| visually styled and formatted.
|
*/
'css' => [
'path' => env('OPEN_GRAPH_IMAGE_CSS_PATH', ''),
],
/*
|--------------------------------------------------------------------------
| Image Dimensions
|--------------------------------------------------------------------------
|
| These values determine the default dimensions for generated Open Graph
| images. The standard recommended size for Open Graph images is
| 1200x630 pixels, which provides optimal display across platforms.
|
*/
'dimensions' => [
'height' => 630,
'width' => 1200,
],
/*
|--------------------------------------------------------------------------
| Route Configuration
|--------------------------------------------------------------------------
|
| These settings configure the HTTP routes that your Open Graph image
| generator will respond to. You may customize the path, prefix, and
| route names to fit your application's routing conventions.
|
*/
'route' => [
'name' => env('OPEN_GRAPH_IMAGE_ROUTE_NAME', 'open-graph-image'),
'path' => env('OPEN_GRAPH_IMAGE_ROUTE_PATH', 'open-graph-image'),
'prefix' => env('OPEN_GRAPH_IMAGE_ROUTE_PREFIX', ''),
'preview' => [
'enabled' => env('OPEN_GRAPH_IMAGE_ROUTE_PREVIEW_ENABLED', env('APP_ENV') === 'local'),
'name' => env('OPEN_GRAPH_IMAGE_ROUTE_PREVIEW_NAME', 'open-graph-image.preview'),
'path' => env('OPEN_GRAPH_IMAGE_ROUTE_PREVIEW_PATH', 'open-graph-image/preview'),
],
],
];
```
### Configuring Browsershot
This package uses Browsershot for screenshot generation. For detailed requirements and installation instructions, see the [Browsershot requirements](https://spatie.be/docs/browsershot/v4/requirements).
To get started, you'll need to install Puppeteer:
```bash
npm install puppeteer
```
### Downloading Tailwind CLI
Download the Tailwind CSS v4 binary:
```bash
php artisan open-graph-image:download-tailwind-binary
```
## Basic usage
### Getting started
Let's generate an Open Graph image for a blog post. We'll create a Blade template and add the meta component to your page.
First, create a template in `resources/views/open-graph-image/templates/post.blade.php`:
```blade
{{ $title }}
By {{ $author }} • {{ $date }}
```
Now, add the meta component to your page:
```blade
{{-- In your layout or page head --}}
```
The meta component outputs `og:image`, `og:image:width`, `og:image:height`, `og:image:type`, `twitter:card`, and `twitter:image` meta tags. The image is generated when accessed and cached for subsequent requests.
### Programmatically generating images
Generate images directly in your code:
```php
use HosmelQ\OpenGraphImage\Facades\OpenGraphImage;
$image = OpenGraphImage::template('post')
->with([
'title' => 'Getting Started with Laravel',
'author' => 'Jane Smith',
'date' => 'December 1, 2024'
])
->generate(); // Returns the PNG image as a string
```
### Using the preview mode
During development, preview your templates as HTML without generating images:
```
http://your-app.test/open-graph-image/preview?template=post&title=Test&author=John
```
The preview route is only available in the local environment by default.
> [!TIP]
> Use your browser's Responsive Mode with a 1200×630 viewport to preview templates at the exact Open Graph image dimensions. This speeds up design iteration without regenerating PNGs.
## Creating templates
Templates are Blade views stored in `resources/views/open-graph-image/templates/`.
### Simple template
```blade
{{-- resources/views/open-graph-image/templates/simple.blade.php --}}
{{ $text }}
```
### Demo template
```blade
{{-- resources/views/open-graph-image/templates/demo.blade.php --}}
Laravel Open Graph Image
Generate Open Graph images for your
Laravel application.
Terminal
$ composer require hosmelq/laravel-open-graph-image
```
### Using the image embedding directive
The `@embedImage` directive converts local images to data URIs. Use paths like `public_path('images/logo.png')`:
```blade
{{-- Embed a local image as a data URI --}}
))
```
## Customizing CSS
The package processes your templates with Tailwind CSS v4. To use custom CSS, publish the default file:
```bash
php artisan vendor:publish --tag="open-graph-image-css"
```
This creates `resources/vendor/open-graph-image/css/open-graph-image.css` that you can modify:
```css
@import "tailwindcss";
.gradient-text {
@apply bg-gradient-to-r from-blue-600 to-purple-600 bg-clip-text text-transparent;
}
```
Alternatively, use your own CSS file from any location:
```php
// .env
OPEN_GRAPH_IMAGE_CSS_PATH=/path/to/your/custom.css
```
## Testing
```bash
composer test
```
## Changelog
Please see [CHANGELOG.md](CHANGELOG.md) for more information on what has changed recently.
## Credits
- [Hosmel Quintana](https://github.com/hosmelq)
- [All Contributors](../../contributors)
## License
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.