Browsershot

https://github.com/spatie/browsershot
Admin
Browsershot is a PHP package that converts web pages to images or PDFs using headless Chrome and...
Tokens:11,120
Snippets:207
Trust Score:10
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install Image Manipulation Dependency

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-images.md

To use image manipulation features, install the spatie/image package version 3 or higher.

```bash
composer require spatie/image
```

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

### Install Puppeteer on MacOS globally

Source: https://github.com/spatie/browsershot/blob/main/docs/requirements.md

Install Puppeteer globally on your system.

```bash
npm install puppeteer --location=global
```

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

### Equivalent to Device Emulation

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-images.md

This example shows the equivalent configuration to emulating an 'iPhone X' using individual methods.

```php
Browsershot::url('https://example.com')
    ->userAgent('Mozilla/5.0 (iPhone; CPU iPhone OS 11_0 like Mac OS X) AppleWebKit/604.1.38 (KHTML, like Gecko) Version/11.0 Mobile/15A372 Safari/604.1')
    ->windowSize(375, 812)
    ->deviceScaleFactor(3)
    ->mobile()
    ->touch()
    ->landscape(false)
    ->save($pathToImage);
```

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

### Install Browsershot with Composer

Source: https://github.com/spatie/browsershot/blob/main/docs/installation-setup.md

Use this command to add Browsershot to your project's dependencies.

```bash
composer require spatie/browsershot
```

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

### Install Puppeteer on Forge provisioned Ubuntu server

Source: https://github.com/spatie/browsershot/blob/main/docs/requirements.md

Commands to verify environment, install Puppeteer and Chromium, and configure AppArmor for Ubuntu v24.04.

```bash
# Check if node and npm are installed
node -v && npm -v

# Install puppeteer
sudo npm install -g puppeteer

# Install chromium
npx puppeteer browsers install chrome

# Install dependencies
sudo apt update
sudo apt install libasound2t64 libatk1.0-0 libatk-bridge2.0-0 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgbm1 libgcc1 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6

# You may get an error: "No usable sandbox! If you are running on Ubuntu 23.10+ or another Linux distro that has disabled unprivileged user namespaces with AppArmor"
# You can fix this by editing /etc/sysctl.conf and add these lines to the end of the file
kernel.apparmor_restrict_unprivileged_userns=0
kernel.apparmor_restrict_unprivileged_unconfined=0
```

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

### Run Tests

Source: https://github.com/spatie/browsershot/blob/main/README.md

Execute the package's test suite. Requires Puppeteer and poppler-utils to be installed.

```bash
composer test
```

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

### Install Puppeteer on MacOS via NPM

Source: https://github.com/spatie/browsershot/blob/main/docs/requirements.md

Install Puppeteer locally in your project using NPM.

```bash
npm install puppeteer
```

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

### Pass font rendering arguments to Chromium

Source: https://github.com/spatie/browsershot/blob/main/docs/requirements.md

Example of passing a specific flag to fix font rendering issues.

```php
Browsershot::html('Foo')
  ->addChromiumArguments([
      'font-render-hinting' => 'none',
  ]);
```

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

### Set Arbitrary Option with setOption

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/setting-an-arbirary-option.md

Use `setOption` to pass any arbitrary option to Browsershot. This example sets the 'landscape' option to true.

```php
Browsershot::url('https://example.com')
   ->setOption('landscape', true)
   ->save($pathToImage);
```

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

### Disable Sandboxing

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/disable-sandboxing.md

Use the `noSandbox()` method when running Browsershot in Linux environments that require sandboxing to be disabled. This is often needed in certain virtualization setups.

```php
Browsershot::url('https://example.com')
   ->noSandbox()
   ...
```

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

### Get Screenshot as Base64 Data

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-images.md

Retrieve the screenshot directly as a base64 encoded string, useful when disk storage is not desired.

```php
$base64Data = Browsershot::url('https://example.com')
    ->base64Screenshot();
```

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

### Get Triggered Requests

Source: https://github.com/spatie/browsershot/blob/main/docs/introduction.md

Obtain a list of all requests triggered by a webpage after it has loaded and executed JavaScript. Each request is returned as an associative array.

```php
$requests = Browsershot::url('https://example.com')
    ->triggeredRequests();

foreach ($requests as $request) {
    $url = $request['url']; //https://example.com/
}
```

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

### Get Triggered Requests

Source: https://github.com/spatie/browsershot/blob/main/README.md

Retrieve a list of all requests triggered by the page after it has loaded and executed JavaScript. Each request is an associative array.

```php
$requests = Browsershot::url('https://example.com')
    ->triggeredRequests();

foreach ($requests as $request) {
    $url = $request['url']; //https://example.com/
}
```

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

### Get Failed Requests in PHP

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/getting-failed-requests.md

Call `failedRequests()` after loading a URL to get an array of failed requests. Each item in the array contains the 'status' and 'url' of the failed resource, such as a broken image.

```php
$consoleMessages = Browsershot::url('https://example.com')->failedRequests(); // returns an array
```

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

### Set custom chrome or chromium executable path

Source: https://github.com/spatie/browsershot/blob/main/docs/requirements.md

Point Browsershot to a specific chrome or chromium executable instead of the one installed by Puppeteer.

```php
Browsershot::html('Foo')
  ->setChromePath("/path/to/my/chrome")
```

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

### Set Initial PDF Page Number

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-pdfs.md

Define the starting page number for the PDF using the `initialPageNumber` method. This is useful when customizing headers/footers with page numbers.

```php
Browsershot::html($someHtml)
   ->showBrowserHeaderAndFooter()
   ->hideFooter()
   ->headerHtml('<span class="pageNumber"></span>')
   ->initialPageNumber(8)
   ->save('example.pdf');
```

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

### Get Redirect History with Browsershot

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/read-redirect-history.md

Use this snippet to retrieve the redirect history for a given URL. It iterates through the history, printing details like URL, status, reason, and headers for each redirect.

```php
$redirects = Browsershot::url('https://www.spatie.be')
    ->redirectHistory();

foreach ($redirects as $redirect) {
    print $redirect['url'] . PHP_EOL;
    print $redirect['status'] . PHP_EOL;
    print $redirect['reason'] . PHP_EOL;
    foreach ($redirect['headers'] as $name => $value) {
      print $name . ' : ' . $value . PHP_EOL;
    }
    print PHP_EOL;
}
```

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

### Get Body HTML After JavaScript Execution

Source: https://github.com/spatie/browsershot/blob/main/README.md

Retrieve the HTML content of the page's body after JavaScript has been executed. Useful for dynamic content.

```php
Browsershot::url('https://example.com')->bodyHtml(); // returns the html of the body
```

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

### Get PDF as Base64 Data

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-pdfs.md

Obtain the PDF content as a base64 encoded string using the `base64pdf` method. Useful for environments where saving files is restricted.

```php
$base64Data = Browsershot::url('https://example.com')
    ->base64pdf();
```

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

### Getting Console Output

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/getting-console-ouput.md

This endpoint allows you to retrieve all console messages generated by Chrome. The `consoleMessages` method returns an array, where each element contains details about a console message.

```APIDOC
## GET /consoleMessages

### Description
Retrieves all console messages (logs, errors, etc.) from the browser.

### Method
GET

### Endpoint
This is a method call within the Browsershot library, not a direct HTTP endpoint.

### Parameters
None

### Request Example
```php
$consoleMessages = Browsershot::url('https://example.com')->consoleMessages();
```

### Response
#### Success Response (200)
- **consoleMessages** (array) - An array of console message objects.

Each object in the `consoleMessages` array has the following keys:
- **type** (string) - The type of console output (e.g., 'log', 'error').
- **message** (string) - The content of the console message.
- **location** (array) - Information about where the message was triggered, often containing a 'url' key.

#### Response Example
```json
[
  {
    "type": "log",
    "message": "Page loaded successfully.",
    "location": {
      "url": "https://example.com",
      "lineNumber": 10,
      "columnNumber": 5
    }
  },
  {
    "type": "error",
    "message": "Uncaught TypeError: Cannot read property 'name' of undefined",
    "location": {
      "url": "https://example.com",
      "lineNumber": 55,
      "columnNumber": 12
    }
  }
]
```
```

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

### Export Specific PDF Pages

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-pdfs.md

Control which pages are included in the PDF export by providing a print range string to the `pages` method. Examples: '1', '1-3', '1-5, 8, 11-13'.

```php
Browsershot::html($someHtml)
   ->pages('1-5, 8, 11-13')
   ->save('example.pdf');
```

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

### Get HTML Body After JavaScript Execution

Source: https://github.com/spatie/browsershot/blob/main/docs/introduction.md

Retrieve the HTML content of the page's body after JavaScript has been executed. This is useful for dynamic content.

```php
Browsershot::url('https://example.com')->bodyHtml(); // returns the html of the body
```

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

### Get Chrome Console Output

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/getting-console-ouput.md

Call the `consoleMessages` method on a Browsershot instance to retrieve an array of console messages. Each message object contains its type, the message content, and location details.

```php
$consoleMessages = Browsershot::url('https://example.com')->consoleMessages(); // returns an array
```

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

### Create a Basic Screenshot

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-images.md

Use this method for a simple screenshot of a given URL. The output format defaults to PNG.

```php
Browsershot::url('https://example.com')->save($pathToImage);
```

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

### Set custom node and npm binary paths

Source: https://github.com/spatie/browsershot/blob/main/docs/requirements.md

Manually specify the paths to the node and npm binaries if they are not automatically detected.

```php
Browsershot::html('Foo')
    ->setNodeBinary('/usr/local/bin/node')
    ->setNpmBinary('/usr/local/bin/npm');
```

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

### Set custom binary path

Source: https://github.com/spatie/browsershot/blob/main/docs/requirements.md

Use an alternative script source by setting the binary path.

```php
Browsershot::html('Foo')
  ->setBinPath("/path/to/my/project/my_script.js")
```

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

### Emulate a Specific Device

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-images.md

Use the `device()` method to emulate a specific device, such as 'iPhone X'. This sets appropriate user agent, window size, scale factor, and other properties.

```php
$browsershot = new Browsershot('https://example.com', true);
$browsershot
        ->device('iPhone X')
        ->save($pathToImage);
```

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

### Emulate CSS Media Type for PDF Generation

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/setting-the-css-media-type-of-the-page.md

Use emulateMedia('screen') to render the page as if it were a screen, which is useful for PDF generation to emulate the print version. Pass null to disable emulation.

```php
Browsershot::url('https://example.com')
    ->emulateMedia('screen') // "screen", "print" (default) or null (passing null disables the emulation).
    ->savePdf($pathToPdf);
```

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

### Submit a form by typing and clicking

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/typing-on-the-page.md

Combine `type` and `click` methods to simulate a user filling out a form and submitting it. Use `delay` to wait for any client-side processing before saving the screenshot.

```php
Browsershot::url('https://example.com')
    ->type('#firstName', 'My name')
    ->click('#submit')
    ->delay($millisecondsToWait)
    ->save($pathToImage);
```

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

### Emulate Mobile View and Touch

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-images.md

Configure the browser to emulate a mobile device, including touch functionality, and set a custom user agent.

```php
Browsershot::url('https://example.com')
    ->userAgent('My Mobile Browser 1.0')
    ->mobile()
    ->touch()
    ->save($pathToImage);
```

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

### Save Webpage as PDF

Source: https://github.com/spatie/browsershot/blob/main/docs/introduction.md

This snippet demonstrates how to save a webpage as a PDF file by specifying a '.pdf' extension in the save path.

```php
// a pdf will be saved
Browsershot::url('https://example.com')->save('example.pdf');
```

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

### Submit Form and Take Screenshot

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/changing-the-value-of-a-dropdown.md

Combine `type`, `selectOption`, `click`, and `delay` to automate form submissions and capture a screenshot of the resulting page. Ensure to include a delay if necessary for dynamic content loading.

```php
Browsershot::url('https://example.com')
    ->type('#firstName', 'My name')
    ->selectOption('#state', 'MT')
    ->click('#submit')
    ->delay($millisecondsToWait)
    ->save($pathToImage);
```

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

### Set Custom Window Size

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-images.md

Define a specific resolution for the screenshot by setting the window width and height.

```php
Browsershot::url('https://example.com')
    ->windowSize(640, 480)
    ->save($pathToImage);
```

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

### Apply Image Manipulation (Greyscale)

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-images.md

Perform image manipulations like converting to greyscale after capturing the screenshot. Requires the spatie/image package.

```php
Browsershot::url('https://example.com')
    ->windowSize(640, 480)
    ->greyscale()
    ->save($pathToImage);
```

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

### Set custom include path

Source: https://github.com/spatie/browsershot/blob/main/docs/requirements.md

Modify the system include path to help Browsershot locate node and npm.

```php
Browsershot::html('Foo')
    ->setIncludePath('$PATH:/usr/local/bin')
```

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

### Provide HTTP Authentication Credentials

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/using-http-authentication.md

Use the `authenticate` method to supply a username and password for HTTP authentication when requesting a URL. Ensure the URL requires authentication.

```php
Browsershot::url('https://example.com')
    ->authenticate('username', 'password')
   ...
```

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

### Save URL to PDF

Source: https://github.com/spatie/browsershot/blob/main/README.md

Use this to save a web page as a PDF. The file path must have a .pdf extension.

```php
// a pdf will be saved
Browsershot::url('https://example.com')->save('example.pdf');
```

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

### Set Proxy Server for Browsershot

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/specifying-a-proxy-server.md

Use `setProxyServer` to specify a proxy for Chromium. The argument is passed to the `--proxy-server=` option. Ensure the proxy format is correct.

```php
Browsershot::url('https://example.com')
   ->setProxyServer("1.2.3.4:8080")
   ...
```

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

### Set Browser Language Environment

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/changing-the-language-of-the-browser.md

Use setEnvironmentOptions to specify the browser's language, such as 'en-GB', for loading a page.

```php
Browsershot::url('https://example.com')
   ->setEnvironmentOptions([
      'LANG' => 'en-GB',
   ])
   ...
```

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

### Show Browser Header and Footer

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-pdfs.md

Enable the display of browser-generated headers and footers in the PDF. Custom HTML templates can be provided for both.

```php
Browsershot::html($someHtml)
   ->showBrowserHeaderAndFooter()
   ->headerHtml($someHtml)
   ->footerHtml($someHtml)
   ->save('example.pdf');
```

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

### Import Browsershot Namespace

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/introduction.md

Ensure this namespace is imported at the top of your file to use Browsershot functionalities.

```php
use Spatie\Browsershot\Browsershot;
```

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

### Set User Data Directory

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-images.md

Use `userDataDir()` to specify a directory for browser session data. This can improve performance but requires an absolute path and may cause cache issues.

```php
$image = Browsershot::url('https://example.com')
    ->userDataDir('/tmp/session-1')
    ->screenshot()
```

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

### Convert HTML File to PDF

Source: https://github.com/spatie/browsershot/blob/main/README.md

Use this to convert the content of a local HTML file into a PDF. Ensure the file path has a .pdf extension.

```php
Browsershot::htmlFromFilePath('/local/path/to/file.html')->save('example.pdf');
```

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

### Set Device Scale Factor

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-images.md

Capture the webpage at a higher pixel density, simulating retina or xhdpi displays by setting a scale factor (e.g., 2 or 3).

```php
Browsershot::url('https://example.com')
    ->deviceScaleFactor(2)
    ->save($pathToImage);
```

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

### Enable New Headless Mode

Source: https://github.com/spatie/browsershot/blob/main/README.md

Enable Chrome's new headless mode for rendering. This can be combined with saving to an image or PDF.

```php
Browsershot::url('https://example.com')->newHeadless()->save($pathToImage);
```

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

### Use Transparent Background for PDF

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-pdfs.md

Set the PDF background to transparent instead of the default white by calling the `transparentBackground` method.

```php
Browsershot::html($someHtml)
   ->transparentBackground()
   ->save('example.pdf');
```

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

### Take a Full Page Screenshot

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-images.md

Capture the entire scrollable height of the webpage using the `fullPage()` method.

```php
Browsershot::url('https://example.com')
    ->fullPage()
    ->save($pathToImage);
```

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

### Convert HTML String to PDF

Source: https://github.com/spatie/browsershot/blob/main/README.md

Use this to convert an HTML string directly into a PDF. Ensure the file path has a .pdf extension.

```php
Browsershot::html('<h1>Hello world!!</h1>')->save('example.pdf');
```

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

### Set Screenshot Type and Quality

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-images.md

Change the screenshot format to JPEG and specify the quality level (0-100).

```php
Browsershot::url('https://example.com')
    ->setScreenshotType('jpeg', 100)
    ->save($pathToImage);
```

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

### Send POST Request with Browsershot

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/sending-post-requests.md

Use the `post` method to send a POST request. POST requests are sent with `application/x-www-form-urlencoded` content type by default.

```php
Browsershot::url('https://example.com')
    ->post(['foo' => 'bar'])
   ...
```

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

### Inject script before page load

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/evaluating-a-script-before-page-load.md

Use `evaluateOnNewDocument` to inject a script that runs before the page's own scripts. The argument is evaluated as a statement.

```php
Browsershot::url('https://example.com')
    ->evaluateOnNewDocument('window.myFlag = true')
    ->save($pathToImage);
```

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

### Wait for Network Idle

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-images.md

Use `waitUntilNetworkIdle()` to pause screenshot capture until there are no network connections for 500ms. This ensures all lazy-loaded resources are fetched. Set to `false` to allow up to two connections within the period.

```php
Browsershot::url('https://example.com')
    ->waitUntilNetworkIdle()
    ->save($pathToImage);
```

```php
Browsershot::url('https://example.com')
    ->waitUntilNetworkIdle(false)
    ->save($pathToImage);
```

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

### Output Screenshot Directly to Browser

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-images.md

Use the `screenshot()` method to output the image directly to the browser instead of saving it to a file.

```php
$image = Browsershot::url('https://example.com')->screenshot()
```

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

### Set Remote Chromium Instance

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/connection-to-a-remote-chrome-instance.md

Use this method to connect to a remote Chromium instance. Specify the IP and port. If the remote instance is unavailable, Browsershot will fallback to launching a local instance.

```php
Browsershot::url('https://example.com')
   ->setRemoteInstance('1.2.3.4', 9222)
   ...
```

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

### Write Browsershot Options to File

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/writing-options-to-a-file.md

Use this method when the amount of options given to Puppeteer becomes too large, causing command-line character overflows. This bypasses the limit by passing the options file to Puppeteer.

```php
Browsershot::url('https://example.com')
   ->writeOptionsToFile()
   ...
```

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

### Save Webpage as Image

Source: https://github.com/spatie/browsershot/blob/main/docs/introduction.md

Use this snippet to save a webpage as an image file. Ensure the file extension is not '.pdf'.

```php
use Spatie\Browsershot\Browsershot;

// an image will be saved
Browsershot::url('https://example.com')->save($pathToImage);
```

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

### Emulate CSS Media Features like Dark Mode

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/setting-the-css-media-type-of-the-page.md

Emulate specific media features, such as 'prefers-color-scheme' set to 'dark', to test or generate content reflecting these states.

```php
Browsershot::url('https://example.com')
    ->emulateMediaFeatures([
        ['name' => 'prefers-color-scheme', 'value' => 'dark']
    ])
    ->save($pathToImage);
```

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

### Convert URL to PDF

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/introduction.md

Use this method to convert the HTML content of a given URL into a PDF file. Specify the output file path.

```php
Browsershot::url('https://example.com')->save('example.pdf');
```

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

### Save URL to Image

Source: https://github.com/spatie/browsershot/blob/main/README.md

Use this to save a web page as an image. Ensure the file path does not have a PDF extension.

```php
use Spatie\Browsershot\Browsershot;

// an image will be saved
Browsershot::url('https://example.com')->save($pathToImage);
```

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

### Convert HTML to PDF

Source: https://github.com/spatie/browsershot/blob/main/docs/introduction.md

Convert arbitrary HTML content directly to a PDF file. Replace the `url` method with `html` for this purpose.

```php
Browsershot::html('<h1>Hello world!!</h1>')->save('example.pdf');
```

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

### Output PDF Directly to Browser

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-pdfs.md

Generate and output the PDF directly to the browser without saving it to disk, using the `pdf()` method. This is useful for immediate downloads or display.

```php
$pdf = Browsershot::url('https://example.com')->pdf()
```

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

### Set Screenshot Delay

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-images.md

Use `setDelay()` to introduce a delay before taking the screenshot. This is useful for waiting for JavaScript execution or lazy-loaded resources.

```php
Browsershot::url('https://example.com')
    ->setDelay($delayInMilliseconds)
    ->save($pathToImage);
```

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

### Set User Agent for Screenshots

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/setting-the-user-agent.md

Use the `userAgent` method to define the user agent string for the browser. This is useful for testing responsive designs or accessing content that requires a specific user agent.

```php
Browsershot::url('https://example.com')
    ->userAgent('My Special Snowflake Browser 1.0')
    ->save($pathToImage);
```

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

### Set custom node module path

Source: https://github.com/spatie/browsershot/blob/main/docs/requirements.md

Specify an alternative source for node_modules.

```php
Browsershot::html('Foo')
  ->setNodeModulePath("/path/to/my/project/node_modules/")
```

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

### Set Predefined PDF Format

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-pdfs.md

Apply a predefined paper format (e.g., 'A4', 'Letter') using the `format` method. Refer to Puppeteer documentation for available formats.

```php
Browsershot::url('https://example.com')->format('A4')->save('example.pdf');
```

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

### Include Background in PDF

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-pdfs.md

Render the background of the HTML page in the generated PDF by calling the `showBackground` method. The default is to exclude backgrounds.

```php
Browsershot::html($someHtml)
   ->showBackground()
   ->save('example.pdf');
```

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

### Set Browser Environment Variables with Browsershot

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/passing-environment-variables-to-the-browser.md

Use the `setEnvironmentOptions` method to pass custom environment variables that influence the browser instance. This is useful for setting timezones or other environment-specific configurations.

```php
Browsershot::url('https://example.com')
   ->setEnvironmentOptions(['TZ' => 'Pacific/Auckland'])
   ...
```

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

### Set custom node environment variables

Source: https://github.com/spatie/browsershot/blob/main/docs/requirements.md

Define environment variables for the node process using setNodeEnv.

```php
Browsershot::html('Foo')
    ->setNodeEnv(['NODE_ENV' => 'production'])
```

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

### Block Specific Domains

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-images.md

Use `blockDomains()` to block connections to entire domains, effective for ad and tracker blocking. Pass an array of domain names.

```php
$domainsList = array("googletagmanager.com", "googlesyndication.com", "doubleclick.net", "google-analytics.com");
Browsershot::url('https://example.com')
    ->blockDomains($domainsList)
    ->save($pathToImage);
```

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

### Simulate Clicks on a Web Page

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/clicking-on-the-page.md

Use the `click` method to simulate clicks on elements identified by CSS selectors. You can specify the click type (e.g., 'right'), the number of clicks, and the duration between clicks.

```php
Browsershot::url('https://example.com')
    ->click('#selector1')
    // Right click 5 times on #selector2, each click lasting 200 milliseconds.
    ->click('#selector2', 'right', 5, 200)
```

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

### Use Pipe Connection in Browsershot

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/using-a-pipe-instead-of-a-websocket.md

Configure Browsershot to use a pipe connection instead of a WebSocket. This is useful for specific deployment scenarios or when WebSocket connections are not feasible.

```php
Browsershot::url('https://example.com')
   ->usePipe()
   ...
```

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

### Generate Tagged (Accessible) PDF

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-pdfs.md

Create a tagged PDF for improved accessibility by calling the `taggedPdf` method. This is beneficial for screen readers and other assistive technologies.

```php
Browsershot::html($someHtml)
    ->taggedPdf()
    ->save('example.pdf');
```

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

### Hide Website Background

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-images.md

Use `hideBackground()` to ignore the website's default background during screenshot capture.

```php
Browsershot::url('https://example.com')
    ->hideBackground()
    ->save($pathToImage);
```

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

### Set PDF to Landscape Orientation

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-pdfs.md

Configure the PDF to be generated in landscape orientation by calling the `landscape` method. This affects the page's width and height ratio.

```php
Browsershot::html($someHtml)
   ->landscape()
   ->save('example.pdf');
```

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

### Wait for CSS Selector

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-images.md

Use `waitForSelector()` to wait until a specific CSS selector appears on the page before taking the screenshot.

```php
Browsershot::url('https://example.com')
    ->waitForSelector('#my_selector')
    ->save($pathToImage);
```

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

### Pass custom arguments to Chromium

Source: https://github.com/spatie/browsershot/blob/main/docs/requirements.md

Add custom flags to Chromium using addChromiumArguments. Arguments are automatically prefixed with --.

```php
Browsershot::html('Foo')
  ->addChromiumArguments([
      'some-argument-without-a-value',
      'keyed-argument' => 'argument-value',
  ]);
```

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

### Set PDF Paper Size

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-pdfs.md

Specify custom width and height for the PDF using the `paperSize` method. An optional unit can be provided as the third parameter.

```php
Browsershot::html($someHtml)
   ->paperSize($width, $height)
   ->save('example.pdf');
```

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

### Evaluate JavaScript

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-html.md

This method allows you to evaluate a JavaScript expression within the page's context. It's useful for retrieving specific values or checking conditions after JavaScript execution. Ensure the deviceScaleFactor is set if needed for accurate evaluation.

```php
Browsershot::url('https://example.com')
  ->deviceScaleFactor(2)
  ->evaluate("window.devicePixelRatio"); // returns 2
```

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

### Save HTML to PDF

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-pdfs.md

Convert provided HTML content into a PDF document using the `savePdf` method. Ensure the HTML is trusted.

```php
Browsershot::html($someHtml)->savePdf('example.pdf');
```

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

### Type text into a form field

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/typing-on-the-page.md

Use the `type` method to simulate typing text into an element identified by a CSS selector. This is useful for filling out form fields.

```php
Browsershot::url('https://example.com')
    ->type('#selector1', 'Hello, is it me you are looking for?')
```

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

### Set Base URL for HTML Content

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/using-url-for-html-content.md

Use setContentUrl to provide a base URL for fetching relative resources when generating a screenshot from HTML content. This is crucial when your HTML includes relative paths that need a base to resolve correctly.

```php
Browsershot::html('<html>... relative paths to fetch ...</html>')
   ->setContentUrl('https://www.example.com')
   ...
```

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

### Block Specific URLs

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-images.md

Use `blockUrls()` to prevent connections to specified URLs, which is useful for blocking ads and trackers. Provide a list of URLs to block.

```php
$urlsList = array("example.com/cm-notify?pi=outbrain", "sync.outbrain.com/cookie-sync?p=bidswitch");
Browsershot::url('https://example.com')
    ->blockUrls($urlsList)
    ->save($pathToImage);
```

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

### Add CSS Styles

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-images.md

Use `setOption('addStyleTag', ...)` to inject custom CSS styles before the screenshot is taken, following Puppeteer's `addStyleTag` options.

```php
Browsershot::url('https://example.com')
    ->setOption('addStyleTag', json_encode(['content' => 'body{ font-size: 14px; }']))
    ->save($pathToImage);
```

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

### Specify Domain for Cookies

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/using-cookies.md

Optionally, specify the domain to which the cookies should be registered. This is useful when cookies need to be associated with a specific subdomain.

```php
Browsershot::url('https://example.com')
    ->useCookies(['Cookie-Key' => 'Cookie-Value'], 'ui.example.com')
   ...
```

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

### Set Browsershot Timeout

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/setting-the-timeout.md

Modify the default 60-second timeout to a custom value, such as 120 seconds, for a specific Browsershot operation. Ensure your environment is configured correctly if using Docker to avoid unexpected timeouts.

```php
Browsershot::url('https://example.com')
    ->timeout(120)
    ->save($pathToImage);
```

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

### Set PDF Margins

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-pdfs.md

Define custom margins (top, right, bottom, left) for the PDF using the `margins` method. An optional unit can be provided as the fifth parameter.

```php
Browsershot::html($someHtml)
   ->margins($top, $right, $bottom, $left)
   ->save('example.pdf');
```

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

### Explicitly Save URL to PDF

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-pdfs.md

Use the `savePdf` method for explicit PDF saving from a URL. This method is equivalent to saving with a `.pdf` extension.

```php
Browsershot::url('https://example.com')->savePdf('example.pdf');
```

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

### Add Cookies to Request

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/using-cookies.md

Use this method to add cookies to the request to a given URL. Ensure cookies are properly formatted as an associative array.

```php
Browsershot::url('https://example.com')
    ->useCookies(['Cookie-Key' => 'Cookie-Value'])
   ...
```

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

### Clip a Specific Portion of the Page

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-images.md

Capture only a rectangular region of the webpage defined by its coordinates and dimensions.

```php
Browsershot::url('https://example.com')
    ->clip($x, $y, $width, $height)
    ->save($pathToImage);
```

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

### Add Custom HTTP Headers to Navigation Request

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/adding-extra-headers-to-the-navigational-request.md

Use `setExtraNavigationHttpHeaders` to include custom headers in the main page request. Note that these headers are not sent for external resources like images or CSS.

```php
Browsershot::url('https://example.com')
    ->setExtraNavigationHttpHeaders(['Custom-Header-Name' => 'Custom-Header-Value'])
   ...
```

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

### Screenshot a Specific Element

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-images.md

Capture a screenshot of an HTML element identified by a CSS selector. An optional index can specify which matching element to capture.

```php
Browsershot::url('https://example.com')
    ->select('.some-selector', $selectorIndex)
    ->save($pathToImage);
```

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

### Scale PDF Content

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-pdfs.md

Adjust the scale of the PDF content using the `scale` method. The value must be between 0.1 and 2. Defaults to 1.

```php
Browsershot::html($someHtml)
    ->scale(0.5)
    ->save('example.pdf');
```

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

### Add Extra HTTP Headers to Requests

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/adding-extra-headers-to-every-request.md

Use `setExtraHttpHeaders` to add custom headers to the navigational HTTP request and all resources that make up the page. This is useful for authentication or custom tracking.

```php
Browsershot::url('https://example.com')
    ->setExtraHttpHeaders(['Custom-Header-Name' => 'Custom-Header-Value'])
   ...
```

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

### Add JavaScript Tag

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-images.md

Use `setOption('addScriptTag', ...)` to inject custom JavaScript content before the screenshot is taken, following Puppeteer's `addScriptTag` options.

```php
Browsershot::url('https://example.com')
    ->setOption('addScriptTag', json_encode(['content' => 'alert("Hello World")']))
    ->save($pathToImage);
```

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

### Disable HTTP Redirects

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/disabling-redirects.md

Use the `disableRedirects()` method to prevent Browsershot from following HTTP redirects. This is useful for security or to avoid redirects to disallowed domains.

```php
Browsershot::url('http://www.spatie.be')
   ->disableRedirects()
   ...
```

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

### Ignore HTTPS Errors in Browsershot

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/ignore-https-errors.md

Use the `ignoreHttpsErrors` method to allow Browsershot to load pages with invalid or self-signed SSL certificates. This is useful for development environments.

```php
Browsershot::url('https://example.com')
   ->ignoreHttpsErrors()
   ...
```

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

### Wait for JavaScript Function

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-images.md

Use `waitForFunction()` to pause execution until a JavaScript function returns `true`. Specify the polling interval and timeout in milliseconds.

```php
Browsershot::url('https://example.com')
    ->waitForFunction('window.innerWidth < 100', $pollingInMilliseconds, $timeoutInMilliseconds)
    ->save($pathToImage);
```

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

### Prevent Unsuccessful Responses

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/prevent-unsuccessful-responses.md

Use this method to throw an error when the page response is unsuccessful. Ensure proper error handling is in place.

```php
Browsershot::url('https://example.com')
   ->preventUnsuccessfulResponse()
    ...
```

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

### Disable Images in Screenshots

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-images.md

Use `disableImages()` to remove all images and `<img>` elements from the captured page. This can speed up screenshot generation.

```php
Browsershot::url('https://example.com')
    ->disableImages()
    ->save($pathToImage);
```

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

### Disable URL Capturing in Browsershot

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/performance.md

Use `disableCaptureURLs()` to prevent Browsershot from capturing URLs, which can improve memory efficiency when dealing with data URLs.

```php
Browsershot
    ::html('More data urls exists in this document')
    ->disableCaptureURLs()
;
```

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

### Dismiss JavaScript Dialogs

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-images.md

Automatically close JavaScript alerts, prompts, or confirmations that might halt rendering, ensuring a complete screenshot.

```php
Browsershot::url('https://example.com')
    ->dismissDialogs()
    ->save($pathToImage);
```

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

### Select Option in Dropdown

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/changing-the-value-of-a-dropdown.md

Use `selectOption` to change the selected value of a dropdown element identified by its CSS selector. This is useful for interacting with form select fields.

```php
Browsershot::url('https://example.com')
    ->selectOption('#selector1', '100')
```

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

### Disable CORS Checks in Browsershot

Source: https://github.com/spatie/browsershot/blob/main/docs/miscellaneous-options/fixing-cors-options.md

Use the --disable-web-security option to bypass CORS checks. This is useful when encountering issues related to cross-origin resource sharing.

```php
Browsershot::url('https://example.com')
   ->setOption('args', ['--disable-web-security'])
   ->save($pathToImage);
```

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

### Disable JavaScript Execution

Source: https://github.com/spatie/browsershot/blob/main/docs/usage/creating-images.md

Completely disable JavaScript execution for the page rendering. Note that this may cause some sites to not render correctly.

```php
Browsershot::url('https://example.com')
    ->disableJavascript()
    ->save($pathToImage);
```
Tokens:
Raw