Spatie Browsershot

Browsershot uses Puppeteer to convert web pages into images or PDF files. The output format is determined by the file extension provided to the save method.

To save an image, provide a path with an image extension. To save a PDF, provide a path with a .pdf extension.

If you encounter Cross-Origin Resource Sharing (CORS) issues when rendering a page, you can bypass these checks by passing the --disable-web-security Chromium command-line switch via the setOption method using the args key.

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

Use the type() method to simulate typing text into a specific element on a page. This is useful for filling out form fields automatically. The method requires a CSS selector and the string of text to be typed.

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

When running on Linux within certain virtualization environments, Puppeteer may require sandboxing to be disabled to function correctly. Use the noSandbox() method to disable the Chrome sandbox.

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

When providing a large number of options to Puppeteer, Browsershot may fail due to command line character limits (overflow). To prevent this, use the writeOptionsToFile() method. This instructs Browsershot to write the options to a temporary file and pass that file to Puppeteer instead of passing them directly via the command line.

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

You can include cookies in the request sent to a specific URL by using the useCookies method. This method accepts an associative array where the keys are the cookie names and the values are the cookie values.

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

If you need to navigate to a URL that has invalid or self-signed SSL certificates, you can use the ignoreHttpsErrors() method to prevent Puppeteer from failing the request.

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

Browsershot requires Puppeteer to run a headless version of Google Chrome. You can install it globally via npm:

npm -g i puppeteer

To prevent Browsershot from following HTTP redirects—which can be useful for security reasons or to avoid navigating to unauthorized domains—call the disableRedirects() method on your Browsershot instance.

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

Use the url() method to target a specific webpage and the save() method to export the result. Browsershot determines the output format based on the file extension provided to save(): use an image extension (e.g., .png, .jpg) for images, or .pdf for PDF documents.

use Spatie\Browsershot\Browsershot;

// Save an image
Browsershot::url('https://example.com')->save($pathToImage);

// Save a PDF
Browsershot::url('https://example.com')->save('example.pdf');

For Ubuntu v24.04 servers (such as those provisioned by Laravel Forge), follow these steps to install Node, Puppeteer, Chromium, and the necessary system dependencies.

Note for Ubuntu v22.04 users: Replace libasound2t64 with libasound2 in the dependency list.

# 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 can change the language of the browser by using the setEnvironmentOptions method. This is useful when you need to load a page in a specific language or locale. Pass an associative array to setEnvironmentOptions containing the LANG key with your desired locale (e.g., 'en-GB').

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