### Install spatie/laravel-og-image

Source: https://context7.com/spatie/laravel-og-image/llms.txt

Install the package using Composer. Optionally, publish the configuration and screenshot layout views.

```bash
composer require spatie/laravel-og-image

# Publish config (optional)
php artisan vendor:publish --tag=og-image-config

# Publish screenshot layout view (optional)
php artisan vendor:publish --tag=og-image-views
```

--------------------------------

### Install Chromium on macOS

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/advanced-usage/troubleshooting.md

Install the Chromium browser using Homebrew on macOS.

```bash
brew install --cask chromium
```

--------------------------------

### Chaining Configuration Methods

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/basic-usage/customizing-screenshots.md

All configuration methods can be chained together for concise setup in your AppServiceProvider.

```php
OgImage::format('webp')
    ->size(1200, 630)
    ->disk('s3', 'og-images');
```

--------------------------------

### Install Laravel OG Image Package

Source: https://github.com/spatie/laravel-og-image/blob/main/README.md

Install the package using Composer. This package has a dependency on spatie/laravel-screenshot, which in turn requires Node.js and a Chrome/Chromium binary.

```bash
composer require spatie/laravel-og-image
```

--------------------------------

### Install Chromium on Ubuntu/Debian

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/advanced-usage/troubleshooting.md

Install the Chromium browser package on Ubuntu or Debian-based systems.

```bash
apt-get install -y chromium-browser
```

--------------------------------

### Configure Cloudflare Driver for OG Images

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/installation-setup.md

Use Cloudflare's Browser Rendering API instead of local installations of Node.js and Chrome. Configure this in your AppServiceProvider and add credentials to your .env file.

```php
use Spatie\OgImage\Facades\OgImage;

public function boot(): void
{
    OgImage::useCloudflare(
        apiToken: env('CLOUDFLARE_API_TOKEN'),
        accountId: env('CLOUDFLARE_ACCOUNT_ID'),
    );
}
```

```dotenv
CLOUDFLARE_API_TOKEN=your-api-token
CLOUDFLARE_ACCOUNT_ID=your-account-id
```

--------------------------------

### Example Blade View for OG Image

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/basic-usage/getting-started.md

This is an example of a Blade view that can be referenced by the `<x-og-image>` component. It uses the data passed via the `data` attribute.

```blade
{{-- resources/views/og-image/post.blade.php --}}
<div class="w-full h-full bg-blue-900 text-white flex items-center justify-center p-16">
    <div>
        <h1 class="text-6xl font-bold">{{ $title }}</h1>
        <p class="text-2xl mt-4">by {{ $author }}</p>
    </div>
</div>
```

--------------------------------

### Use Cloudflare Browser Rendering Driver

Source: https://context7.com/spatie/laravel-og-image/llms.txt

Utilize Cloudflare's Browser Rendering API for screenshots, avoiding the need for a local Chrome installation. Requires Cloudflare API token and account ID.

```php
use Spatie\OgImage\Facades\OgImage;

public function boot(): void
{
    OgImage::useCloudflare(
        apiToken: env('CLOUDFLARE_API_TOKEN'),   // Workers Scripts: Edit permission
        accountId: env('CLOUDFLARE_ACCOUNT_ID'), // From dash.cloudflare.com URL
    );
}
```

```env
CLOUDFLARE_API_TOKEN=your-api-token
CLOUDFLARE_ACCOUNT_ID=your-account-id
```

--------------------------------

### Resolve Screenshot URL Using Full URL

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/advanced-usage/customizing-the-page-url.md

Use this to include all query parameters in the cached URL, ensuring each unique combination of path and query parameters gets its own screenshot. Register this in your AppServiceProvider.

```php
use Illuminate\\Http\\Request;
use Spatie\\OgImage\\Facades\\OgImage;

public function boot(): void
{
    OgImage::resolveScreenshotUrlUsing(function (Request $request) {
        return $request->fullUrl();
    });
}
```

--------------------------------

### Customize Screenshot URL Resolution

Source: https://github.com/spatie/laravel-og-image/blob/main/resources/boost/skills/laravel-og-image/SKILL.md

Modify how the package resolves the URL for cached screenshots, for example, to include query parameters.

```php
OgImage::resolveScreenshotUrlUsing(function (Request $request) {
    return $request->fullUrl();
});
```

--------------------------------

### Conditionally Include Specific Query Parameters

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/advanced-usage/customizing-the-page-url.md

Customize URL resolution to selectively include only certain query parameters. This example includes the 'category' parameter if it exists.

```php
OgImage::resolveScreenshotUrlUsing(function (Request $request) {
    $url = $request->url();

    if ($request->has('category')) {
        $url .= '?category=' . $request->query('category');
    }

    return $url;
});
```

--------------------------------

### Configure Global Screenshot Settings

Source: https://github.com/spatie/laravel-og-image/blob/main/resources/boost/skills/laravel-og-image/SKILL.md

Set global configurations for image format, size, and disk using the `OgImage` facade in `AppServiceProvider`.

```php
use Spatie\OgImage\Facades\OgImage;

OgImage::format('webp')
    ->size(1200, 630)
    ->disk('s3', 'og-images');
```

--------------------------------

### Publish Configuration File

Source: https://github.com/spatie/laravel-og-image/blob/main/README.md

Optionally, publish the configuration file for the package to customize its behavior.

```bash
php artisan vendor:publish --tag="og-image-config"
```

--------------------------------

### Configure Global Screenshot Settings

Source: https://context7.com/spatie/laravel-og-image/llms.txt

Set default screenshot dimensions, format, quality, and storage disk globally. These methods are chainable.

```php
use Spatie\OgImage\Facades\OgImage;

public function boot(): void
{
    OgImage::format('webp')          // 'jpeg' | 'png' | 'webp'
        ->size(1200, 630)             // width × height in pixels
        ->disk('s3', 'og-images');    // filesystem disk + path
}
```

```php
// config/og-image.php — fine-grained defaults
return [
    'disk'                  => 'public',
    'path'                  => 'og-images',
    'width'                 => 1200,
    'height'                => 630,
    'format'                => 'jpeg',
    'quality'               => 80,          // 1-100, null = driver default
    'redirect_cache_max_age'=> 60 * 60 * 24 * 7, // 7-day CDN cache
    'lock_timeout'          => 60,
];
```

--------------------------------

### Configure Screenshot Builder

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/basic-usage/customizing-screenshots.md

Use `configureScreenshot()` to pass a closure that receives the `ScreenshotBuilder` instance for advanced customization. This allows setting options like `waitUntil`.

```php
use Spatie\LaravelScreenshot\Enums\WaitUntil;
use Spatie\LaravelScreenshot\ScreenshotBuilder;

OgImage::configureScreenshot(function (ScreenshotBuilder $screenshot) {
    $screenshot->waitUntil(WaitUntil::NetworkIdle0);
});
```

--------------------------------

### Configure Low-Level Screenshot Options

Source: https://context7.com/spatie/laravel-og-image/llms.txt

Pass a closure to customize the underlying ScreenshotBuilder for advanced control over wait strategies, Chrome paths, or delays. This can be combined with other configuration methods.

```php
use Spatie\LaravelScreenshot\Enums\WaitUntil;
use Spatie\LaravelScreenshot\ScreenshotBuilder;
use Spatie\OgImage\Facades\OgImage;

public function boot(): void
{
    OgImage::useCloudflare(
            apiToken: env('CLOUDFLARE_API_TOKEN'),
            accountId: env('CLOUDFLARE_ACCOUNT_ID'),
        )
        ->configureScreenshot(function (ScreenshotBuilder $screenshot) {
            // Wait until all network requests settle before screenshotting
            $screenshot->waitUntil(WaitUntil::NetworkIdle0);
        });
}
```

```php
// Fix Chrome not found at the default path
OgImage::configureScreenshot(function (ScreenshotBuilder $screenshot) {
    $screenshot->setChromePath('/usr/bin/chromium');
});
```

--------------------------------

### Run Package Tests

Source: https://github.com/spatie/laravel-og-image/blob/main/README.md

Execute the package's test suite to ensure everything is functioning correctly.

```bash
composer test
```

--------------------------------

### Configure Chrome/Chromium Path

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/advanced-usage/troubleshooting.md

Set a custom path for the Chrome or Chromium binary if it's not in a standard location. This is done within a service provider.

```php
use Spatie\OgImage\Facades\OgImage;

OgImage::configureScreenshot(function ($screenshot) {
    $screenshot->setChromePath('/usr/bin/chromium');
});
```

--------------------------------

### Publish Laravel OG Image Configuration

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/installation-setup.md

Optionally publish the configuration file to customize package settings like disk, path, dimensions, and cache settings.

```bash
php artisan vendor:publish --tag=og-image-config
```

--------------------------------

### Set Storage Disk and Path

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/basic-usage/customizing-screenshots.md

Specify the storage disk and directory where OG images should be saved. The default is the 'public' disk in the 'og-images' directory.

```php
OgImage::disk('s3', 'og-images');
```

--------------------------------

### Preview Mode

Source: https://context7.com/spatie/laravel-og-image/llms.txt

Enable preview mode by appending `?ogimage` to a URL to render the OG image template without saving an image.

```APIDOC
## Preview mode

Append `?ogimage` to any page URL to render just the OG image template at the configured dimensions, using the page's full `<head>`. No image is saved; this is purely for local development and debugging.

```
https://yourapp.com/blog/my-post?ogimage
# Renders the <x-og-image> template at 1200×630 with all CSS and fonts applied
```
```

--------------------------------

### Implement ScreenshotDriver Interface

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/advanced-usage/using-a-custom-screenshot-driver.md

Implement the ScreenshotDriver interface to create a custom screenshot driver. The generateScreenshot method should return the image as a binary string, while saveScreenshot should save it to a specified path. The ScreenshotOptions object provides access to configured options.

```php
use Spatie\LaravelScreenshot\Drivers\ScreenshotDriver;
use Spatie\LaravelScreenshot\ScreenshotOptions;

class MyScreenshotDriver implements ScreenshotDriver
{
    public function generateScreenshot(
        string $input,
        bool $isHtml,
        ScreenshotOptions $options,
    ): string {
        // Take the screenshot and return the image as a binary string.
        //
        // $input is a URL (when $isHtml is false) or an HTML string (when $isHtml is true).
        // $options contains width, height, type, deviceScaleFactor, etc.
    }

    public function saveScreenshot(
        string $input,
        bool $isHtml,
        ScreenshotOptions $options,
        string $path,
    ): void {
        // Take the screenshot and save it to $path.
    }
}
```

--------------------------------

### Configure Image Quality

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/basic-usage/customizing-screenshots.md

Set the quality for JPEG and WebP images. This can be done in the `config/og-image.php` file or via `configureScreenshot()` for more granular control. A value of `null` uses the driver's default.

```php
// config/og-image.php
'quality' => 80,
```

--------------------------------

### Nginx Configuration for Direct Serving

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/basic-usage/managing-caching-and-storage.md

Add this Nginx location block to serve generated OG images directly from disk, bypassing PHP for improved performance. It checks for the image file and serves it if found, otherwise falls back to PHP.

```nginx
location ~ ^/og-image/([a-f0-9]+\.(jpeg|jpg|png|webp)) {
    try_files /storage/og-images/$1 /index.php?$query_string;
}
```

--------------------------------

### Nginx Optimization for Serving Images

Source: https://context7.com/spatie/laravel-og-image/llms.txt

Configure Nginx to serve generated OG images directly from disk, bypassing PHP.

```APIDOC
## Nginx optimization for serving images without PHP

When not using a CDN, add an nginx rule to serve already-generated images directly from disk, bypassing PHP entirely.

```nginx
# Place before the location / block in your nginx site config
location ~ ^/og-image/([a-f0-9]+\.(jpeg|jpg|png|webp))$ {
    try_files /storage/og-images/$1 /index.php?$query_string;
}
```
```

--------------------------------

### Registering Custom Action

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/advanced-usage/customizing-actions.md

After creating your custom action class, register it in your `config/og-image.php` file to replace the default action.

```php
'actions' => [
    'generate_og_image' => \App\Actions\CustomGenerateOgImageAction::class,
],
```

--------------------------------

### Set WaitUntil NetworkIdle0

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/advanced-usage/troubleshooting.md

Configure the screenshot process to wait until the network is idle before taking the screenshot. This helps ensure all assets like CSS and web fonts are loaded.

```php
use Spatie\LaravelScreenshot\Enums\WaitUntil;

OgImage::configureScreenshot(function ($screenshot) {
    $screenshot->waitUntil(WaitUntil::NetworkIdle0);
});
```

--------------------------------

### Default Actions Configuration

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/advanced-usage/customizing-actions.md

This configuration shows the default actions registered in the `og-image` config file. These actions handle various aspects of OG image generation and injection.

```php
        'actions' => [
            'generate_og_image' => \Spatie\OgImage\Actions\GenerateOgImageAction::class,
            'inject_og_image_fallback' => \Spatie\OgImage\Actions\InjectOgImageFallbackAction::class,
            'render_og_image_screenshot' => \Spatie\OgImage\Actions\RenderOgImageScreenshotAction::class,
        ],
```

--------------------------------

### Preview OG Image with ?ogimage

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/advanced-usage/troubleshooting.md

Append `?ogimage` to a URL to preview the OG image content and dimensions before it's screenshotted. This is useful for debugging rendering and asset loading.

```url
https://yourapp.com/blog/my-post?ogimage
```

--------------------------------

### Combine Cloudflare with Screenshot Configuration

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/basic-usage/customizing-screenshots.md

You can combine `useCloudflare()` with `configureScreenshot()` to leverage Cloudflare's rendering while applying custom screenshot builder settings.

```php
OgImage::useCloudflare(
        apiToken: env('CLOUDFLARE_API_TOKEN'),
        accountId: env('CLOUDFLARE_ACCOUNT_ID'),
    )
    ->configureScreenshot(function (ScreenshotBuilder $screenshot) {
        $screenshot->waitUntil(WaitUntil::NetworkIdle0);
    });
```

--------------------------------

### Implement and Use a Custom Screenshot Driver

Source: https://context7.com/spatie/laravel-og-image/llms.txt

Implement the `ScreenshotDriver` interface to integrate any third-party screenshot service. Register your custom driver using `useDriver()`.

```php
use Spatie\LaravelScreenshot\Drivers\ScreenshotDriver;
use Spatie\LaravelScreenshot\ScreenshotOptions;
use Spatie\OgImage\Facades\OgImage;

class MyApiScreenshotDriver implements ScreenshotDriver
{
    public function generateScreenshot(string $input, bool $isHtml, ScreenshotOptions $options): string
    {
        // $input  = URL or HTML string
        // $isHtml = true when $input is raw HTML
        $response = Http::post('https://screenshot-api.example.com/capture', [
            'url'    => $input,
            'width'  => $options->width,
            'height' => $options->height,
            'type'   => $options->type->value, // 'jpeg' | 'png' | 'webp'
        ]);

        return $response->body(); // binary image string
    }

    public function saveScreenshot(string $input, bool $isHtml, ScreenshotOptions $options, string $path): void
    {
        file_put_contents($path, $this->generateScreenshot($input, $isHtml, $options));
    }
}

// Register in AppServiceProvider:
OgImage::useDriver(new MyApiScreenshotDriver());
```

--------------------------------

### Generate OG Images with Artisan Command

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/basic-usage/pre-generating-images.md

Use the Artisan command to pre-generate OG images for multiple URLs simultaneously. This is useful for bulk generation.

```bash
php artisan og-image:generate https://yourapp.com/page1 https://yourapp.com/page2
```

--------------------------------

### Artisan Command for Pre-generation

Source: https://context7.com/spatie/laravel-og-image/llms.txt

Use the artisan command to pre-generate OG images for one or more URLs.

```APIDOC
```bash
# Or use the artisan command to pre-generate one or more pages
php artisan og-image:generate https://yourapp.com/blog/post-1 https://yourapp.com/blog/post-2
```
```

--------------------------------

### Nginx Optimization for Serving OG Images

Source: https://context7.com/spatie/laravel-og-image/llms.txt

Configure Nginx to serve generated OG images directly from disk, bypassing PHP. This improves performance when not using a CDN.

```nginx
# Place before the location / block in your nginx site config
location ~ ^/og-image/([a-f0-9]+\.(jpeg|jpg|png|webp))$ {
    try_files /storage/og-images/$1 /index.php?$query_string;
}
```

--------------------------------

### Use Cloudflare Browser Rendering

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/basic-usage/customizing-screenshots.md

Configure the package to use Cloudflare's Browser Rendering service instead of the default Browsershot. You need to provide your Cloudflare API token and account ID.

```php
OgImage::useCloudflare(
    apiToken: env('CLOUDFLARE_API_TOKEN'),
    accountId: env('CLOUDFLARE_ACCOUNT_ID'),
);
```

--------------------------------

### Registering a Fallback OG Image

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/basic-usage/defining-fallback-images.md

Register a closure in `AppServiceProvider` to define a fallback OG image. The closure receives the current request and should return a view.

```php
use Illuminate\Http\Request;
use Spatie\OgImage\Facades\OgImage;

public function boot(): void
{
    OgImage::fallbackUsing(function (Request $request) {
        return view('og-image.fallback', [
            'title' => config('app.name'),
        ]);
    });
}
```

--------------------------------

### Preview OG Image Template in Browser

Source: https://context7.com/spatie/laravel-og-image/llms.txt

Append `?ogimage` to a page URL to preview the OG image template directly in the browser. This renders the template with full head content for local development and debugging without saving an image.

```text
https://yourapp.com/blog/my-post?ogimage
# Renders the <x-og-image> template at 1200×630 with all CSS and fonts applied
```

--------------------------------

### Configure Storage Disk

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/basic-usage/managing-caching-and-storage.md

Set the storage disk and directory for generated OG images using the OgImage facade. This is useful for directing images to specific storage locations like S3.

```php
use Spatie\OgImage\Facades\OgImage;

OgImage::disk('s3', 'og-images');
```

--------------------------------

### Pre-generate OG Images via Artisan Command

Source: https://context7.com/spatie/laravel-og-image/llms.txt

Use the Artisan command to pre-generate OG images for one or more URLs. This command is helpful for batch generation during deployment or other maintenance tasks.

```bash
php artisan og-image:generate https://yourapp.com/blog/post-1 https://yourapp.com/blog/post-2
```

--------------------------------

### Using an Existing Image URL

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/basic-usage/getting-started.md

Provide an existing image URL using the `url` attribute if you prefer to use a pre-existing image instead of generating one. The package will use this URL for the meta tags.

```blade
@if($post->og_image)
    <x-og-image :url="$post->og_image" />
@else
    <x-og-image view="og-image.post" :data="['title' => $post->title]" />
@endif
```

--------------------------------

### Publish OG Image Views

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/advanced-usage/customizing-the-screenshot-layout.md

Publish the OG image views to customize the screenshot layout. This makes `screenshot.blade.php` available for modification.

```bash
php artisan vendor:publish --tag=og-image-views
```

--------------------------------

### Register Custom Screenshot Driver

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/advanced-usage/using-a-custom-screenshot-driver.md

Register your custom screenshot driver with the OgImage facade. This tells the package to use your driver for generating screenshots.

```php
use Spatie\OgImage\Facades\OgImage;

OgImage::useDriver(new MyScreenshotDriver());
```

--------------------------------

### Programmatic Pre-generation of OG Images

Source: https://context7.com/spatie/laravel-og-image/llms.txt

Generate OG images programmatically for a given URL, either synchronously or asynchronously.

```APIDOC
## `OgImage::generateForUrl()` — Programmatic pre-generation

Fetch a page, extract its `<x-og-image>` template, take the screenshot, and save the image — all without waiting for a crawler. Returns the public URL of the saved image.

```php
use Spatie\OgImage\Facades\OgImage;

// Generate synchronously (e.g., from a seeder or console command)
$imageUrl = OgImage::generateForUrl('https://yourapp.com/blog/my-post');
// => "https://yourapp.com/storage/og-images/a1b2c3d4e5f6.jpeg"

// Dispatch asynchronously after publishing content
class PublishPostAction
{
    public function execute(Post $post): void
    {
        $post->update(['published_at' => now()]);

        dispatch(function () use ($post) {
            OgImage::generateForUrl(route('posts.show', $post));
        })->afterResponse();
    }
}
```
```

--------------------------------

### Extending GenerateOgImageAction

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/advanced-usage/customizing-actions.md

Create a custom action class by extending the default `GenerateOgImageAction` and overriding the `generateImage` method to implement custom image generation logic.

```php
namespace App\Actions;

use Spatie\OgImage\Actions\GenerateOgImageAction;

class CustomGenerateOgImageAction extends GenerateOgImageAction
{
    protected function generateImage(array $cached, string $path, $disk): void
    {
        // Custom generation logic...
    }
}
```

--------------------------------

### Programmatically Pre-generate OG Images

Source: https://context7.com/spatie/laravel-og-image/llms.txt

Generate OG images for specific URLs programmatically, either synchronously or asynchronously. This is useful for pre-generating images from seeders, console commands, or after content is published to avoid initial loading delays.

```php
use Spatie\OgImage\Facades\OgImage;

// Generate synchronously (e.g., from a seeder or console command)
$imageUrl = OgImage::generateForUrl('https://yourapp.com/blog/my-post');
// => "https://yourapp.com/storage/og-images/a1b2c3d4e5f6.jpeg"

// Dispatch asynchronously after publishing content
class PublishPostAction
{
    public function execute(Post $post): void
    {
        $post->update(['published_at' => now()]);

        dispatch(function () use ($post) {
            OgImage::generateForUrl(route('posts.show', $post));
        })->afterResponse();
    }
}
```

--------------------------------

### Default Laravel OG Image Configuration

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/installation-setup.md

This is the content of the published configuration file, showing default settings for disk, path, dimensions, format, quality, preview parameter, cache settings, and custom actions.

```php
return [
    /*
     * The filesystem disk used to store generated OG images.
     */
    'disk' => 'public',

    /*
     * The path within the disk where OG images will be stored.
     */
    'path' => 'og-images',

    /*
     * The dimensions of the generated OG images in pixels.
     */
    'width' => 1200,
    'height' => 630,

    /*
     * The default image format. Supported: "jpeg", "png", "webp".
     */
    'format' => 'jpeg',

    /*
     * The image quality for JPEG and WebP formats (1-100).
     * Set to null to use the driver's default quality.
     */
    'quality' => null,

    /*
     * The query parameter used to trigger OG image preview mode.
     * Appending this parameter to any page URL renders just the
     * template content at the configured dimensions.
     */
    'preview_parameter' => 'ogimage',

    /*
     * The number of seconds that CDNs and browsers may cache the image
     * response from /og-image/{hash}.jpeg.
     * Since image URLs are content-hashed, this is safe to cache aggressively.
     * Set to 0 to disable caching.
     */
    'redirect_cache_max_age' => 60 * 60 * 24,

    /*
     * The maximum number of seconds to wait for a lock when generating
     * an OG image. This prevents concurrent requests from generating
     * the same image simultaneously.
     */
    'lock_timeout' => 60,

    /*
     * The actions used by this package. You can replace any of them with
     * your own class to customize the behavior. Your custom class should
     * extend the default action.
     *
     * Learn more: https://spatie.be/docs/laravel-og-image/v1/advanced-usage/customizing-actions
     */
    'actions' => [
        'generate_og_image' => \Spatie\OgImage\Actions\GenerateOgImageAction::class,
        'inject_og_image_fallback' => \Spatie\OgImage\Actions\InjectOgImageFallbackAction::class,
        'render_og_image_screenshot' => \Spatie\OgImage\Actions\RenderOgImageScreenshotAction::class,
    ],

];
```

--------------------------------

### Customizing Action Classes

Source: https://context7.com/spatie/laravel-og-image/llms.txt

Override core action classes to hook into the OG image generation pipeline.

```APIDOC
## Customizing action classes

Override any of the three core action classes to hook into the generation pipeline. Register the replacement in `config/og-image.php`.

```php
// app/Actions/CustomGenerateOgImageAction.php
namespace App\Actions;

use Illuminate\Contracts\Filesystem\Filesystem;
use Spatie\OgImage\Actions\GenerateOgImageAction;

class CustomGenerateOgImageAction extends GenerateOgImageAction
{
    protected function generateImage(array $cached, string $path, Filesystem $disk): void
    {
        // Log before generating
        logger()->info('Generating OG image', ['url' => $cached['url'], 'path' => $path]);

        parent::generateImage($cached, $path, $disk);

        // Notify after generation
        cache()->put("og-image-generated:{$path}", now(), now()->addDay());
    }
}
```

```php
// config/og-image.php
'actions' => [
    'generate_og_image' => \App\Actions\CustomGenerateOgImageAction::class,
    // Other actions use package defaults
],
```
```

--------------------------------

### Customize OG Image Generation Action

Source: https://context7.com/spatie/laravel-og-image/llms.txt

Override the default `GenerateOgImageAction` class to hook into the image generation pipeline. Register your custom action in the `config/og-image.php` file.

```php
// app/Actions/CustomGenerateOgImageAction.php
namespace App\Actions;

use Illuminate\Contracts\Filesystem\Filesystem;
use Spatie\OgImage\Actions\GenerateOgImageAction;

class CustomGenerateOgImageAction extends GenerateOgImageAction
{
    protected function generateImage(array $cached, string $path, Filesystem $disk): void
    {
        // Log before generating
        logger()->info('Generating OG image', ['url' => $cached['url'], 'path' => $path]);

        parent::generateImage($cached, $path, $disk);

        // Notify after generation
        cache()->put("og-image-generated:{$path}", now(), now()->addDay());
    }
}
```

```php
// config/og-image.php
'actions' => [
    'generate_og_image' => \App\Actions\CustomGenerateOgImageAction::class,
    // Other actions use package defaults
],
```

--------------------------------

### Programmatically Generate OG Image for a URL

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/basic-usage/pre-generating-images.md

Generate an OG image for a specific URL programmatically. This method fetches the page, finds the OG image template, takes a screenshot, and saves it.

```php
use Spatie\OgImage\Facades\OgImage;

$imageUrl = OgImage::generateForUrl('https://yourapp.com/blog/my-post');
```

--------------------------------

### Use Existing Image URL for OG Image

Source: https://context7.com/spatie/laravel-og-image/llms.txt

If an image URL is already available (e.g., from a CMS), pass it to the `url` attribute of the `<x-og-image>` component. The package will use this URL directly, skipping screenshot generation.

```blade
@if($post->og_image_url)
    {{-- Use the CMS-provided image directly --}}
    <x-og-image :url="$post->og_image_url" />
@else
    {{-- Fall back to auto-generated screenshot --}} 
    <x-og-image view="og-images.post" :data="['title' => $post->title]" />
@endif
```

--------------------------------

### Dispatch Job to Generate OG Image After Content Publish

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/basic-usage/pre-generating-images.md

Dispatch a queued job to generate an OG image after content is published. This ensures the image is ready before it's requested by crawlers.

```php
use Spatie\OgImage\Facades\OgImage;

class PublishPostAction
{
    public function execute(Post $post): void
    {
        // ... publish logic ...

        dispatch(function () use ($post) {
            OgImage::generateForUrl($post->url);
        });
    }
}
```

--------------------------------

### Specifying Image Format

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/basic-usage/getting-started.md

You can specify the desired image format (e.g., 'webp') using the `format` attribute on the `<x-og-image>` component. By default, images are generated as JPEG.

```blade
<x-og-image format="webp">
    <div class="w-full h-full bg-gradient-to-r from-purple-500 to-pink-500 text-white flex items-center justify-center">
        <h1 class="text-6xl font-bold">{{ $title }}</h1>
    </div>
</x-og-image>
```

--------------------------------

### Generated Meta Tags and HTML Structure

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/basic-usage/getting-started.md

The package automatically injects `og:image`, `twitter:image`, and `twitter:card` meta tags into the `<head>`. It also outputs a hidden `<template>` tag in the body containing the image content.

```html
<head>
    <!-- your existing head content -->
    <meta property="og:image" content="https://yourapp.com/og-image/a1b2c3d4e5f6.jpeg">
    <meta name="twitter:image" content="https://yourapp.com/og-image/a1b2c3d4e5f6.jpeg">
    <meta name="twitter:card" content="summary_large_image">
</head>
<body>
    <template data-og-image>
        <div class="w-full h-full bg-blue-900 text-white flex items-center justify-center">
            <h1 class="text-6xl font-bold">My Post Title</h1>
        </div>
    </template>
</body>
```

--------------------------------

### Register Fallback OG Image View

Source: https://context7.com/spatie/laravel-og-image/llms.txt

Register a closure to provide a default OG image for pages without an explicit component. The closure receives the Request object and can return null to skip routes.

```php
use Illuminate\Http\Request;
use Spatie\OgImage\Facades\OgImage;

public function boot(): void
{
    OgImage::fallbackUsing(function (Request $request) {
        // Skip admin and API routes
        if ($request->routeIs('admin.*', 'api.*')) {
            return null;
        }

        $title = $request->route('post')?->title ?? config('app.name');

        return view('og-images.fallback', [
            'title' => $title,
            'url'   => $request->url(),
        ]);
    });
}
```

```blade
{{-- resources/views/og-images/fallback.blade.php --}}
<div class="w-full h-full bg-slate-800 text-white flex flex-col items-center justify-center p-16 gap-6">
    <img src="/logo.svg" class="h-16 opacity-80" />
    <h1 class="text-5xl font-bold text-center">{{ $title }}</h1>
    <p class="text-lg opacity-50">{{ $url }}</p>
</div>
```

--------------------------------

### Custom Format and Dimensions for OG Images

Source: https://context7.com/spatie/laravel-og-image/llms.txt

Override the output format (e.g., 'webp') and specify custom dimensions (width and height) for the generated OG image. The hash includes dimensions, ensuring unique URLs for different sizes.

```blade
{{-- Twitter card at a different aspect ratio, using WebP --}}
<x-og-image format="webp" :width="1200" :height="600">
    <div class="w-full h-full bg-pink-600 text-white flex items-center justify-center">
        <h1 class="text-7xl font-black">{{ $product->name }}</h1>
    </div>
</x-og-image>
```

--------------------------------

### Customize Screenshot URL Resolution

Source: https://context7.com/spatie/laravel-og-image/llms.txt

Override the default behavior of resolving screenshot URLs to include specific query parameters.

```APIDOC
## `OgImage::resolveScreenshotUrlUsing()` — Customize the screenshot URL

By default the page URL is stored without query parameters (so `/posts?page=2` and `/posts?page=3` share the same OG image). Override this to include relevant query parameters in the cached URL.

```php
use Illuminate\Http\Request;
use Spatie\OgImage\Facades\OgImage;

public function boot(): void
{
    OgImage::resolveScreenshotUrlUsing(function (Request $request) {
        $url = $request->url();

        // Only include the 'category' query param when present
        if ($request->has('category')) {
            $url .= '?category=' . $request->query('category');
        }

        return $url;
    });
}
```
```

--------------------------------

### Set Global Image Size

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/basic-usage/customizing-screenshots.md

Change the default dimensions for all OG images generated by the package. This is typically done in your AppServiceProvider.

```php
use Spatie\OgImage\Facades\OgImage;

public function boot(): void
{
    OgImage::size(1200, 630);
}
```

--------------------------------

### Inline Blade Component for OG Images

Source: https://context7.com/spatie/laravel-og-image/llms.txt

Use the `<x-og-image>` component directly within a Blade view to define the OG image content. The package hashes the inner HTML and injects meta tags.

```blade
<x-og-image>
    <div class="w-full h-full bg-blue-900 text-white flex items-center justify-center p-16">
        <div>
            <p class="text-xl uppercase tracking-widest opacity-60">{{ $post->category }}</p>
            <h1 class="text-6xl font-bold mt-2">{{ $post->title }}</h1>
            <p class="text-2xl mt-4 opacity-80">by {{ $post->author->name }}</p>
        </div>
    </div>
</x-og-image>

{{-- Rendered <head> output: --}}
{{--
<meta property="og:image" content="https://yourapp.com/og-image/a1b2c3d4e5f6.jpeg">
<meta name="twitter:image" content="https://yourapp.com/og-image/a1b2c3d4e5f6.jpeg">
<meta name="twitter:card" content="summary_large_image">
--?>
```

--------------------------------

### Set Image Format

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/basic-usage/customizing-screenshots.md

Change the default image format from JPEG to PNG or WebP. This method can be called in your AppServiceProvider.

```php
OgImage::format('webp');
```

--------------------------------

### Customizing Fallback with Request Data

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/basic-usage/defining-fallback-images.md

Utilize request data within the fallback closure to dynamically set the OG image title and URL. This allows for personalized fallbacks based on route parameters or other request attributes.

```php
OgImage::fallbackUsing(function (Request $request) {
    $title = $request->route('post')?->title ?? config('app.name');

    return view('og-image.fallback', [
        'title' => $title,
        'url' => $request->url(),
    ]);
});
```

--------------------------------

### Conditional Fallback Image

Source: https://github.com/spatie/laravel-og-image/blob/main/resources/boost/skills/laravel-og-image/SKILL.md

Conditionally skip the fallback OG image for specific requests by returning `null` from the `fallbackUsing` closure.

```php
OgImage::fallbackUsing(function (Request $request) {
    if ($request->routeIs('admin.*')) {
        return null;
    }

    return view('og-image.fallback', ['title' => config('app.name')]);
});
```

--------------------------------

### Clear Generated OG Images

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/basic-usage/clearing-generated-images.md

Run this artisan command to delete all generated OG images from the configured disk path. Images will be regenerated on the next request or cache refresh.

```bash
php artisan og-image:clear
```

--------------------------------

### Custom OG Image Format

Source: https://github.com/spatie/laravel-og-image/blob/main/resources/boost/skills/laravel-og-image/SKILL.md

Change the image format (e.g., 'webp') from the default JPEG by using the `format` attribute on the `<x-og-image>` component.

```blade
<x-og-image format="webp">
    <div>WebP format</div>
</x-og-image>
```

--------------------------------

### Skipping Fallback for Specific Routes

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/basic-usage/defining-fallback-images.md

Return `null` from the fallback closure to prevent OG image generation for specific requests, such as those matching admin routes.

```php
OgImage::fallbackUsing(function (Request $request) {
    if ($request->routeIs('admin.*')) {
        return null;
    }

    return view('og-image.fallback', [
        'title' => config('app.name'),
    ]);
});
```

--------------------------------

### External Blade View for OG Images

Source: https://context7.com/spatie/laravel-og-image/llms.txt

Reference a separate Blade view for your OG image layout using the `view` attribute. Pass data to this view using the `data` attribute.

```blade
{{-- In the page view --}}
<x-og-image view="og-images.post" :data="['title' => $post->title, 'author' => $post->author->name, 'tag' => $post->primaryTag]" />

{{-- resources/views/og-images/post.blade.php --}}
<div class="w-full h-full bg-gradient-to-br from-slate-900 to-slate-700 text-white flex items-center justify-center p-16">
    <div class="space-y-4">
        <span class="bg-blue-500 text-sm font-semibold px-3 py-1 rounded-full">{{ $tag }}</span>
        <h1 class="text-5xl font-bold leading-tight">{{ $title }}</h1>
        <p class="text-xl opacity-70">by {{ $author }}</p>
    </div>
</div>
```

--------------------------------

### Referencing a Blade View for OG Image Content

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/basic-usage/getting-started.md

Instead of inline HTML, you can specify a Blade view using the `view` attribute and pass data to it via the `data` attribute. This is useful for reusable or complex layouts.

```blade
<x-og-image view="og-image.post" :data="['title' => $post->title, 'author' => $post->author->name]" />
```

--------------------------------

### Fallback View Structure

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/basic-usage/defining-fallback-images.md

The fallback view should be a simple Blade file containing only the necessary HTML for the OG image. It inherits the page's head, making CSS, fonts, and Vite assets available.

```blade
{{-- resources/views/og-image/fallback.blade.php --}}
<div class="w-full h-full bg-blue-900 text-white flex items-center justify-center p-16">
    <h1 class="text-6xl font-bold">{{ $title }}</h1>
</div>
```

--------------------------------

### Set Redirect Cache Max Age

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/basic-usage/managing-caching-and-storage.md

Configure the cache duration for OG image redirects in the `config/og-image.php` file. This controls the `Cache-Control: max-age` header, allowing for longer caching periods when using content-hashed URLs.

```php
// config/og-image.php
'redirect_cache_max_age' => 60 * 60 * 24 * 7, // 7 days
```

--------------------------------

### Override Action Classes

Source: https://github.com/spatie/laravel-og-image/blob/main/resources/boost/skills/laravel-og-image/SKILL.md

Customize the action classes used by the package by modifying the `actions` configuration in `config/og-image.php`.

```php
'actions' => [
    'generate_og_image' => \App\Actions\CustomGenerateOgImageAction::class,
    'inject_og_image_fallback' => \Spatie\OgImage\Actions\InjectOgImageFallbackAction::class,
    'render_og_image_screenshot' => \Spatie\OgImage\Actions\RenderOgImageScreenshotAction::class,
],
```

--------------------------------

### Define OG Image with Blade Component

Source: https://github.com/spatie/laravel-og-image/blob/main/README.md

Use the x-og-image Blade component to define your OG image content inline within your Blade views. This component automatically generates the necessary meta tags and a template for the screenshot.

```blade
<x-og-image>
    <div class="w-full h-full bg-blue-900 text-white flex items-center justify-center">
        <h1 class="text-6xl font-bold">{{ $post->title }}</h1>
    </div>
</x-og-image>
```

--------------------------------

### Increase Lock Timeout

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/advanced-usage/troubleshooting.md

Adjust the lock timeout duration in the configuration file if you encounter timeout issues when generating large images or on slow servers.

```php
// config/og-image.php
'lock_timeout' => 120,
```

--------------------------------

### HTML Output for OG Image Generation

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/basic-usage/how-it-works.md

This HTML structure is outputted by the Blade component and middleware. The meta tags point to the generated image URL, and the template tag contains the HTML content for the OG image. Visitors do not see the template tag.

```html
<head>
    <!-- your existing head content -->
    <meta property="og:image" content="https://yourapp.com/og-image/a1b2c3d4e5f6.jpeg">
    <meta name="twitter:image" content="https://yourapp.com/og-image/a1b2c3d4e5f6.jpeg">
    <meta name="twitter:card" content="summary_large_image">
</head>
<body>
    <template data-og-image>
        <div class="...">My Post Title</div>
    </template>
</body>
```

--------------------------------

### Set Per-Component Image Size

Source: https://github.com/spatie/laravel-og-image/blob/main/docs/basic-usage/customizing-screenshots.md

Override the global image dimensions for a specific OG image component. These dimensions take precedence over the global configuration.

```blade
<x-og-image :width="800" :height="400">
    <div>This OG image will be 800×400</div>
</x-og-image>
```

--------------------------------

### Clear All Generated Images

Source: https://context7.com/spatie/laravel-og-image/llms.txt

Delete all generated OG images from disk using the artisan command.

```APIDOC
## `php artisan og-image:clear` — Clear all generated images

Delete every generated OG image from disk. Images are regenerated on the next crawler request (or the next `og-image:generate` call).

```bash
php artisan og-image:clear
# All files removed from storage/og-images/
# Images will be regenerated on demand
```
```

--------------------------------

### Clear All Generated OG Images

Source: https://context7.com/spatie/laravel-og-image/llms.txt

Delete all generated OG images from the disk. Images will be automatically regenerated on the next crawler request or when `og-image:generate` is called.

```bash
php artisan og-image:clear
# All files removed from storage/og-images/
# Images will be regenerated on demand
```

--------------------------------

### Custom OG Image Dimensions

Source: https://github.com/spatie/laravel-og-image/blob/main/resources/boost/skills/laravel-og-image/SKILL.md

Override the default OG image dimensions (1200x630) by specifying `:width` and `:height` attributes on the `<x-og-image>` component.

```blade
<x-og-image :width="800" :height="400">
    <div>This OG image will be 800x400</div>
</x-og-image>
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.