Fix device examples

README.md

@@ -3,82 +3,98 @@
 
   ![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)
 
 </div>
 
-# 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
 
 ```bash
 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).