PHPackages                             cnerstudio/puphpeteer - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Testing & Quality](/categories/testing)
4. /
5. cnerstudio/puphpeteer

ActiveLibrary[Testing & Quality](/categories/testing)

cnerstudio/puphpeteer
=====================

A Puppeteer bridge for PHP, supporting the entire API.

v3.1.2(5mo ago)019MITPHPPHP ^8.1

Since Jan 29Pushed 5mo ago1 watchersCompare

[ Source](https://github.com/cnerstudio/puphpeteer)[ Packagist](https://packagist.org/packages/cnerstudio/puphpeteer)[ RSS](/packages/cnerstudio-puphpeteer/feed)WikiDiscussions cner Synced 1mo ago

READMEChangelogDependencies (11)Versions (29)Used By (0)

PuPHPeteer
==========

[](#puphpeteer)

[![](https://user-images.githubusercontent.com/817508/100672192-dd258500-3361-11eb-845f-e8b5109752e4.png)](https://user-images.githubusercontent.com/817508/100672192-dd258500-3361-11eb-845f-e8b5109752e4.png)

[![PHP Version](https://camo.githubusercontent.com/16999b033b6c4d3c6ad210d06b7ebb6619c593542e38404dc735b9032e7e2fa9/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f636e657273747564696f2f707570687065746565722e7376673f7374796c653d666c61742d737175617265)](http://php.net/)[![Composer Version](https://camo.githubusercontent.com/eb99070fb495c6ebbe640d3846b56d3fcef31cae15b7a5180ab0830474121e4e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f636e657273747564696f2f707570687065746565722e7376673f7374796c653d666c61742d737175617265266c6162656c3d436f6d706f736572)](https://packagist.org/packages/cnerstudio/puphpeteer)[![Node Version](https://camo.githubusercontent.com/7b3cdb10f853fa7b47de1db3bc4ac402bab9badeeb86fbfe54868f105b7819d5/68747470733a2f2f696d672e736869656c64732e696f2f6e6f64652f762f40636e657273747564696f2f707570687065746565722e7376673f7374796c653d666c61742d737175617265266c6162656c3d4e6f6465)](https://nodejs.org/)[![NPM Version](https://camo.githubusercontent.com/9ca2fb42a9090873b4f918762bcf946bff69e7fdcba1258fc65a1e7c2413cbc7/68747470733a2f2f696d672e736869656c64732e696f2f6e706d2f762f40636e657273747564696f2f707570687065746565722e7376673f7374796c653d666c61742d737175617265266c6162656c3d4e504d)](https://www.npmjs.com/package/@nesk/puphpeteer)

A [Puppeteer](https://github.com/GoogleChrome/puppeteer/) bridge for PHP, supporting the entire API. Based on [Rialto](https://github.com/cnerstudio/rialto/), a package to manage Node resources from PHP.

Here are some examples [borrowed from Puppeteer's documentation](https://github.com/GoogleChrome/puppeteer/blob/master/README.md#usage) and adapted to PHP's syntax:

**Example** - navigating to  and saving a screenshot as *example.png*:

```
use Nesk\Puphpeteer\Puppeteer;

$puppeteer = new Puppeteer;
$browser = $puppeteer->launch();

$page = $browser->newPage();
$page->goto('https://example.com');
$page->screenshot(['path' => 'example.png']);

$browser->close();
```

**Example** - evaluate a script in the context of the page:

```
use Nesk\Puphpeteer\Puppeteer;
use Nesk\Rialto\Data\JsFunction;

$puppeteer = new Puppeteer;

$browser = $puppeteer->launch();
$page = $browser->newPage();
$page->goto('https://example.com');

// Get the "viewport" of the page, as reported by the page.
$dimensions = $page->evaluate(JsFunction::createWithBody("
    return {
        width: document.documentElement.clientWidth,
        height: document.documentElement.clientHeight,
        deviceScaleFactor: window.devicePixelRatio
    };
"));

printf('Dimensions: %s', print_r($dimensions, true));

$browser->close();
```

Requirements and installation
-----------------------------

[](#requirements-and-installation)

This package requires PHP >= 7.3 and Node >= 8.

Install it with these two command lines:

```
composer require cnerstudio/puphpeteer
npm install @cnerstudio/puphpeteer
```

Use with browserless
--------------------

[](#use-with-browserless)

```
docker run --rm  -p 3000:3000 ghcr.io/browserless/chrome
```

```
$puppeteer = new Nesk\Puphpeteer\Puppeteer;

$options = [
    'headless' => false,
    'stealth'=> true,
    'timeout'=> 5000,
    'args' => [
        '--window-size=1366,768',
    ],
];

$browser = $puppeteer->connect(['browserWSEndpoint' => 'ws://127.0.0.1:3000/chrome?launch='.urlencode(json_encode($options, JSON_UNESCAPED_UNICODE))]);
$page = $browser->newPage();
$page->goto('https://www.example.com');
$page->screenshot(['path' => 'example.png']);
$browser->close();
```

Notable differences between PuPHPeteer and Puppeteer
----------------------------------------------------

[](#notable-differences-between-puphpeteer-and-puppeteer)

### Puppeteer's class must be instantiated

[](#puppeteers-class-must-be-instantiated)

Instead of requiring Puppeteer:

```
const puppeteer = require('puppeteer');
```

You have to instantiate the `Puppeteer` class:

```
$puppeteer = new Puppeteer;
```

This will create a new Node process controlled by PHP.

You can also pass some options to the constructor, see [Rialto's documentation](https://github.com/nesk/rialto/blob/master/docs/api.md#options). PuPHPeteer also extends these options:

```
[
    // Logs the output of Browser's console methods (console.log, console.debug, etc...) to the PHP logger
    'log_browser_console' => false,
]
```

**⏱ Want to use some timeouts higher than 30 seconds in Puppeteer's API?**
If you use some timeouts higher than 30 seconds, you will have to set a higher value for the `read_timeout` option (default: `35`):

```
$puppeteer = new Puppeteer([
    'read_timeout' => 65, // In seconds
]);

$puppeteer->launch()->newPage()->goto($url, [
    'timeout' => 60000, // In milliseconds
]);
```

### No need to use the `await` keyword

[](#no-need-to-use-the-await-keyword)

With PuPHPeteer, every method call or property getting/setting is synchronous.

### Some methods have been aliased

[](#some-methods-have-been-aliased)

The following methods have been aliased because PHP doesn't support the `$` character in method names:

- `$` => `querySelector`
- `$$` => `querySelectorAll`
- `$eval` => `querySelectorEval`
- `$$eval` => `querySelectorAllEval`

Use these aliases just like you would have used the original methods:

```
$divs = $page->querySelectorAll('div');
// Runs the `//h2` as the XPath expression.
$xpath = $page->querySelectorAll('::-p-xpath(//h2)');
// div element that has Checkout as the inner text.
$text = $page->querySelector('div ::-p-text(Checkout)');
```

### Evaluated functions must be created with `JsFunction`

[](#evaluated-functions-must-be-created-with-jsfunction)

Functions evaluated in the context of the page must be written [with the `JsFunction` class](https://github.com/nesk/rialto/blob/master/docs/api.md#javascript-functions), the body of these functions must be written in JavaScript instead of PHP.

```
use Nesk\Rialto\Data\JsFunction;

$pageFunction = JsFunction::createWithParameters(['element'])
    ->body("return element.textContent");
```

### Exceptions must be caught with `->tryCatch`

[](#exceptions-must-be-caught-with--trycatch)

If an error occurs in Node, a `Node\FatalException` will be thrown and the process closed, you will have to create a new instance of `Puppeteer`.

To avoid that, you can ask Node to catch these errors by prepending your instruction with `->tryCatch`:

```
use Nesk\Rialto\Exceptions\Node;

try {
    $page->tryCatch->goto('invalid_url');
} catch (Node\Exception $exception) {
    // Handle the exception...
}
```

Instead, a `Node\Exception` will be thrown, the Node process will stay alive and usable.

### Puppeteer plugins

[](#puppeteer-plugins)

Puppeteer-extra and puppeteer-extra-plugin-stealth plugins already added in npm requirements.

To use them, override js inclusion with js\_extra option

```
    $puppeteer = new Puppeteer([
        'js_extra' => /** @lang JavaScript */ "
            const puppeteer = require('puppeteer-extra');
            const StealthPlugin = require('puppeteer-extra-plugin-stealth');
            puppeteer.use(StealthPlugin());
            instruction.setDefaultResource(puppeteer);
        "
    ]);
```

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE) for more information.

Logo attribution
----------------

[](#logo-attribution)

PuPHPeteer's logo is composed of:

- [Puppet](https://thenounproject.com/search/?q=puppet&i=52120) by Luis Prado from [the Noun Project](http://thenounproject.com/).
- [Elephant](https://thenounproject.com/search/?q=elephant&i=954119) by Lluisa Iborra from [the Noun Project](http://thenounproject.com/).

Thanks to [Laravel News](https://laravel-news.com/) for picking the icons and colors of the logo.

###  Health Score

46

—

FairBetter than 93% of packages

Maintenance70

Regular maintenance activity

Popularity6

Limited adoption so far

Community15

Small or concentrated contributor base

Maturity82

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 69.9% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~143 days

Recently: every ~97 days

Total

21

Last Release

167d ago

Major Versions

0.2.2 → 1.0.02018-06-05

1.6.0 → 2.1.02023-07-17

v2.2.0 → v3.0.02024-11-01

PHP version history (5 changes)0.1.0PHP >=7.1

2.1.0PHP ^8.0

v3.0.0PHP >=7.3

v3.0.3PHP ^7.2 || ^8.0

v3.1.1PHP ^8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/dca860fd47fef74b0f9725a39b3cb7030a23356e578772015dc70369a8aba0f1?d=identicon)[cnerstudio](/maintainers/cnerstudio)

---

Top Contributors

[![nesk](https://avatars.githubusercontent.com/u/817508?v=4)](https://github.com/nesk "nesk (107 commits)")[![xtrime-ru](https://avatars.githubusercontent.com/u/34161928?v=4)](https://github.com/xtrime-ru "xtrime-ru (27 commits)")[![spekulatius](https://avatars.githubusercontent.com/u/8433587?v=4)](https://github.com/spekulatius "spekulatius (8 commits)")[![RobinDev](https://avatars.githubusercontent.com/u/3944894?v=4)](https://github.com/RobinDev "RobinDev (5 commits)")[![erikgaal](https://avatars.githubusercontent.com/u/1234268?v=4)](https://github.com/erikgaal "erikgaal (2 commits)")[![nickescobedo](https://avatars.githubusercontent.com/u/2837169?v=4)](https://github.com/nickescobedo "nickescobedo (1 commits)")[![SirLouen](https://avatars.githubusercontent.com/u/224787?v=4)](https://github.com/SirLouen "SirLouen (1 commits)")[![LF995](https://avatars.githubusercontent.com/u/132549555?v=4)](https://github.com/LF995 "LF995 (1 commits)")[![fmaruejol](https://avatars.githubusercontent.com/u/38423811?v=4)](https://github.com/fmaruejol "fmaruejol (1 commits)")

---

Tags

phptestingwebautomationpuppeteerdeveloper-toolsheadless-chrome

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/cnerstudio-puphpeteer/health.svg)

```
[![Health](https://phpackages.com/badges/cnerstudio-puphpeteer/health.svg)](https://phpackages.com/packages/cnerstudio-puphpeteer)
```

###  Alternatives

[zoon/puphpeteer

A Puppeteer bridge for PHP, supporting the entire API.

204192.9k1](/packages/zoon-puphpeteer)[phan/phan

A static analyzer for PHP

5.6k11.2M1.1k](/packages/phan-phan)[playwright-php/playwright

Modern PHP library for Playwright automation: browsing, scraping, screenshots, testing, and more.

7613.0k5](/packages/playwright-php-playwright)[nigelcunningham/puphpeteer

A Puppeteer bridge for PHP, supporting the entire API.

2221.7k](/packages/nigelcunningham-puphpeteer)[victor-teles/playwright-php

A Playwright bridge for PHP.

203.6k](/packages/victor-teles-playwright-php)[doppiogancio/mocked-client

A simple way to mock a client

2174.9k3](/packages/doppiogancio-mocked-client)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)