UrlScreenshotBuilder

You may have the possibility to generate a screenshot from a URL.

Basic usage

url

URL of the page you want to convert into screenshot.

namespace App\Controller;

use Sensiolabs\GotenbergBundle\GotenbergScreenshotInterface;

class YourController
{
    public function yourControllerMethod(GotenbergScreenshotInterface $gotenberg): Response
    {
        return $gotenberg->url()
            ->url('https://sensiolabs.com/fr/')
            ->generate()
            ->stream()
         ;
    }
}

route

Route of the page you want to convert into screenshot.

# config/packages/sensiolabs_gotenberg.yaml
sensiolabs_gotenberg:
  request_context:
      base_uri: 'http://host.docker.internal:3000'

namespace App\Controller;

use Sensiolabs\GotenbergBundle\GotenbergScreenshotInterface;

class YourController
{
    public function yourControllerMethod(GotenbergScreenshotInterface $gotenberg): Response
    {
        return $gotenberg->url()
            ->route('home', [
                'my_var' => 'value'
            ])
            ->generate()
            ->stream()
        ;
    }
}

Customization

Available methods

• downloadFrom
• route
• url
• addAsset
• assets
• addWebhookExtraHeaders
• webhook
• webhookConfiguration
• webhookErrorRoute
• webhookErrorUrl
• webhookEventsRoute
• webhookEventsUrl
• webhookExtraHeaders
• webhookRoute
• webhookUrl
• addCookies
• cookies
• forwardCookie
• setCookie
• clip
• format
• height
• omitBackground
• optimizeForSpeed
• quality
• width
• waitDelay
• waitForExpression
• waitForSelector
• content
• contentFile
• contentRaw
• footer
• footerFile
• footerRaw
• header
• headerFile
• headerRaw
• emulatedMediaFeatures
• failOnConsoleExceptions
• failOnHttpStatusCodes
• failOnResourceHttpStatusCodes
• failOnResourceLoadingFailed
• ignoreResourceHttpStatusDomains
• addExtraHttpHeaders
• extraHttpHeaders
• userAgent
• emulatedMediaType
• skipNetworkAlmostIdleEvent
• skipNetworkIdleEvent

downloadFrom(array $downloadFrom)

Sets download from to download each entry (file) in parallel (URLs MUST return a Content-Disposition header with a filename parameter.).

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->downloadFrom([['url' => 'http://example.com/url/to/file', 'extraHttpHeaders' => ['MyHeader' => 'MyValue']], ['url' => 'http://example.com/url/to/file', 'extraHttpHeaders' => ['MyHeaderOne' => 'MyValue', 'MyHeaderTwo' => 'MyValue']]])
    ->generate()
    ->stream()
;

route(string $name, array $parameters)

Route of the page you want to convert into PDF.

You must provide a URL accessible by Gotenberg with a public Host.
Or configure request_context.base_uri in sensiolabs_gotenberg.yaml

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->route('home', ['my_var' => 'value'])
    ->generate()
    ->stream()
;

url(string $url)

URL of the page you want to convert into a screenshot.

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->url('https://sensiolabs.com/fr/')
    ->generate()
    ->stream()
;

addAsset(Stringable|string $path)

Adds a file, like an image, font, stylesheet, and so on.

By default, the assets files are fetch in the assets folder of your application.
If your assets are in another folder, you can override the default value of assets_directory in your
configuration file config/sensiolabs_gotenberg.yml.

assets(Stringable|string ...$paths)

Adds additional files, like images, fonts, stylesheets, and so on (overrides any previous files).

By default, the assets files are fetch in the assets folder of your application.
If your assets are in another folder, you can override the default value of assets_directory in your
configuration file config/sensiolabs_gotenberg.yml.

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->assets('../img/ceo.jpeg', __DIR__'/../../public/admin.jpeg')
    ->generate()
    ->stream()
;

addWebhookExtraHeaders(array $extraHttpHeaders)

Adds extra headers to the ones already provided to the webhook endpoint, preserving previously set values.

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->addWebhookExtraHeaders(['X-Custom-Header' => 'CustomValue'])
    ->generate()
    ->stream()
;

webhook(array $webhook)

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->webhook(['config_name' => 'my_config', 'success' => ['url' => 'https://my.webhook.url/success', 'method' => 'POST'], 'error' => ['route' => 'my_route_error', 'method' => 'POST'], 'events' => ['url' => 'https://my.webhook.url/events']])
    ->generate()
    ->stream()
;

webhookConfiguration(string $name)

Providing an existing $name from the configuration file, it will correctly set both success and error webhook URLs as well as extra_http_headers if defined.

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->webhookConfiguration('my_webhook_config')
    ->generate()
    ->stream()
;

webhookErrorRoute(string $route, array $parameters, ?string $method)

Sets the webhook route with params and method for cases of error.

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->webhookErrorRoute('my_route_error', ['foo' => 'bar'], 'PUT')
    ->generate()
    ->stream()
;

webhookErrorUrl(string $url, ?string $method)

Sets the webhook for cases of success.
Optionally sets a custom HTTP method for such endpoint among : POST, PUT or PATCH.

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->webhookErrorUrl('https://my.webhook.url', 'PUT')
    ->generate()
    ->stream()
;

webhookEventsRoute(string $route, array $parameters)

Sets the webhook route with params for event callbacks.

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->webhookEventsRoute('my_route_events', ['foo' => 'bar'])
    ->generate()
    ->stream()
;

webhookEventsUrl(string $url)

Sets the URL that will receive structured JSON event callbacks after each webhook operation.
When set, POST requests are sent with event type (webhook.success or webhook.error), correlationId, and timestamp.

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->webhookEventsUrl('https://my.webhook.url/events')
    ->generate()
    ->stream()
;

webhookExtraHeaders(array $extraHttpHeaders)

Extra headers that will be provided to the webhook endpoint. May it either be Success or Error.

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->webhookExtraHeaders(['Authorization' => 'Bearer my-secret-token','X-Custom-Header' => 'CustomValue'])
    ->generate()
    ->stream()
;

webhookRoute(string $route, array $parameters, ?string $method)

Sets the webhook route with params and method for cases of success.

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->webhookRoute('my_route_success', ['foo' => 'bar'], 'PUT')
    ->generate()
    ->stream()
;

webhookUrl(string $url, ?string $method)

Sets the webhook for cases of success.
Optionally sets a custom HTTP method for such endpoint among : POST, PUT or PATCH.

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->webhookUrl('https://my.webhook.url', 'PUT')
    ->generate()
    ->stream()
;

addCookies(array $cookies)

Add cookies to store in the Chromium cookie jar.

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->addCookies([['name' => 'my_cookie','value' => 'symfony','domain' => 'symfony.com','secure' => true,'httpOnly' => true,'sameSite' => 'Lax']])
    ->generate()
    ->stream()
;

cookies(array $cookies)

Cookies to store in the Chromium cookie jar.

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->cookies([[ 'name' => 'my_cookie', 'value' => 'symfony', 'domain' => 'symfony.com', 'secure' => true, 'httpOnly' => true, 'sameSite' => 'Lax']])
    ->generate()
    ->stream()
;

forwardCookie(string $name)

If you want to forward cookies from the current request.

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->forwardCookie('my_cookie')
    ->generate()
    ->stream()
;

setCookie(string $name, Symfony\Component\HttpFoundation\Cookie|array $cookie)

If you want to add cookies and delete the ones already loaded in the configuration .

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->setCookie([ 'name' => 'my_cookie', 'value' => 'symfony', 'domain' => 'symfony.com', 'secure' => true, 'httpOnly' => true, 'sameSite' => 'Lax'])
    ->generate()
    ->stream()
;

clip(bool $bool)

Define whether to clip the screenshot according to the device dimensions. (Default false).

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->clip() // is same as `->clip(true)`
    ->generate()
    ->stream()
;

format(Sensiolabs\GotenbergBundle\Enumeration\ScreenshotFormat $format)

The image compression format, either "png", "jpeg" or "webp". (default png).

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->format(ScreenshotFormat::Webp)
    ->generate()
    ->stream()
;

height(int $height)

The device screen width in pixels. (Default 600).

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->height(600)
    ->generate()
    ->stream()
;

omitBackground(bool $bool)

Hides default white background and allows generating screenshot with transparency.

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->omitBackground() // is same as `->omitBackground(true)`
    ->generate()
    ->stream()
;

optimizeForSpeed(bool $bool)

Define whether to optimize image encoding for speed, not for resulting size. (Default false).

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->optimizeForSpeed() // is same as `->optimizeForSpeed(true)`
    ->generate()
    ->stream()
;

quality(int $quality)

The compression quality from range 0 to 100 (jpeg only). (default 100).

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->quality(50)
    ->generate()
    ->stream()
;

width(int $width)

The device screen width in pixels. (Default 800).

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->width(600)
    ->generate()
    ->stream()
;

waitDelay(string $delay)

Sets the duration (i.e., "1s", "2ms", etc.) to wait when loading an HTML
document before converting it to PDF.

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->waitDelay('5s')
    ->generate()
    ->stream()
;

waitForExpression(string $expression)

Sets the JavaScript expression to wait before converting an HTML document to PDF until it returns true.

For instance: "window.status === 'ready'".

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->waitForExpression("window.globalVar === 'ready'")
    ->generate()
    ->stream()
;

waitForSelector(string $selector)

Selector (e.g. '#id') to query before converting an HTML document into PDF until it matches a node.

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->waitForSelector('#special-id')
    ->generate()
    ->stream()
;

content(string $template, array $context)

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->content('content.html.twig', ['my_var' => 'value'])
    ->generate()
    ->stream()
;

contentFile(string $path)

The HTML file to convert into PDF.

As assets files, by default the HTML files are fetch in the assets folder of your application.
If your HTML files are in another folder, you can override the default value of assets_directory in your
configuration file config/sensiolabs_gotenberg.yml.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->contentFile('../public/content.html')
    ->generate()
    ->stream()
;

contentRaw(string $html)

The raw html string to convert into PDF.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->contentRaw('<html><body><h2>The content</h2></body></html>')
    ->generate()
    ->stream()
;

footer(string $template, array $context)

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->footer('header.html.twig', ['my_var' => 'value'])
    ->generate()
    ->stream()
;

footerFile(string $path)

HTML file containing the footer.

As assets files, by default the HTML files are fetch in the assets folder of your application.
If your HTML files are in another folder, you can override the default value of assets_directory in your
configuration file config/sensiolabs_gotenberg.yml.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->footerFile('../templates/html/footer.html')
    ->generate()
    ->stream()
;

footerRaw(string $html)

The raw html string to convert into PDF.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->footerRaw('<html><body><h6>The footer</h6></body></html>')
    ->generate()
    ->stream()
;

header(string $template, array $context)

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->header('header.html.twig', ['my_var' => 'value'])
    ->generate()
    ->stream()
;

headerFile(string $path)

HTML file containing the header.

As assets files, by default the HTML files are fetch in the assets folder of your application.
If your HTML files are in another folder, you can override the default value of assets_directory in your
configuration file config/sensiolabs_gotenberg.yml.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->headerFile('../templates/html/header.html')
    ->generate()
    ->stream()
;

headerRaw(string $html)

The raw html string to convert into PDF.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->headerRaw('<html><body><h1>The header</h1></body></html>')
    ->generate()
    ->stream()
;

emulatedMediaFeatures(array $emulatedMediaFeatures)

You can simulate specific browser conditions by overriding CSS media features.
This is particularly useful for forcing "Dark Mode" or testing layouts with reduced motion.

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->emulatedMediaFeatures([['name' => 'prefers-color-scheme', 'value' => 'dark'], ['name' => 'prefers-reduced-motion', 'value' => 'reduce'])
    ->generate()
    ->stream()
;

failOnConsoleExceptions(bool $bool)

Forces GotenbergPdf to return a 409 Conflict response if there are
exceptions in the Chromium console. (default false).

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->failOnConsoleExceptions() // is same as `->failOnConsoleExceptions(true)`
    ->generate()
    ->stream()
;

failOnHttpStatusCodes(array $statusCodes)

Return a 409 Conflict response if the HTTP status code from
the main page is not acceptable. (default [499,599]). (overrides any previous configuration).

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->failOnHttpStatusCodes([401, 403])
    ->generate()
    ->stream()
;

failOnResourceHttpStatusCodes(array $statusCodes)

Return a 409 Conflict response if the HTTP status code from at least one resource is not acceptable. (overrides any previous configuration).

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->failOnResourceHttpStatusCodes([401, 403])
    ->generate()
    ->stream()
;

failOnResourceLoadingFailed(bool $bool)

Forces GotenbergPdf to return a 409 Conflict response if Chromium fails to load at least one resource.
(default false).

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->failOnResourceLoadingFailed() // is same as `->failOnResourceLoadingFailed(true)`
    ->generate()
    ->stream()
;

ignoreResourceHttpStatusDomains(array $domains)

Exclude resources from failOnResourceHttpStatusCodes checks based on their hostname.

The ignoreResourceHttpStatusDomains option allows you to exclude specific domains from the resource HTTP status
code checks. A match happens if the hostname equals the domain or is a subdomain of it
(e.g., browser.sentry-cdn.com matches sentry-cdn.com).

Values are normalized (trimmed, lowercased) and may be provided as:

example.com
.example.com or .example.com
example.com:443 (port is ignored)
https://example.com/path (scheme/path are ignored)

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->ignoreResourceHttpStatusDomains(['sentry-cdn.com', 'analytics.example.com'])
    ->generate()
    ->stream()
;

addExtraHttpHeaders(array $headers)

Adds extra HTTP headers that Chromium will send when loading the HTML document.

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->addExtraHttpHeaders(['MyHeader' => 'MyValue'])
    ->generate()
    ->stream()
;

extraHttpHeaders(array $headers)

Sets extra HTTP headers that Chromium will send when loading the HTML document. (overrides any previous headers).

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->extraHttpHeaders(['MyHeader' => 'MyValue'])
    ->generate()
    ->stream()
;

userAgent(string $userAgent)

Override the default User-Agent HTTP header.

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->userAgent(UserAgent::AndroidChrome)
    ->generate()
    ->stream()
;

emulatedMediaType(Sensiolabs\GotenbergBundle\Enumeration\EmulatedMediaType $mediaType)

Forces Chromium to emulate, either "screen" or "print". (default "print").

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->emulatedMediaType(EmulatedMediaType::Screen)
    ->generate()
    ->stream()
;

skipNetworkAlmostIdleEvent(bool $bool)

Does not wait for Chromium network to be almost idle (at most 2 open connections for 500ms) before conversion.
Useful for pages with long-polling or analytics connections. (default true).

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->skipNetworkAlmostIdleEvent() // is same as `->skipNetworkAlmostIdleEvent(true)`
    ->generate()
    ->stream()
;

skipNetworkIdleEvent(bool $bool)

Gotenberg, by default, waits for the network idle event to ensure that the majority of the page is rendered during
conversion. However, this often significantly slows down the conversion process. Setting this form field to true
can greatly enhance the conversion speed.

return $gotenberg
    // Your builder call as ->html() and the rest of your configuration code
    ->skipNetworkIdleEvent() // is same as `->skipNetworkIdleEvent(true)`
    ->generate()
    ->stream()
;