Add Options classes (Page, Locator, Selector, Tracing, Websocket, ...) (#56)

Introduces a set of new options classes under the
`Playwright\**\Options` namespaces to encapsulate and validate options
parameters.

Author: smnandre

src/FileChooser/FileChooser.php

@@ -14,6 +14,7 @@
 
 namespace Playwright\FileChooser;
 
+use Playwright\FileChooser\Options\SetFilesOptions;
 use Playwright\Page\PageInterface;
 use Playwright\Transport\TransportInterface;
 
@@ -50,10 +51,11 @@ public function page(): PageInterface
 
     /**
      * @param string|array<string>|array{name: string, mimeType: string, buffer: string}|array<array{name: string, mimeType: string, buffer: string}> $files
-     * @param array{noWaitAfter?: bool, timeout?: int}                                                                                                $options
+     * @param array<string, mixed>|SetFilesOptions                                                                                                    $options
      */
-    public function setFiles(string|array $files, array $options = []): void
+    public function setFiles(string|array $files, array|SetFilesOptions $options = []): void
     {
+        $options = SetFilesOptions::from($options);
         $normalizedFiles = $this->normalizeFiles($files);
 
         $payload = [
@@ -62,8 +64,9 @@ public function setFiles(string|array $files, array $options = []): void
             'files' => $normalizedFiles,
         ];
 
-        if (!empty($options)) {
-            $payload['options'] = $options;
+        $optionsArray = $options->toArray();
+        if (!empty($optionsArray)) {
+            $payload['options'] = $optionsArray;
         }
 
         $fileChooserId = $this->data['fileChooserId'] ?? null;

src/FileChooser/FileChooserInterface.php

@@ -14,6 +14,7 @@
 
 namespace Playwright\FileChooser;
 
+use Playwright\FileChooser\Options\SetFilesOptions;
 use Playwright\Page\PageInterface;
 
 /**
@@ -42,9 +43,7 @@ public function page(): PageInterface;
      * For empty array, clears the selected files.
      *
      * @param string|array<string>|array{name: string, mimeType: string, buffer: string}|array<array{name: string, mimeType: string, buffer: string}> $files
-     * @param array{noWaitAfter?: bool, timeout?: int}                                                                                                $options
-     * @param string|string[]|array{name: string, mimeType: string, buffer: string}|array<array{name: string, mimeType: string, buffer: string}>      $files
-     * @param array<string, mixed>                                                                                                                    $options
+     * @param array<string, mixed>|SetFilesOptions                                                                                                    $options
      */
-    public function setFiles(string|array $files, array $options = []): void;
+    public function setFiles(string|array $files, array|SetFilesOptions $options = []): void;
 }

src/FileChooser/Options/SetFilesOptions.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the community-maintained Playwright PHP project.
+ * It is not affiliated with or endorsed by Microsoft.
+ *
+ * (c) 2025-Present - Playwright PHP - https://github.com/playwright-php
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Playwright\FileChooser\Options;
+
+final readonly class SetFilesOptions
+{
+    public function __construct(
+        public ?bool $noWaitAfter = null,
+        public ?float $timeout = null,
+    ) {
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function toArray(): array
+    {
+        $options = [];
+        if (null !== $this->noWaitAfter) {
+            $options['noWaitAfter'] = $this->noWaitAfter;
+        }
+        if (null !== $this->timeout) {
+            $options['timeout'] = $this->timeout;
+        }
+
+        return $options;
+    }
+
+    /**
+     * @param array<string, mixed>|self $options
+     */
+    public static function from(array|self $options = []): self
+    {
+        if ($options instanceof self) {
+            return $options;
+        }
+
+        /** @var bool|null $noWaitAfter */
+        $noWaitAfter = $options['noWaitAfter'] ?? null;
+        /** @var float|int|null $timeoutValue */
+        $timeoutValue = $options['timeout'] ?? null;
+        $timeout = null !== $timeoutValue ? (float) $timeoutValue : null;
+
+        return new self($noWaitAfter, $timeout);
+    }
+}