Skip to content

Latest commit

 

History

History
554 lines (429 loc) · 13.3 KB

customization.md

File metadata and controls

554 lines (429 loc) · 13.3 KB
Raw

Screenshot customization

Available functions

Render

width
height
clip
quality
omitBackground

Style

assets
addAsset

Request

optimizeForSpeed waitDelay
waitForExpression
emulatedMediaType
cookies
setCookie
addCookies
extraHttpHeaders
addExtraHttpHeaders
failOnHttpStatusCodes
failOnConsoleExceptions
skipNetworkIdleEvent

Formatting

format

Render

width

Default: 800 pixels

The device screen width in pixels.

    namespace App\Controller;

    use Sensiolabs\GotenbergBundle\GotenbergScreenshotInterface;
    
    class YourController
    {
        public function yourControllerMethod(GotenbergScreenshotInterface $gotenberg): Response
        {
            return $gotenberg->html()
                ->content('twig_simple_pdf.html.twig', [
                    'my_var' => 'value'
                ])
                ->width(600)
                ->generate()
            ;
        }
    }

Tip

For more information go to Gotenberg documentations.

height

Default: 600 pixels

The device screen height in pixels.

    namespace App\Controller;

    use Sensiolabs\GotenbergBundle\GotenbergScreenshotInterface;
    
    class YourController
    {
        public function yourControllerMethod(GotenbergScreenshotInterface $gotenberg): Response
        {
            return $gotenberg->html()
                ->content('twig_simple_pdf.html.twig', [
                    'my_var' => 'value'
                ])
                ->height(600)
                ->generate()
            ;
        }
    }

Tip

For more information go to Gotenberg documentations.

clip

Default: false

Define whether to clip the screenshot according to the device dimensions.

    namespace App\Controller;

    use Sensiolabs\GotenbergBundle\GotenbergScreenshotInterface;
    
    class YourController
    {
        public function yourControllerMethod(GotenbergScreenshotInterface $gotenberg): Response
        {
            return $gotenberg->html()
                ->content('twig_simple_pdf.html.twig', [
                    'my_var' => 'value'
                ])
                ->clip()
                ->generate()
            ;
        }
    }

Tip

For more information go to Gotenberg documentations.

quality

Default: 100

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

    namespace App\Controller;

    use Sensiolabs\GotenbergBundle\Enumeration\ScreenshotFormat;
    use Sensiolabs\GotenbergBundle\GotenbergScreenshotInterface;
    
    class YourController
    {
        public function yourControllerMethod(GotenbergScreenshotInterface $gotenberg): Response
        {
            return $gotenberg->html()
                ->content('twig_simple_pdf.html.twig', [
                    'my_var' => 'value'
                ])
                ->quality(50)
                ->format(ScreenshotFormat::Jpeg)
                ->generate()
            ;
        }
    }

Tip

For more information go to Gotenberg documentations.

omitBackground

default: false

Hide the default white background and allow generating screenshots with transparency.

    namespace App\Controller;

    use Sensiolabs\GotenbergBundle\GotenbergScreenshotInterface;
    
    class YourController
    {
        public function yourControllerMethod(GotenbergScreenshotInterface $gotenberg): Response
        {
            return $gotenberg->html()
                ->content('twig_simple_pdf.html.twig', [
                    'my_var' => 'value'
                ])
                ->omitBackground()
                ->generate()
            ;
        }
    }

Request

optimizeForSpeed

default: false

Define whether to optimize image encoding for speed, not for resulting size.

    namespace App\Controller;

    use Sensiolabs\GotenbergBundle\GotenbergScreenshotInterface;
    
    class YourController
    {
        public function yourControllerMethod(GotenbergScreenshotInterface $gotenberg): Response
        {
            return $gotenberg->html()
                ->content('twig_simple_pdf.html.twig', [
                    'my_var' => 'value'
                ])
                ->optimizeForSpeed(true)
                ->generate()
            ;
        }
    }

waitDelay

default: None

When the page relies on JavaScript for rendering, and you don't have access to the page's code, you may want to wait a certain amount of time to make sure Chromium has fully rendered the page you're trying to generate.

    namespace App\Controller;

    use Sensiolabs\GotenbergBundle\GotenbergScreenshotInterface;

    class YourController
    {
        public function yourControllerMethod(GotenbergScreenshotInterface $gotenberg): Response
        {
            return $gotenberg
                ->html()
                ->waitDelay('5s')
                ->generate()
            ;
        }
    }

Tip

For more information go to Gotenberg documentations.

waitForExpression

You may also wait until a given JavaScript expression.

    namespace App\Controller;

    use Sensiolabs\GotenbergBundle\GotenbergScreenshotInterface;

    class YourController
    {
        public function yourControllerMethod(GotenbergScreenshotInterface $gotenberg): Response
        {
            return $gotenberg
                ->html()
                ->waitForExpression("window.globalVar === 'ready'")
                ->generate()
            ;
        }
    }

Tip

For more information go to Gotenberg documentations.

emulatedMediaType

default: print

Some websites have dedicated CSS rules for print. Using screen allows you to force the "standard" CSS rules.

    namespace App\Controller;

    use Sensiolabs\GotenbergBundle\Enumeration\EmulatedMediaType;
    use Sensiolabs\GotenbergBundle\GotenbergScreenshotInterface;

    class YourController
    {
        public function yourControllerMethod(GotenbergScreenshotInterface $gotenberg): Response
        {
            return $gotenberg
                ->html()
                ->emulatedMediaType(EmulatedMediaType::Screen)
                ->generate()
            ;
        }
    }

Tip

For more information go to Gotenberg documentations.

cookies

default: None

Cookies to store in the Chromium cookie jar.

    namespace App\Controller;

    use Sensiolabs\GotenbergBundle\GotenbergScreenshotInterface;

    class YourController
    {
        public function yourControllerMethod(GotenbergScreenshotInterface $gotenberg): Response
        {
            return $gotenberg
                ->html()
                ->cookies([[
                    'name' => 'my_cookie',
                    'value' => 'symfony',
                    'domain' => 'symfony.com',
                    'secure' => true,
                    'httpOnly' => true,
                    'sameSite' => 'Lax',
                ]])
                ->generate()
            ;
        }
    }

Tip

For more information go to Gotenberg documentations.

setCookie

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

    namespace App\Controller;

    use Sensiolabs\GotenbergBundle\GotenbergScreenshotInterface;

    class YourController
    {
        public function yourControllerMethod(GotenbergScreenshotInterface $gotenberg): Response
        {
            return $gotenberg
                ->html()
                ->setCookie([
                    'name' => 'my_cookie',
                    'value' => 'symfony',
                    'domain' => 'symfony.com',
                    'secure' => true,
                    'httpOnly' => true,
                    'sameSite' => 'Lax',
                ])
                ->generate()
            ;
        }
    }

addCookies

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

    namespace App\Controller;

    use Sensiolabs\GotenbergBundle\GotenbergScreenshotInterface;

    class YourController
    {
        public function yourControllerMethod(GotenbergScreenshotInterface $gotenberg): Response
        {
            return $gotenberg
                ->html()
                ->addCookies([[
                    'name' => 'my_cookie',
                    'value' => 'symfony',
                    'domain' => 'symfony.com',
                    'secure' => true,
                    'httpOnly' => true,
                    'sameSite' => 'Lax',
                ]])
                ->generate()
            ;
        }
    }

extraHttpHeaders

default: None

HTTP headers to send by Chromium while loading the HTML document.

    namespace App\Controller;

    use Sensiolabs\GotenbergBundle\GotenbergScreenshotInterface;

    class YourController
    {
        public function yourControllerMethod(GotenbergScreenshotInterface $gotenberg): Response
        {
            return $gotenberg
                ->html()
                ->extraHttpHeaders([
                    'MyHeader' => 'MyValue'
                ])
                ->generate()
            ;
        }
    }

Tip

For more information go to Gotenberg documentations.

addExtraHttpHeaders

default: None

If you want to add headers from the ones already loaded in the configuration.

    namespace App\Controller;

    use Sensiolabs\GotenbergBundle\GotenbergScreenshotInterface;

    class YourController
    {
        public function yourControllerMethod(GotenbergScreenshotInterface $gotenberg): Response
        {
            return $gotenberg
                ->html()
                ->addExtraHttpHeaders([
                    'MyHeader' => 'MyValue'
                ])
                ->generate()
            ;
        }
    }

failOnHttpStatusCodes

default: [499,599]

To return a 409 Conflict response if the HTTP status code from the main page is not acceptable.

    namespace App\Controller;

    use Sensiolabs\GotenbergBundle\GotenbergScreenshotInterface;

    class YourController
    {
        public function yourControllerMethod(GotenbergScreenshotInterface $gotenberg): Response
        {
            return $gotenberg
                ->html()
                ->failOnHttpStatusCodes([401, 403])
                ->generate()
            ;
        }
    }

Tip

For more information go to Gotenberg documentations.

failOnConsoleExceptions

default: false

Return a 409 Conflict response if there are exceptions in the Chromium console.

    namespace App\Controller;

    use Sensiolabs\GotenbergBundle\GotenbergScreenshotInterface;

    class YourController
    {
        public function yourControllerMethod(GotenbergScreenshotInterface $gotenberg): Response
        {
            return $gotenberg
                ->html()
                ->failOnConsoleExceptions()
                ->generate()
            ;
        }
    }

Tip

For more information go to Gotenberg documentations.

skipNetworkIdleEvent

default: false

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.

    namespace App\Controller;

    use Sensiolabs\GotenbergBundle\GotenbergScreenshotInterface;

    class YourController
    {
        public function yourControllerMethod(GotenbergScreenshotInterface $gotenberg): Response
        {
            return $gotenberg
                ->html()
                ->skipNetworkIdleEvent()
                ->generate()
            ;
        }
    }

Tip

For more information go to Gotenberg documentations.

Formatting

format

default: png

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

    namespace App\Controller;

    use Sensiolabs\GotenbergBundle\Enumeration\ScreenshotFormat;
    use Sensiolabs\GotenbergBundle\GotenbergScreenshotInterface;

    class YourController
    {
        public function yourControllerMethod(GotenbergScreenshotInterface $gotenberg): Response
        {
            return $gotenberg
                ->html()
                ->format(ScreenshotFormat::Webp)
                ->generate()
            ;
        }
    }

Tip

For more information go to Gotenberg documentations.