From 6b1e8474e5eb3801a0177f954c1538c09dc1b631 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Simon=20Andr=C3=A9?= Date: Thu, 13 Aug 2026 04:27:28 +0200 Subject: [PATCH] Fix device examples --- README.md | 106 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 61 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index 396a049..b7f0c60 100644 --- a/README.md +++ b/README.md @@ -3,16 +3,14 @@   ![PHP Version](https://img.shields.io/badge/PHP-8.2+-05971B?labelColor=09161E&color=1D8D23&logoColor=FFFFFF)   ![CI](https://img.shields.io/github/actions/workflow/status/playwright-php/devices/CI.yaml?branch=main&label=Tests&color=1D8D23&labelColor=09161E&logoColor=FFFFFF) -  ![Release](https://img.shields.io/github/v/release/playwright-php/devices?label=Stable&labelColor=09161E&color=1D8D23&logoColor=FFFFFF) +  [![Release](https://img.shields.io/github/v/release/playwright-php/devices?label=Stable&labelColor=09161E&color=1D8D23&logoColor=FFFFFF)](https://packagist.org/packages/playwright-php/devices)   ![License](https://img.shields.io/github/license/playwright-php/devices?label=License&labelColor=09161E&color=1D8D23&logoColor=FFFFFF) -# Playwright PHP: Device Descriptors +# Playwright PHP Devices -This package provides the official [device descriptors](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/deviceDescriptorsSource.json) -from [Microsoft Playwright](https://github.com/microsoft/playwright) for use -with [Playwright PHP](https://playwright-php.dev). +Use Microsoft Playwright's device descriptors from PHP for repeatable viewport, user agent, touch, and mobile emulation. ## Installation @@ -20,65 +18,83 @@ with [Playwright PHP](https://playwright-php.dev). composer require playwright-php/devices ``` -## Usage +The package requires PHP 8.2+. Install `playwright-php/playwright` as well when using descriptors in browser automation. -### Device Registry +## Quick Start + +Load a descriptor by its upstream Playwright device name: ```php use Playwright\Device\DeviceRegistry; $device = (new DeviceRegistry())->get('iPhone 15 Pro'); -``` -### Device descriptor +echo $device->getName(); +echo $device->getUserAgent(); +``` -The returned `$device` is an instance of `Playwright\Device\Device`, -with the following methods: +Use its properties when creating a Playwright browser context: ```php -$device->getName(); // 'iPhone 15 Pro' -$device->getUserAgent(); // 'Mozilla/5.0 (iPhone; CPU [...]' -$device->getViewport(); // ['width' => 393, 'height' => 659] -$device->getScreen(); // ['width' => 393, 'height' => 852] -$device->getDeviceScaleFactor(); // 3 -$iphone->isMobile(); // true -$iphone->hasTouch(); // true -$iphone->getDefaultBrowserType(); // 'webkit' +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(); ``` -### Browser emulation +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: ```php -// Pass the device properties to a new browser context: -$browser->newContext([ - 'userAgent' => $iphone->getUserAgent(), - 'viewport' => $iphone->getViewport(), - 'isMobile' => $iphone->isMobile(), - 'hasTouch' => $iphone->hasTouch(), -]); +$landscape = $device->landscape(); -// Or more simply: -$browser->newContext($iphone->toArray()); +echo $landscape->getViewport()['width']; ``` +Calling `landscape()` on a descriptor without landscape data throws an `InvalidArgumentException`. + ## Catalog -| Device | Browser | Screen | Scale | Viewport | Landscape | Mobile | Touch | -|-----------------------|----------|-------------|-------|------------|------------|--------|-------| -| Desktop Chrome | Chromium | 1920 x 1080 | 1 | 1280 x 720 | | No | No | -| Desktop Chrome HiDPI | Chromium | 1792 x 1120 | 2 | 1280 x 720 | | No | No | -| Desktop Edge | Chromium | 1920 x 1080 | 1 | 1280 x 720 | | No | No | -| Desktop Edge HiDPI | Chromium | 1792 x 1120 | 2 | 1280 x 720 | | No | No | -| Desktop Firefox | Firefox | 1920 x 1080 | 1 | 1280 x 720 | | No | No | -| Desktop Firefox HiDPI | Firefox | 1792 x 1120 | 2 | 1280 x 720 | | No | No | -| Desktop Safari | Webkit | 1792 x 1120 | 2 | 1280 x 720 | | No | No | -| Blackberry PlayBook | Webkit | n/a | 1 | 600 x 1024 | 1024 x 600 | Yes | Yes | -| BlackBerry Z30 | Webkit | n/a | 2 | 360 x 640 | 640 x 360 | Yes | Yes | -| Galaxy A55 | Chromium | n/a | 2.25 | 480 x 1040 | 1040 x 480 | Yes | Yes | - -Explore the full list of devices in [`docs/DEVICES.md`](docs/DEVICES.md). +Use `DeviceRegistry::has()` to check a name and `DeviceRegistry::all()` to retrieve the complete catalog. + +The generated [device catalog](docs/DEVICES.md) lists every available descriptor and its browser, screen, viewport, scale, mobile, and touch values. + +Device descriptors emulate browser-visible properties. They do not reproduce physical hardware, operating-system UI, network conditions, or device performance. + +## Documentation + +- [Device catalog](docs/DEVICES.md) +- [Playwright PHP Getting Started](https://github.com/playwright-php/playwright/blob/main/docs/guide/getting-started.md) + +## Contributing + +Contributions are welcome. Before submitting a pull request, run: + +```bash +composer validate --strict +vendor/bin/php-cs-fixer fix --dry-run --diff +vendor/bin/phpstan analyse +vendor/bin/phpunit +``` ## License -This package is released by the [Playwright PHP](https://playwright-php.dev) -project under the MIT License. See the [LICENSE](LICENSE) file for details. +Playwright PHP Devices is released under the [MIT License](LICENSE).