English | Tiếng Việt
Playwright-style browser automation for PHP: no Node.js, works in Swoole coroutines.
Native Playwright is a native PHP extension. It is written in PHP and compiled to C++17 with TypePHP. It drives Chromium directly over the Chrome DevTools Protocol (CDP), with no intermediate process.
- Familiar API:
Locator,getByRole, auto-waiting,route,expectPopup… mirror Playwright, so existing code ports easily. - No Node.js: no driver process, just PHP and Chromium.
- Lightweight: the driver uses about 19 MB, compared with about 145 MB for Playwright on Node. Total RAM is about 34% lower.
- Swoole support: coroutines are detected automatically, so many pages can run concurrently on one worker without blocking the event loop.
- Requirements: PHP 8.4 / 8.5 (NTS), Linux or macOS.
- Installation
- Quick start
- Core concepts
- Usage guide
- Launching the browser
- Contexts and emulation
- Navigation
- Finding elements with locators
- Actions
- Reading data and waiting
- Running JavaScript
- Keyboard, mouse, touch
- Iframes
- Network: monitoring and interception
- Events
- Dialogs, popups, downloads, uploads
- Screenshots and PDF
- Cookies and storage state
- Calling PHP from the page
- Timeouts and errors
- Raw CDP access
- Using with Swoole
- Migrating from Playwright (JS)
- Performance
- Architecture
- Current limitations
- Troubleshooting
- Development
| Component | Version |
|---|---|
| PHP | 8.4 or 8.5, NTS build |
| Chromium | chrome-headless-shell (recommended), Chromium or Google Chrome |
| Swoole | 6.x (optional, only needed for coroutines) |
| Build tools | C/C++ compiler (C++17), phpize, libgmp-dev, libmpfr-dev |
PIE is the official PHP extension installer. It builds the extension for your exact PHP version and enables it in php.ini:
# build dependencies (Debian/Ubuntu; use gmp-devel mpfr-devel on RHEL, "brew install gmp mpfr" on macOS)
sudo apt-get install -y build-essential libgmp-dev libmpfr-dev
pie install nguyenthuan2412/native-playwrightThen install Chrome: see Installing Chrome.
Each GitHub release ships a PECL package:
sudo apt-get install -y build-essential libgmp-dev libmpfr-dev
curl -fsSLO https://github.com/nguyenthuan2412/native-playwright/releases/download/v0.1.0/native_playwright-0.1.0.tgz
pecl install ./native_playwright-0.1.0.tgz
echo "extension=native_playwright" > "$(php-config --ini-dir)/native_playwright.ini"The ext/ directory is a standard phpize source tree. Building it does not require TypePHP:
cd ext
phpize
./configure # --with-gmp-dir=PREFIX if GMP/MPFR live in a non-standard prefix
make -j"$(nproc)"
sudo make installVerify:
php --ri native_playwrightThe extension statically embeds the PHPX runtime. At runtime it only needs the system libgmp and libmpfr.
PIE and PECL install only the extension. Native Playwright also needs a Chrome binary on the machine. Install one (option A, B or C), find where it is, and give that path to Native Playwright.
sudo apt-get install -y chromium-headless-shellThis installs /usr/lib/chromium/chromium-headless-shell, which Native Playwright finds on its own, so there is nothing else to configure. It works on x86_64 and arm64. The official php:* Docker images are Debian-based:
FROM php:8.5-cli
RUN apt-get update && apt-get install -y --no-install-recommends chromium-headless-shell libgmp-dev libmpfr-devGoogle publishes chrome-headless-shell builds at https://googlechromelabs.github.io/chrome-for-testing/. In the Stable section, copy the chrome-headless-shell URL for your platform (linux64, mac-arm64 or mac-x64), then download and unzip it:
cd /opt
sudo curl -fsSLO "<URL copied from the page>"
sudo unzip -q chrome-headless-shell-linux64.zip # mac: chrome-headless-shell-mac-arm64.zip
# binary: /opt/chrome-headless-shell-linux64/chrome-headless-shellIf Node.js is available, this one command does the same and prints the path at the end:
npx @puppeteer/browsers install chrome-headless-shell@stableOn Ubuntu the browser also needs some system libraries (package names for Ubuntu 24.04; on 22.04 drop the t64 suffix):
sudo apt-get install -y libnss3 libnspr4 libatk1.0-0t64 libatk-bridge2.0-0t64 libcups2t64 libdrm2 \
libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1 libasound2t64 \
libatspi2.0-0t64 libpango-1.0-0 libcairo2 libxshmfence1 fonts-liberationTo check, run ldd /path/to/chrome-headless-shell | grep "not found". If it prints nothing, no library is missing.
Chrome for Testing has no Linux arm64 build. On arm64, use option A.
A normal Chrome or Chromium install works as well, but it uses about 3× more RAM than chrome-headless-shell (see Performance).
| Installed with | How to find the binary |
|---|---|
apt install chromium-headless-shell |
/usr/lib/chromium/chromium-headless-shell (or dpkg -L chromium-headless-shell) |
| Chrome for Testing zip | the folder you unzipped into, or find / -name chrome-headless-shell -type f 2>/dev/null |
npx @puppeteer/browsers |
printed on the last line of the install command |
| Google Chrome on Linux | which google-chrome |
| Google Chrome on macOS | /Applications/Google Chrome.app/Contents/MacOS/Google Chrome |
Check that the path works:
"/opt/chrome-headless-shell-linux64/chrome-headless-shell" --versionPass it when launching:
$browser = Playwright::chromium()->launch([
'executablePath' => '/opt/chrome-headless-shell-linux64/chrome-headless-shell',
]);Or set it once for the whole application with an environment variable:
export NATIVE_PLAYWRIGHT_CHROME=/opt/chrome-headless-shell-linux64/chrome-headless-shell| Where your PHP runs | How to set the variable |
|---|---|
| CLI / Swoole server | export NATIVE_PLAYWRIGHT_CHROME=... before starting PHP |
| PHP-FPM | env[NATIVE_PLAYWRIGHT_CHROME] = /path/... in the pool config (e.g. www.conf) |
| Docker | ENV NATIVE_PLAYWRIGHT_CHROME=/path/... in the Dockerfile |
Native Playwright picks the browser in this order:
- The
executablePathlaunch option - The
NATIVE_PLAYWRIGHT_CHROMEenvironment variable - These locations, checked one by one (no configuration needed if your browser is here):
/usr/lib/chromium/chromium-headless-shell,/usr/bin/chromium-headless-shell,/usr/bin/chrome-headless-shell,/opt/google/chrome-headless-shell/chrome-headless-shell,/usr/lib/chromium/chromium,/usr/bin/chromium,/usr/bin/chromium-browser,/usr/bin/google-chrome,/opt/google/chrome/chrome,/Applications/Google Chrome.app/Contents/MacOS/Google Chrome,/Applications/Chromium.app/Contents/MacOS/Chromium
You need the extension and a Chrome binary: see Installing Chrome.
<?php
use NativePlaywright\Playwright;
$browser = Playwright::chromium()->launch();
$page = $browser->newPage();
$page->goto('https://example.com');
echo $page->title(), PHP_EOL;
$page->getByRole('link', ['name' => 'More information'])->click();
$page->waitForLoadState();
$page->screenshot(['path' => 'example.png', 'fullPage' => true]);
$browser->close();php -d extension=build/php8.5/native_playwright.so quickstart.php| Object | Role |
|---|---|
Playwright |
Entry point: Playwright::chromium() returns a BrowserType |
Browser |
One Chromium process |
BrowserContext |
An isolated session (own cookies, storage, cache). Cheap to create because it shares the browser process |
Page |
A tab |
Frame |
The main frame or an iframe inside a page |
Locator |
A way to find elements. Lazy, strict, and auto-waiting |
General conventions:
- Options are passed as associative arrays, with the same keys as Playwright:
['timeout' => 5000, 'waitUntil' => 'networkidle']. - Times are in milliseconds.
timeout => 0means no limit. - URL patterns come in three forms: a glob (
'**/api/*'), a PHP regex written as a string ('/\.png$/'), or aClosure(string $url): bool.
$browser = Playwright::chromium()->launch([
'executablePath' => '/usr/lib/chromium/chromium-headless-shell',
'args' => ['--lang=en-US'], // extra Chromium flags
'timeout' => 30000,
'slowMo' => 0, // ms pause after each action (debugging)
'downloadsPath' => '/tmp/downloads',
'proxy' => ['server' => 'http://proxy:3128', 'bypass' => 'localhost'],
]);
echo $browser->version(); // "156.0.8078.79"
$browser->close();| Option | Default | Description |
|---|---|---|
executablePath |
auto-detected | Path to Chromium |
args |
[] |
Extra Chromium flags |
ignoreDefaultArgs |
false |
true drops all default flags; or pass an array of flags to drop |
headless |
true |
false only has an effect with full Chromium |
chromiumSandbox |
false |
Enable Chromium's sandbox |
siteIsolation |
false |
Enable site isolation (see Limitations) |
swoole |
auto-detected | Force (or disable) the Swoole transport |
A persistent profile (keeps logins between runs):
$context = Playwright::chromium()->launchPersistentContext('/data/profile', ['locale' => 'en-US']);
$page = $context->newPage();
// ...
$context->close(); // also closes the browser$context = $browser->newContext([
'baseURL' => 'https://shop.example.com',
'viewport' => ['width' => 1366, 'height' => 768], // null = don't force a size
'deviceScaleFactor'=> 2,
'userAgent' => 'MyBot/1.0',
'locale' => 'en-GB',
'timezoneId' => 'Europe/London',
'geolocation' => ['latitude' => 51.50, 'longitude' => -0.12],
'permissions' => ['geolocation', 'notifications'],
'colorScheme' => 'dark',
'extraHTTPHeaders' => ['X-Request-Source' => 'Native Playwright'],
'httpCredentials' => ['username' => 'admin', 'password' => 'secret'],
'ignoreHTTPSErrors'=> true,
'javaScriptEnabled'=> true,
'offline' => false,
'storageState' => 'auth.json', // load saved cookies + localStorage
]);
$page = $context->newPage();
$page->goto('/cart'); // same as https://shop.example.com/cartDevice emulation:
$page = $browser->newPage(Playwright::devices('iPhone 13'));Available devices: iPhone 15, iPhone 13, iPhone SE, iPad Pro 11, Pixel 7, Galaxy S9+, Desktop Chrome, Desktop Chrome HiDPI.
$browser->newPage($options) creates a dedicated context for that page. Closing the page also closes the context.
Changing settings while a context is running:
$context->setGeolocation(['latitude' => 48.85, 'longitude' => 2.35]);
$context->setOffline(true);
$context->setExtraHTTPHeaders(['Authorization' => 'Bearer ...']);
$context->grantPermissions(['clipboard-read'], ['origin' => 'https://app.example.com']);
$context->clearPermissions();
$page->setViewportSize(['width' => 800, 'height' => 600]);
$page->emulateMedia(['media' => 'print', 'colorScheme' => 'light']);$response = $page->goto('https://example.com', [
'waitUntil' => 'load', // load | domcontentloaded | networkidle | commit
'timeout' => 15000,
'referer' => 'https://google.com',
]);
$response?->status(); // 200
$page->reload();
$page->goBack();
$page->goForward();
$page->waitForLoadState('networkidle');
$page->waitForURL('**/checkout/success');
// Wait for a navigation triggered by an action
$page->expectNavigation(fn() => $page->getByText('Sign in')->click());
$page->url();
$page->title();
$page->content(); // current HTML
$page->setContent('<h1>Hello</h1>');goto() throws NativePlaywright\Exception when navigation fails (for example net::ERR_NAME_NOT_RESOLVED). It returns null for same-document navigations (hash changes).
Prefer locators that reflect how users see the page:
$page->getByRole('button', ['name' => 'Submit']);
$page->getByRole('heading', ['level' => 1]);
$page->getByRole('checkbox', ['checked' => true]);
$page->getByText('Welcome'); // substring, case-insensitive
$page->getByText('Welcome', ['exact' => true]); // exact match
$page->getByText('/^Total: \d+/'); // regex
$page->getByLabel('Email');
$page->getByPlaceholder('Search');
$page->getByAltText('Logo');
$page->getByTitle('Close');
$page->getByTestId('submit-btn'); // data-testid; rename with Playwright::setTestIdAttribute()CSS / XPath and Playwright's extended syntax:
$page->locator('#cart .item'); // CSS, pierces shadow DOM
$page->locator('xpath=//table/tr[2]');
$page->locator('//button'); // detected as XPath
$page->locator('text=Sign out');
$page->locator('li:has-text("Apple")');
$page->locator('button:visible');
$page->locator('.list >> li >> nth=2'); // chainingFiltering, combining and picking by position:
$rows = $page->locator('tr');
$rows->filter(['hasText' => 'Paid']);
$rows->filter(['hasNotText' => 'Cancelled']);
$rows->filter(['has' => $page->getByRole('button', ['name' => 'Edit'])]);
$rows->filter(['visible' => true]);
$rows->first();
$rows->last();
$rows->nth(3);
$rows->count();
foreach ($rows->all() as $row) { /* ... */ }
$page->locator('.card')->getByRole('link'); // search inside
$page->getByRole('button')->and($page->getByTitle('Save'));
$page->getByText('Sign in')->or($page->getByText('Log in'));Strict mode: any action on a locator that matches more than one element fails with strict mode violation, and the error lists the matches. Narrow it down with first(), nth() or filter().
Before every action, Native Playwright waits until the element is attached, visible, stable (not animating), enabled, and not covered by another element. Off-screen elements are scrolled into view. You don't need sleep calls.
$page->getByRole('button', ['name' => 'Buy']) ->click();
$page->getByText('Photo') ->dblclick();
$page->getByLabel('Full name') ->fill('Jane Doe');
$page->getByLabel('Full name') ->clear();
$page->getByLabel('OTP code') ->pressSequentially('123456', ['delay' => 50]);
$page->getByLabel('Search') ->press('Enter');
$page->getByLabel('I agree') ->check();
$page->getByLabel('Newsletter') ->setChecked(false);
$page->getByLabel('Country') ->selectOption('Germany'); // by value or label
$page->locator('select[multiple]') ->selectOption(['a', 'b']);
$page->locator('select') ->selectOption(['index' => 2]);
$page->locator('.menu') ->hover();
$page->locator('#item') ->dragTo($page->locator('#trash'));
$page->locator('input') ->focus();
$page->locator('.box') ->dispatchEvent('click');
$page->locator('button') ->tap(); // requires hasTouchOptions for mouse actions:
$locator->click([
'button' => 'right', // left | right | middle
'clickCount' => 2,
'delay' => 100, // ms between press and release
'position' => ['x' => 5, 'y' => 5], // relative to the element's top-left corner
'modifiers' => ['Shift', 'ControlOrMeta'],
'force' => true, // skip actionability checks
'trial' => true, // run the checks only, don't click
'timeout' => 5000,
]);Like Playwright, Page also has selector shortcuts: $page->click('#ok'), $page->fill('#q', 'x'), $page->check(...)…
$el = $page->locator('#total');
$el->textContent(); // ?string
$el->innerText();
$el->innerHTML();
$el->getAttribute('href');
$el->inputValue(); // input / textarea / select
$el->boundingBox(); // ['x','y','width','height'] or null
$el->isVisible(); // does not wait
$el->isHidden();
$el->isEnabled();
$el->isChecked();
$el->isEditable();
$page->locator('li')->allTextContents(); // string[]
$page->locator('li')->allInnerTexts();
$page->locator('main')->ariaSnapshot(); // accessibility tree as YAMLWaiting for a specific state:
$page->locator('.spinner')->waitFor(['state' => 'hidden']); // attached | detached | visible | hidden
$page->locator('.result')->waitFor(['timeout' => 10000]);
$page->waitForSelector('#toast', ['state' => 'visible']);
$page->waitForFunction('() => window.appReady === true');
$page->waitForTimeout(500); // for debugging only$page->evaluate('document.title'); // expression
$page->evaluate('(a) => a.x + a.y', ['x' => 1, 'y' => 2]); // function with an argument
$page->evaluate('async () => (await fetch("/api/me")).json()'); // promises are awaited
$page->locator('#price')->evaluate('el => el.dataset.value');
$page->locator('li')->evaluateAll('(els, sep) => els.map(e => e.textContent).join(sep)', ', ');
$page->addInitScript('Object.defineProperty(navigator, "webdriver", { get: () => false })');
$page->addScriptTag(['url' => 'https://cdn.example.com/lib.js']);
$page->addStyleTag(['content' => '* { animation: none !important }']);Return values are converted to PHP types: objects become associative arrays, Date becomes an ISO string, and NaN/Infinity become floats. Values that can't be serialized (DOM nodes, window, functions) become null.
$page->keyboard->type('Hello world', ['delay' => 30]);
$page->keyboard->press('ControlOrMeta+A'); // Control on Linux/Windows, Meta on macOS
$page->keyboard->press('Shift+Tab');
$page->keyboard->down('Shift');
$page->keyboard->up('Shift');
$page->keyboard->insertText('😀');
$page->mouse->move(100, 200, ['steps' => 10]);
$page->mouse->down();
$page->mouse->up();
$page->mouse->click(300, 400, ['button' => 'right']);
$page->mouse->wheel(0, 500);
$page->touchscreen->tap(50, 50);$frame = $page->frameLocator('iframe#payment');
$frame->getByLabel('Card number')->fill('4111 1111 1111 1111');
$frame->getByRole('button', ['name' => 'Pay'])->click();
// Nested iframes
$page->frameLocator('#outer')->frameLocator('#inner')->locator('button')->click();
// Direct access to Frame objects
$page->frame('payment'); // by name attribute
$page->frame(['url' => '**/checkout/*']);
$page->frames();
$page->mainFrame()->childFrames();Same-origin and cross-origin iframes are both supported with the default configuration.
Monitoring:
$page->on('request', fn(NativePlaywright\Request $r) => print("> {$r->method()} {$r->url()}\n"));
$page->on('response', fn(NativePlaywright\Response $r) => print("< {$r->status()} {$r->url()}\n"));
$page->on('requestfailed', fn($r) => print("x {$r->url()} {$r->failure()['errorText']}\n"));
$response = $page->expectResponse('**/api/orders*', fn() => $page->getByText('Load orders')->click());
$data = $response->json();
$response->request()->postDataJSON();Intercepting and modifying requests (routes):
use NativePlaywright\Route;
use NativePlaywright\Request;
// Mock a response
$page->route('**/api/user', fn(Route $route) => $route->fulfill([
'status' => 200,
'json' => ['id' => 1, 'name' => 'Test'],
]));
// Block heavy resources
$page->route('/\.(png|jpe?g|gif|webp|woff2?)$/', fn(Route $route) => $route->abort());
// Modify a request before it is sent
$page->route('**/api/**', fn(Route $route, Request $req) => $route->continue([
'headers' => array_merge($req->headers(), ['authorization' => 'Bearer xyz']),
]));
// Hand over to a handler registered earlier
$page->route('**/*', fn(Route $route) => $route->fallback());
// Apply only N times
$page->route('**/flaky', fn(Route $r) => $r->abort('timedout'), ['times' => 1]);
// Apply to every page in a context
$context->route('**/analytics/**', fn(Route $r) => $r->abort());
$page->unroute('**/api/user');
$page->unrouteAll();Handlers registered later take precedence. Page handlers run before context handlers. If no handler resolves a request, it continues to the network.
$page->on('console', fn(NativePlaywright\ConsoleMessage $m) => print("[{$m->type()}] {$m->text()}\n"));
$page->on('pageerror', fn(NativePlaywright\JSError $e) => print("JS error: {$e->message()}\n"));
$page->on('close', fn() => print("page closed\n"));
$page->once('load', fn() => print("loaded\n"));
$page->off('console');Waiting for an event caused by an action. The listener is registered before the action runs, so the event is never missed:
$msg = $page->expectConsoleMessage(fn() => $page->getByText('Log')->click());
$req = $page->expectRequest('**/track', fn() => $page->getByText('Buy')->click());
$err = $page->expectEvent('pageerror', fn() => $page->getByText('Break')->click());
// Wait for an event that matches a predicate
$page->waitForEvent('console', fn($m) => str_contains($m->text(), 'ready'), 10000);| Object | Events |
|---|---|
| Page | console, pageerror, dialog, popup, download, filechooser, request, response, requestfinished, requestfailed, load, domcontentloaded, frameattached, framenavigated, framedetached, close, crash |
| BrowserContext | page, close, request, response, requestfinished, requestfailed, console, dialog, weberror |
| Browser | disconnected |
Dialogs (alert / confirm / prompt / beforeunload): if there is no handler, the dialog is dismissed automatically, as in Playwright.
$page->on('dialog', fn(NativePlaywright\Dialog $d) => $d->accept('prompt value'));
$dialog = $page->expectDialog(fn() => $page->getByText('Delete')->click()); // handle the dialog yourselfPopups and new tabs:
$popup = $page->expectPopup(fn() => $page->getByText('Open in new tab')->click());
$popup->waitForLoadState();
echo $popup->title();
$newPage = $context->expectPage(fn() => $page->evaluate('() => window.open("/help")'));Downloads:
$download = $page->expectDownload(fn() => $page->getByText('Export CSV')->click());
$download->suggestedFilename(); // "report.csv"
$download->saveAs('/data/report.csv');
$download->path(); // temporary file; waits for completionUploads:
$page->getByLabel('Avatar')->setInputFiles('/path/avatar.png');
$page->locator('input[type=file]')->setInputFiles(['/a.pdf', '/b.pdf']);
$page->locator('input[type=file]')->setInputFiles([
'name' => 'data.csv', 'mimeType' => 'text/csv', 'buffer' => "a,b\n1,2",
]);
// Through the native file chooser
$chooser = $page->expectFileChooser(fn() => $page->getByText('Upload')->click());
$chooser->setFiles('/path/file.txt');$png = $page->screenshot(); // returns bytes
$page->screenshot(['path' => 'full.png', 'fullPage' => true]);
$page->screenshot(['path' => 'shot.jpg', 'type' => 'jpeg', 'quality' => 80]);
$page->screenshot(['clip' => ['x' => 0, 'y' => 0, 'width' => 400, 'height' => 300]]);
$page->screenshot(['omitBackground' => true]); // transparent background
$page->locator('.chart')->screenshot(['path' => 'chart.png']);
$page->pdf([
'path' => 'invoice.pdf',
'format' => 'A4', // Letter, Legal, A0–A6, ...
'landscape' => false,
'printBackground' => true,
'margin' => ['top' => '1cm', 'bottom' => '1cm', 'left' => '15mm', 'right' => '15mm'],
'displayHeaderFooter' => true,
'footerTemplate' => '<div style="font-size:8px;width:100%;text-align:center"><span class="pageNumber"></span></div>',
]);$context->cookies(); // all cookies
$context->cookies('https://example.com'); // cookies for a URL
$context->addCookies([
['name' => 'session', 'value' => 'abc', 'url' => 'https://example.com'],
['name' => 'lang', 'value' => 'en', 'domain' => '.example.com', 'path' => '/', 'httpOnly' => true],
]);
$context->clearCookies(['name' => 'session']);
$context->clearCookies();Log in once and reuse the session:
// First run: log in and save the state
$page->goto('/login');
$page->getByLabel('Email')->fill('me@example.com');
$page->getByLabel('Password')->fill('...');
$page->getByRole('button', ['name' => 'Sign in'])->click();
$page->waitForURL('**/dashboard');
$context->storageState(['path' => 'auth.json']);
// Later runs
$context = $browser->newContext(['storageState' => 'auth.json']);$page->exposeFunction('sha256', fn(string $s) => hash('sha256', $s));
$page->evaluate('async () => await window.sha256("hello")');
$context->exposeBinding('whoAmI', fn(array $source) => $source['page']->url());Functions are installed before the page's own scripts run, and they survive navigations.
$context->setDefaultTimeout(10000); // every action in the context
$context->setDefaultNavigationTimeout(20000);
$page->setDefaultTimeout(5000); // override at page level
$locator->click(['timeout' => 2000]); // override for one calluse NativePlaywright\Exception;
use NativePlaywright\TimeoutError;
try {
$page->getByText('Does not exist')->click(['timeout' => 1000]);
} catch (TimeoutError $e) {
// "locator.click: Timeout 1000ms exceeded.
// Call log:
// - waiting for internal:text="Does not exist"i"
} catch (Exception $e) {
// navigation errors, strict mode violations, closed pages, ...
}TimeoutError extends NativePlaywright\Exception, which extends \RuntimeException.
Use this for Chrome features the API doesn't cover:
$cdp = $page->newCDPSession();
$cdp->send('Performance.enable');
$metrics = $cdp->send('Performance.getMetrics');
$cdp->on('Network.webSocketFrameReceived', fn(array $p) => print($p['response']['payloadData']));
$browserCdp = $browser->newBrowserCDPSession();Native Playwright detects when launch() is called inside a coroutine. In that case the transport uses Swoole's own reactor:
- Each call suspends only the calling coroutine and never blocks the worker.
- Many coroutines share one browser and run concurrently on different pages or contexts.
- Event handlers (
route,dialog,console…) run in their own coroutines.
use NativePlaywright\Playwright;
use function Swoole\Coroutine\run;
run(function () {
$browser = Playwright::chromium()->launch();
$wg = new Swoole\Coroutine\WaitGroup();
foreach (['https://a.com', 'https://b.com', 'https://c.com'] as $url) {
$wg->add();
go(function () use ($browser, $url, $wg) {
try {
$page = $browser->newPage(); // a dedicated context per task
$page->goto($url);
echo $url, ': ', $page->title(), PHP_EOL;
$page->close();
} finally {
$wg->done();
}
});
}
$wg->wait();
$browser->close();
});See the full example in examples/swoole-server.php.
$server->on('workerStart', function () use (&$browser) {
$browser = Playwright::chromium()->launch(); // one browser per worker
});
$server->on('request', function ($req, $res) use (&$browser) {
$context = $browser->newContext(); // isolation per request
try {
$page = $context->newPage();
$page->goto($req->get['url']);
$res->header('Content-Type', 'image/png');
$res->end($page->screenshot());
} finally {
$context->close();
}
});Rules:
- Launch in
workerStart, never before the fork. Each process needs its own browser. - Use one context per request and close it in
finally. A context is far cheaper than a new browser. - Don't share a
Browserbetween processes. - To force a transport, use
launch(['swoole' => true|false]).
| Playwright (JS) | Native Playwright (PHP) |
|---|---|
const browser = await chromium.launch() |
$browser = Playwright::chromium()->launch() |
await page.goto(url, { waitUntil: 'networkidle' }) |
$page->goto($url, ['waitUntil' => 'networkidle']) |
page.getByRole('button', { name: 'OK' }) |
$page->getByRole('button', ['name' => 'OK']) |
await locator.click() |
$locator->click() |
page.keyboard.press('Enter') |
$page->keyboard->press('Enter') |
page.on('console', m => ...) |
$page->on('console', fn($m) => ...) |
const [popup] = await Promise.all([page.waitForEvent('popup'), click()]) |
$popup = $page->expectPopup(fn() => ...) |
const resp = await page.waitForResponse('**/api') (with an action) |
$resp = $page->expectResponse('**/api', fn() => ...) |
await route.fulfill({ json }) |
$route->fulfill(['json' => ...]) |
await page.$eval(sel, fn) |
$page->evalOnSelector($sel, $fn) |
await page.$$eval(sel, fn) |
$page->evalOnSelectorAll($sel, $fn) |
devices['iPhone 13'] |
Playwright::devices('iPhone 13') |
Regex /abc/i |
String '/abc/i' |
Every call is synchronous; there is no await. Under Swoole, waiting only suspends the current coroutine.
Measured with make bench and make memory in Docker (linux/arm64, Chromium 156, chrome-headless-shell). Both sides use the same Chromium binary.
| Metric | Native Playwright | Playwright (Node) |
|---|---|---|
| Driver process | none | 1 Node process |
| Driver PSS | ~19 MB (whole PHP process) | ~145 MB |
| Chromium PSS, 5 pages / 5 contexts | ~261 MB | ~280 MB |
| Total RAM | ~280 MB | ~425 MB |
evaluate('1+1') per call |
~0.6 ms | ~1.6–2.2 ms |
goto (small page) |
11–17 ms | 12–20 ms |
| 1 MB request payload | ~18–23 ms | ~31–52 ms |
Measurements inside Docker on macOS are noisy; read them as relative. Rendering and JavaScript execution time are still determined by Chromium.
Why it is lighter:
- No intermediate Node process; data is serialized once.
- A pipe instead of a WebSocket: no port, no handshake, no frame masking.
chrome-headless-shellis preferred. Full Chromium used ~856 MB for 5 pages; headless-shell used ~257 MB.- Memory-saving default flags:
--in-process-gpu,--no-startup-window, site isolation off, background services disabled. - Page setup is pipelined (about 10 commands in one round trip). A click is also a single round trip.
- Events with no listener are dropped immediately, and finished requests are released.
┌──────────────── PHP process ────────────────┐ ┌──────── Chromium ────────┐
│ your code │ │ │
│ │ │ pipe │ browser ── renderer(s) │
│ native_playwright.so │ fd 3/4 │ │
│ ├─ Playwright API (PHP → TypePHP) │◄────────►│ CDP │
│ ├─ Transport (blocking | Swoole) │ JSON\0 │ │
│ └─ pipe.cc (spawn, poll, frame splitting) │ │ isolated world: │
└─────────────────────────────────────────────┘ │ selector engine │
└──────────────────────────┘
| Component | Role |
|---|---|
| src/native/pipe.cc | About 200 lines of C++: posix_spawn Chromium, non-blocking pipe fds 3/4, poll, split frames on \0 |
| src/NativePlaywright/Transport.php | Matches responses to requests and dispatches events. Reentrant: a handler can issue new commands while another command is waiting |
| src/NativePlaywright/BlockingTransport.php | CLI/FPM: waits with poll() in the C++ layer |
| src/NativePlaywright/SwooleTransport.php | One reader coroutine parks on the fd (System::waitEvent); calling coroutines park on a Channel |
| src/NativePlaywright/Injected.php | Selector engine (CSS, text, XPath, ARIA role, label…) and actionability checks. Runs in an isolated world, invisible to the page |
| Browser / Page / Locator… | Public API |
- Auto-attach with
waitForDebuggerOnStart: emulation, init scripts, routes and bindings are applied before the page runs its first line of JavaScript. - All PHP code is compiled to C++ by TypePHP. The PHP sources don't need to be deployed.
| Not supported yet | Workaround |
|---|---|
| Firefox, WebKit | Chromium only |
tracing, video recording, HAR (recordHar, routeFromHAR) |
Use on('request'/'response') or a CDPSession |
APIRequestContext (request.get/post) |
Use a PHP HTTP client (Guzzle, Swoole HTTP client); cookies are available from $context->cookies() |
route.fetch() |
Combine route->continue() with expectResponse() |
ElementHandle / JSHandle |
Use Locator |
clock, worker / service worker / WebSocket events |
Use a CDPSession |
connectOverCDP (attach to a running browser) |
Not supported (Native Playwright launches its own browser over a pipe) |
Playwright Test expect() assertions |
Use waitFor() or PHPUnit / Pest assertions |
Cross-origin iframes with siteIsolation => true |
Keep the default siteIsolation => false |
Note: Native Playwright disables site isolation by default to save RAM. If you use Native Playwright to browse untrusted content, consider turning it back on.
| Symptom | Cause and fix |
|---|---|
Chromium not found |
Install Chrome and give its path: see Installing Chrome |
configure: error: gmp.h not found |
Install libgmp-dev libmpfr-dev (or pass --with-gmp-dir=PREFIX) |
| The extension fails to load with an API version mismatch | Reinstall with PIE/PECL for the PHP binary you run (pie install uses the php on your PATH) |
| Chromium exits immediately when running as root | Keep chromiumSandbox => false (the default) |
strict mode violation |
The locator matches several elements; narrow it with first(), nth() or filter() |
Timeout ... exceeded with element is not visible / not enabled / intercepts pointer events |
The last line of the call log shows which condition wasn't met |
| High RAM usage | Use chrome-headless-shell, close contexts when done, and don't launch a new browser per task |
| Hangs in a Swoole server | Don't launch before the fork; always launch in workerStart |
| Segmentation fault at exit when using Swoole | Xdebug is loaded. Swoole is incompatible with Xdebug (it crashes even without Native Playwright); run Swoole processes with -d xdebug.mode=off, or don't load Xdebug at all |
make image PHP=8.5 # toolchain image (TypePHP + PHPX + Swoole + chrome-headless-shell)
make dist # regenerate ext/ (phpize tree for PECL/PIE) from src/
make dist-test # build ext/ with phpize and run the e2e suite
make build PHP=8.5 # build/php8.5/native_playwright.so
make test PHP=8.5 # e2e tests: blocking + Swoole modes
make all # build + test on PHP 8.4 and 8.5
make bench # latency comparison with Playwright (Node)
make memory # RAM comparison with Playwright (Node)
make shell # shell inside the imageLayout:
src/native/ C++ for syscalls + stub declarations for TypePHP
ext/ generated phpize source tree (PECL/PIE build-path) - run `make dist`, do not edit
tools/ make-dist.sh, config.m4 template, package.xml generator
src/NativePlaywright/ the whole API (PHP, compiled by TypePHP)
tests/e2e.php end-to-end suite (35 scenarios, 2 local origins)
tests/www/ HTML/PHP fixtures used by the tests
bench/ latency and RAM benchmarks against Playwright (Node)
examples/ basic example and a Swoole HTTP server
project.yml TypePHP configuration (mode: ext)
Dockerfile toolchain (ARG PHP_VERSION=8.4|8.5)
Contribution guidelines:
- Write new logic in PHP under
src/NativePlaywright/. Only add C++ when a syscall is needed. - Don't use another extension's constants in compiled code; use the numeric value with a comment.
- Every new feature needs a scenario in
tests/e2e.phpthat passes in both modes (blocking and Swoole). - Run
make distand commitext/together with changes tosrc/.
- Bump
versioninproject.yml, then runmake dist(this updatesext/package.xml). - Commit, then tag:
git tag v0.1.0 && git push --tags. - The release workflow builds
native_playwright-<version>.tgz(PECL) and attaches it to the GitHub release. Packagist picks up the tag for PIE.