README

Playwright PHP Devices

Use Microsoft Playwright's device descriptors from PHP for repeatable viewport, user agent, touch, and mobile emulation.

Installation

composer require playwright-php/devices

The package requires PHP 8.2+. Install playwright-php/playwright as well when using descriptors in browser automation.

Quick Start

Load a descriptor by its upstream Playwright device name:

use Playwright\Device\DeviceRegistry;

$device = (new DeviceRegistry())->get('iPhone 15 Pro');

echo $device->getName();
echo $device->getUserAgent();

Use its properties when creating a Playwright browser context:

use Playwright\Playwright;

$context = Playwright::webkit([
    'context' => [
        'userAgent' => $device->getUserAgent(),
        'viewport' => $device->getViewport(),
        'screen' => $device->getScreen(),
        'deviceScaleFactor' => $device->getDeviceScaleFactor(),
        'isMobile' => $device->isMobile(),
        'hasTouch' => $device->hasTouch(),
    ],
]);

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

echo $page->title();

$context->close();

The descriptor exposes its preferred browser engine through getDefaultBrowserType(). Choose the matching Playwright engine when browser-specific behavior matters.

Orientation

Descriptors that provide a landscape viewport can be changed without mutating the original object:

$landscape = $device->landscape();

echo $landscape->getViewport()['width'];

Calling landscape() on a descriptor without landscape data throws an InvalidArgumentException.

Catalog

Use DeviceRegistry::has() to check a name and DeviceRegistry::all() to retrieve the complete catalog.

The generated device catalog lists every available descriptor and its browser, screen, viewport, scale, mobile, and touch values.

Each catalog is generated from an explicit stable Playwright release. The source version is recorded in data/playwright-version.txt; generation never follows Playwright's moving main branch.

This package follows SemVer independently of Playwright. A catalog update is released as a new minor version because it changes the public descriptor data; matching Playwright and package version numbers is not implied.

Device descriptors emulate browser-visible properties. They do not reproduce physical hardware, operating-system UI, network conditions, or device performance.

Documentation

• Device catalog
• Playwright PHP Getting Started

Contributing

Contributions are welcome. Before submitting a pull request, run:

composer validate --strict
vendor/bin/php-cs-fixer fix --dry-run --diff
vendor/bin/phpstan analyse
vendor/bin/phpunit

To refresh the catalog for a stable Playwright release:

php bin/update-devices.php
php bin/update-docs.php
vendor/bin/php-cs-fixer fix

Verify the committed catalog without modifying it:

php bin/check-devices.php

Both commands resolve the latest stable Playwright version from npm. Pass --playwright-version=1.63.0 only when reproducing a specific historical snapshot.

The nightly workflow runs the check automatically. It fails when the recorded source version is behind or when the committed catalog does not match its recorded release.

License

Playwright PHP Devices is released under the MIT License.