Custom drivers | laravel-screenshot | Spatie

 SPATIE

  Laravel Screenshot
=====================

spatie.be/open-source

  [Docs](https://spatie.be/docs)  [Laravel-screenshot](https://spatie.be/docs/laravel-screenshot/v1)  Drivers  Custom drivers

 Version   v1

 Other versions for crawler [v1](https://spatie.be/docs/laravel-screenshot/v1)

- [ Introduction ](https://spatie.be/docs/laravel-screenshot/v1/introduction)
- [ Support us ](https://spatie.be/docs/laravel-screenshot/v1/support-us)
- [ Requirements ](https://spatie.be/docs/laravel-screenshot/v1/requirements)
- [ Installation & setup ](https://spatie.be/docs/laravel-screenshot/v1/installation-setup)
- [ Questions and issues ](https://spatie.be/docs/laravel-screenshot/v1/questions-issues)
- [ Changelog ](https://spatie.be/docs/laravel-screenshot/v1/changelog)
- [ About us ](https://spatie.be/docs/laravel-screenshot/v1/about-us)

Basic usage
-----------

- [ Taking screenshots ](https://spatie.be/docs/laravel-screenshot/v1/basic-usage/taking-screenshots)
- [ Customizing screenshots ](https://spatie.be/docs/laravel-screenshot/v1/basic-usage/customizing-screenshots)
- [ Saving screenshots to disks ](https://spatie.be/docs/laravel-screenshot/v1/basic-usage/saving-screenshots-to-disks)
- [ Queued screenshot generation ](https://spatie.be/docs/laravel-screenshot/v1/basic-usage/queued-screenshot-generation)
- [ Testing screenshots ](https://spatie.be/docs/laravel-screenshot/v1/basic-usage/testing-screenshots)

Drivers
-------

- [ Configuration ](https://spatie.be/docs/laravel-screenshot/v1/drivers/configuration)
- [ Customizing Browsershot ](https://spatie.be/docs/laravel-screenshot/v1/drivers/customizing-browsershot)
- [ Using the Cloudflare driver ](https://spatie.be/docs/laravel-screenshot/v1/drivers/using-the-cloudflare-driver)
- [ Custom drivers ](https://spatie.be/docs/laravel-screenshot/v1/drivers/custom-drivers)

Advanced usage
--------------

- [ Extending with macros ](https://spatie.be/docs/laravel-screenshot/v1/advanced-usage/extending-with-macros)

 Custom drivers
==============

###  On this page

1. [ Creating a driver ](#content-creating-a-driver)
2. [ Registering the driver ](#content-registering-the-driver)
3. [ Using the driver ](#content-using-the-driver)

You can create custom screenshot drivers by implementing the `ScreenshotDriver` interface.

Creating a driver
-----------------------------------------------------------------------------------------------------------

A screenshot driver must implement two methods:

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

class PlaywrightDriver implements ScreenshotDriver
{
    public function __construct(protected array $config = [])
    {
        // ...
    }

    public function generateScreenshot(
        string $input,
        bool $isHtml,
        ScreenshotOptions $options
    ): string {
        // Take the screenshot and return raw image bytes
    }

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

The `$input` parameter is either a URL or an HTML string, depending on the value of `$isHtml`.

The `ScreenshotOptions` object contains all the rendering options:

- `$options->width` — viewport width
- `$options->height` — viewport height
- `$options->type` — `ImageType` enum (Png, Jpeg, Webp)
- `$options->quality` — image quality (0-100, for JPEG/WebP)
- `$options->fullPage` — whether to capture the full scrollable page
- `$options->selector` — CSS selector to capture
- `$options->clip` — clip region (`['x' => int, 'y' => int, 'width' => int, 'height' => int]`)
- `$options->deviceScaleFactor` — device pixel ratio
- `$options->omitBackground` — whether to omit the background
- `$options->waitForTimeout` — milliseconds to wait
- `$options->waitForSelector` — CSS selector to wait for
- `$options->waitUntil` — network event to wait for

Registering the driver
--------------------------------------------------------------------------------------------------------------------------

Register your driver as a singleton in a service provider:

```
use App\Screenshots\PlaywrightDriver;

// in a service provider

$this->app->singleton('laravel-screenshot.driver.playwright', function () {
    return new PlaywrightDriver(config('laravel-screenshot.playwright', []));
});
```

Using the driver
--------------------------------------------------------------------------------------------------------

Once registered, you can use it per-screenshot:

```
use Spatie\LaravelScreenshot\Facades\Screenshot;

Screenshot::url('https://example.com')
    ->driver('playwright')
    ->save('screenshot.png');
```

Or set it as the default in your config file:

```
// config/laravel-screenshot.php

'driver' => 'playwright',
```