Add ModifierKey and controlClick utils

src/Exception/InvalidArgumentException.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the playwright-php/playwright package.
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace PlaywrightPHP\Exception;
+
+/**
+ * @author Simon André <smn.andre@gmail.com>
+ */
+class InvalidArgumentException extends \InvalidArgumentException implements PlaywrightExceptionInterface
+{
+}

src/Input/ModifierKey.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the playwright-php/playwright package.
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace PlaywrightPHP\Input;
+
+use PlaywrightPHP\Exception\InvalidArgumentException;
+
+/**
+ * @author Simon André <smn.andre@gmail.com>
+ */
+enum ModifierKey: string
+{
+    case Alt = 'Alt';
+    case Control = 'Control';
+    case Meta = 'Meta';
+    case Shift = 'Shift';
+
+    public static function fromString(string $modifier): self
+    {
+        return match (strtolower($modifier)) {
+            'alt' => self::Alt,
+            'control', 'ctrl' => self::Control,
+            'meta', 'cmd', 'command' => self::Meta,
+            'shift' => self::Shift,
+            default => throw new InvalidArgumentException(sprintf('Unknown modifier key: "%s".', $modifier)),
+        };
+    }
+}

src/Network/Request.php

@@ -27,7 +27,7 @@ public function __construct(
 
     public function url(): string
     {
-        $url = $this->data['url'];
+        $url = $this->data['url'] ?? null;
         if (!is_string($url)) {
             throw new ProtocolErrorException('Invalid URL in request data', 0);
         }
@@ -37,17 +37,20 @@ public function url(): string
 
     public function method(): string
     {
-        $method = $this->data['method'];
+        $method = $this->data['method'] ?? null;
         if (!is_string($method)) {
             throw new ProtocolErrorException('Invalid method in request data', 0);
         }
 
         return $method;
     }
 
+    /**
+     * @return array<string, string>
+     */
     public function headers(): array
     {
-        $headers = $this->data['headers'];
+        $headers = $this->data['headers'] ?? [];
         if (!is_array($headers)) {
             return [];
         }
@@ -59,7 +62,6 @@ public function headers(): array
             }
         }
 
-        /* @var array<string, string> $stringHeaders */
         return $stringHeaders;
     }
 
@@ -77,26 +79,22 @@ public function postDataJSON(): ?array
             return null;
         }
 
-        $decoded = json_decode($postData, true);
-
-        if (!is_array($decoded)) {
+        if (!json_validate($postData)) {
             return null;
         }
 
-        $result = [];
-        foreach ($decoded as $key => $value) {
-            if (!is_string($key)) {
-                return null;
-            }
-            $result[$key] = $value;
+        $decoded = json_decode($postData, false, 512, JSON_THROW_ON_ERROR);
+
+        if (!$decoded instanceof \stdClass) {
+            return null;
         }
 
-        return $result;
+        return (array) $decoded;
     }
 
     public function resourceType(): string
     {
-        $resourceType = $this->data['resourceType'];
+        $resourceType = $this->data['resourceType'] ?? null;
         if (!is_string($resourceType)) {
             throw new ProtocolErrorException('Invalid resourceType in request data', 0);
         }

src/Page/Page.php

@@ -26,6 +26,7 @@
 use PlaywrightPHP\Frame\FrameLocatorInterface;
 use PlaywrightPHP\Input\Keyboard;
 use PlaywrightPHP\Input\KeyboardInterface;
+use PlaywrightPHP\Input\ModifierKey;
 use PlaywrightPHP\Input\Mouse;
 use PlaywrightPHP\Input\MouseInterface;
 use PlaywrightPHP\Locator\Locator;
@@ -45,8 +46,11 @@
 final class Page implements PageInterface, EventDispatcherInterface
 {
     private KeyboardInterface $keyboard;
+
     private MouseInterface $mouse;
+
     private PageEventHandlerInterface $eventHandler;
+
     private LoggerInterface $logger;
 
     public function __construct(
@@ -287,6 +291,30 @@ public function click(string $selector, array $options = []): self
         return $this;
     }
 
+    /**
+     * @param array<string, mixed> $options
+     */
+    public function altClick(string $selector, array $options = []): self
+    {
+        return $this->click($selector, [...$options, 'modifiers' => ModifierKey::Alt]);
+    }
+
+    /**
+     * @param array<string, mixed> $options
+     */
+    public function controlClick(string $selector, array $options = []): self
+    {
+        return $this->click($selector, [...$options, 'modifiers' => ModifierKey::Control]);
+    }
+
+    /**
+     * @param array<string, mixed> $options
+     */
+    public function shiftClick(string $selector, array $options = []): self
+    {
+        return $this->click($selector, [...$options, 'modifiers' => ModifierKey::Shift]);
+    }
+
     /**
      * @param array<string, mixed> $options
      */

src/Page/PageInterface.php

@@ -35,6 +35,21 @@ public function goto(string $url, array $options = []): ?ResponseInterface;
      */
     public function click(string $selector, array $options = []): self;
 
+    /**
+     * @param array<string, mixed> $options
+     */
+    public function altClick(string $selector, array $options = []): self;
+
+    /**
+     * @param array<string, mixed> $options
+     */
+    public function controlClick(string $selector, array $options = []): self;
+
+    /**
+     * @param array<string, mixed> $options
+     */
+    public function shiftClick(string $selector, array $options = []): self;
+
     /**
      * @param array<string, mixed> $options
      */
@@ -63,7 +78,8 @@ public function context(): BrowserContextInterface;
     /**
      * @param array<string>|null $urls
      *
-     * @return array<array{name: string, value: string, domain: string, path: string, expires: int, httpOnly: bool, secure: bool, sameSite: 'Strict'|'Lax'|'None'}>
+     * @return array<array{name: string, value: string, domain: string, path: string, expires: int, httpOnly: bool,
+     *                           secure: bool, sameSite: 'Strict'|'Lax'|'None'}>
      */
     public function cookies(?array $urls = null): array;
 

tests/Unit/Input/ModifierKeyTest.php

@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the playwright-php/playwright package.
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace PlaywrightPHP\Tests\Unit\Input;
+
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\TestCase;
+use PlaywrightPHP\Exception\InvalidArgumentException;
+use PlaywrightPHP\Input\ModifierKey;
+
+#[CoversClass(ModifierKey::class)]
+final class ModifierKeyTest extends TestCase
+{
+    public function testEnumValues(): void
+    {
+        $this->assertSame('Alt', ModifierKey::Alt->value);
+        $this->assertSame('Control', ModifierKey::Control->value);
+        $this->assertSame('Meta', ModifierKey::Meta->value);
+        $this->assertSame('Shift', ModifierKey::Shift->value);
+    }
+
+    #[DataProvider('provideFromStringData')]
+    public function testFromString(ModifierKey $expected, string $input): void
+    {
+        $this->assertSame($expected, ModifierKey::fromString($input));
+    }
+
+    public static function provideFromStringData(): array
+    {
+        return [
+            'alt lowercase' => [ModifierKey::Alt, 'alt'],
+            'alt uppercase' => [ModifierKey::Alt, 'Alt'],
+            'control lowercase' => [ModifierKey::Control, 'control'],
+            'control uppercase' => [ModifierKey::Control, 'Control'],
+            'control short' => [ModifierKey::Control, 'ctrl'],
+            'meta lowercase' => [ModifierKey::Meta, 'meta'],
+            'meta uppercase' => [ModifierKey::Meta, 'Meta'],
+            'meta cmd' => [ModifierKey::Meta, 'cmd'],
+            'meta command' => [ModifierKey::Meta, 'command'],
+            'shift lowercase' => [ModifierKey::Shift, 'shift'],
+            'shift uppercase' => [ModifierKey::Shift, 'Shift'],
+        ];
+    }
+
+    public function testFromStringWithInvalidModifier(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Unknown modifier key: "invalid".');
+
+        ModifierKey::fromString('invalid');
+    }
+}