Generating Webpage Thumbnails in PHP Using the Browsershot Library

In a recent project, I needed to generate thumbnails for specific URLs using PHP. While Node.js developers often use Headless Chrome for this, the PHP ecosystem offers the spatie/browsershot library, which can also leverage Headless Chrome to generate webpage thumbnails. This article documents how to use this library and addresses some common issues encountered during implementation.

Installing and Configuring the spatie/browsershot Library

First, you need to install spatie/browsershot via Composer. Once installed, you can use the library’s classes to generate thumbnails as shown in the official documentation:

use Spatie\Browsershot\Browsershot;

$browsershot = new Browsershot;
$browsershot->setNodeModulePath('/path/to/your/node_modules');
$browsershot->setNpmBinary('/path/to/your/npm');
$browsershot->setPuppeteerExecutablePath('/path/to/your/puppeteer_executable');

$browsershot->url($site_url)
            ->windowSize(1440, 2000)
            ->fullPage()
            ->setScreenshotType('jpeg', 80)
            ->save($save_path);

While the code looks straightforward, successful execution requires more than just configuring paths. You also need to enable specific PHP extensions and install dependencies such as Node.js, Chromium, and various third-party libraries required by Chromium.

Enabling PHP proc_open and proc_get_status Functions

First, ensure that the proc_open and proc_get_status functions are enabled in PHP. The Browsershot library relies on these functions to execute Node.js commands and monitor their execution status.

These functions are often disabled by default in many hosting environments. You can enable them by editing your php.ini file.

Installing Node.js and Chromium Libraries

Browsershot uses Headless Chrome within a Node.js environment to capture screenshots, so Chromium must be installed. On CentOS, you can install Node.js and Chromium using the following commands:

sudo dnf module install nodejs:18
sudo dnf install chromium

If Chromium is not available in your system’s software repository, you can install it via npm:

npm i puppeteer

Once installed, note the paths to these binaries and include them in your code. To find the Chromium executable path, use:

node -e "console.log(require('puppeteer').executablePath())"

Note: The user account running PHP must have execution permissions for the Chromium binary.

Installing Chromium System Dependencies

Chromium depends on several Linux system libraries. These must be installed for Chromium to function correctly.

sudo dnf install atk at-spi2-atk libdrm libXcomposite libXdamage libXrandr mesa-libgbm pango alsa-lib

Or for Debian/Ubuntu systems:

sudo apt install -y libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libgbm1 libxdamage1 libxrandr2 libasound2 libpangocairo-1.0-0 libpangoft2-1.0-0 libnss3 libxcomposite1 libxshmfence1 libxrender1 libxfixes3 libxkbcommon0

Because every Linux environment is different, you might encounter missing libraries. If Browsershot fails to run after installing the above, check the error output to identify and install any remaining missing dependencies.

Browsershot Performance and Usage Suggestions

Browsershot functions by opening a page and capturing a screenshot, which is inherently time-consuming. In my tests, capturing a high-resolution screenshot (1440px wide by 2500px high) typically takes 2 to 3 seconds, depending on the page load speed and server performance. Because of this, Browsershot is generally unsuitable for real-time, synchronous operations. It is best used to pre-generate thumbnails, which are then saved on the server and served as needed.