Chrome PHP

https://github.com/chrome-php/chrome
Admin
A PHP library to programmatically control Chrome/Chromium in headless mode, allowing for web...
Tokens:57,050
Snippets:403
Trust Score:8.3
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install chrome-php/chrome via Composer

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Use this command to install the library with Composer. Requires PHP 7.4-8.5 and a Chrome/Chromium 65+ executable.

```bash
$ composer require chrome-php/chrome
```

--------------------------------

### Evaluate script and get return value

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Complete example of navigating, waiting for navigation, evaluating a script in the browser, and retrieving the return value.

```php
// navigate
$navigation = $page->navigate('http://example.com');

// wait for the page to be loaded
$navigation->waitForNavigation();

// evaluate script in the browser
$evaluation = $page->evaluate('document.documentElement.innerHTML');

// wait for the value to return and get it
$value = $evaluation->getReturnValue();
```

--------------------------------

### Navigate to a URL and wait for navigation

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Basic navigation example. Calls navigate() and then waitForNavigation() to wait for the page to load. The default wait is 30 seconds for the 'loaded' event.

```php
// navigate
$navigation = $page->navigate('http://example.com');

// wait for the page to be loaded
$navigation->waitForNavigation();
```

--------------------------------

### Keyboard API: type raw key and text

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Types like a real user using the keyboard API. The example types a raw key (Tab) and then text.

```php
$page->keyboard()
    ->typeRawKey('Tab') // type a raw key, such as Tab
    ->typeText('bar');  // type the text "bar"
```

--------------------------------

### Basic usage: create browser, navigate, screenshot, PDF

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Starts headless Chrome, creates a page, navigates to a URL, retrieves the page title, takes a screenshot, generates a PDF, and closes the browser. The browser is closed in a finally block to ensure cleanup.

```php
use HeadlessChromium\BrowserFactory;

$browserFactory = new BrowserFactory();

// starts headless Chrome
$browser = $browserFactory->createBrowser();

try {
    // creates a new page and navigate to an URL
    $page = $browser->createPage();
    $page->navigate('http://example.com')->waitForNavigation();

    // get page title
    $pageTitle = $page->evaluate('document.title')->getReturnValue();

    // screenshot - Say "Cheese"! 😄
    $page->screenshot()->saveToFile('/foo/bar.png');

    // pdf
    $page->pdf(['printBackground' => false])->saveToFile('/foo/bar.pdf');
} finally {
    // bye
    $browser->close();
}
```

--------------------------------

### Set a Pre-Script for Pages with $browser->setPagePreScript()

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Sets a script to be evaluated before every page created by this browser navigates. The example overrides the navigator.permissions.query to simulate notification permissions.

```php
$browser->setPagePreScript('// Simulate navigator permissions;
const originalQuery = window.navigator.permissions.query;
window.navigator.permissions.query = (parameters) => (
    parameters.name === 'notifications' ?
        Promise.resolve({ state: Notification.permission }) :
        originalQuery(parameters)
);');
```

--------------------------------

### Persist options with setOptions and addOptions

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Options set via setOptions and addOptions persist across browser creations. addOptions merges new options, and later values override earlier ones for the same key. The example shows how windowSize and enableImages are applied to subsequent browsers.

```php
$browserFactory->setOptions([
    'windowSize' => [1920, 1000],
]);

// both browser will have the same 'windowSize' option
$browser1 = $browserFactory->createBrowser();
$browser2 = $browserFactory->createBrowser();

$browserFactory->addOptions(['enableImages' => false]);

// this browser will have both the 'windowSize' and 'enableImages' options
$browser3 = $browserFactory->createBrowser();

$browserFactory->addOptions(['enableImages' => true]);

// this browser will have the previous 'windowSize', but 'enableImages' will be true
$browser4 = $browserFactory->createBrowser();
```

--------------------------------

### Keyboard API: set key interval

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Adds a delay between keystrokes to impersonate a real user. The example sets a delay of 10 milliseconds.

```php
$page->keyboard()->setKeyInterval(10); // sets a delay of 10 milliseconds between keystrokes
```

--------------------------------

### Cookie API: get cookies

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Gets cookies for a page. Two examples: getting all cookies for the browser, and getting cookies for the current page after navigation. Also shows filtering by name and finding a single cookie.

```php
use HeadlessChromium\Cookies\Cookie;

$page = $browser->createPage();

// example 1: get all cookies for the browser

$cookies = $page->getAllCookies();

// example 2: get cookies for the current page

$page->navigate('http://example.com')->waitForNavigation();
$cookies = $page->getCookies();

// filter cookies with name == 'foo'
$cookiesFoo = $cookies->filterBy('name', 'foo');

// find first cookie with name == 'bar'
$cookieBar = $cookies->findOneBy('name', 'bar');
if ($cookieBar) {
    // do something
}
```

--------------------------------

### Keyboard API: key combinations

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Sends key combinations such as ctrl+v using press, type, and release. Key names are case insensitive and trimmed. The example shows selecting all text with ctrl+a and copying/pasting with ctrl+c and ctrl+v.

```php
// ctrl + a to select all text
$page->keyboard()
    ->press('control') // key names are case insensitive and trimmed
        ->type('a')    // press and release
    ->release('Control');

// ctrl + c to copy and ctrl + v to paste it twice
$page->keyboard()
    ->press('Ctrl') // alias for Control
        ->type('c')
        ->type('V') // upper and lower cases should behave the same way
    ->release();    // release all
```

--------------------------------

### Get page HTML

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Retrieves the current page HTML as a string using the getHtml() method.

```php
$html = $page->getHtml();
```

--------------------------------

### Mouse API: move, click, and scroll

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Controls mouse movement, clicks, and scrolling. The mouse API is dependent on the page instance. The example shows moving to coordinates, clicking, moving with steps, right-clicking, and waiting for page reload after a click on a link.

```php
$page->mouse()
    ->move(10, 20)                             // Moves mouse to position x=10; y=20
    ->click()                                  // left-click on position set above
    ->move(100, 200, ['steps' => 5])           // move mouse to x=100; y=200 in 5 equal steps
    ->click(['button' => Mouse::BUTTON_RIGHT]; // right-click on position set above

// given the last click was on a link, the next step will wait
// for the page to load after the link was clicked
$page->waitForReload();
```

--------------------------------

### Cookie API: set cookies

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Sets cookies for a page. Two examples: setting cookies for a given domain with an expiration, and setting cookies for the current page after navigation.

```php
use HeadlessChromium\Cookies\Cookie;

$page = $browser->createPage();

// example 1: set cookies for a given domain

$page->setCookies([
    Cookie::create('name', 'value', [
        'domain' => 'example.com',
        'expires' => time() + 3600 // expires in 1 hour
    ])
])->await();


// example 2: set cookies for the current page

$page->navigate('http://example.com')->waitForNavigation();

$page->setCookies([
    Cookie::create('name', 'value', ['expires'])
])->await();
```

--------------------------------

### Element::getText

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Gets the text content of the element.

```APIDOC
## Element::getText

### Description
Gets the text content of the element.

### Method
Element::getText

### Parameters
None.

### Request Example
```php
$text = $elem->getText();
```

### Response
Returns the text content as a string.
```

--------------------------------

### Get element text or attribute

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Retrieves the text content of the element and the value of its 'class' attribute.

```php
$text = $elem->getText();
$attr = $elem->getAttribute('class');
```

--------------------------------

### Element::getAttribute

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Gets the value of an attribute of the element.

```APIDOC
## Element::getAttribute

### Description
Gets the value of an attribute of the element.

### Method
Element::getAttribute

### Parameters
- **name** (string) - Required - The attribute name.

### Request Example
```php
$attr = $elem->getAttribute('class');
```

### Response
Returns the attribute value as a string.
```

--------------------------------

### Add a pre-script to evaluate upon page navigation

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Use $page->addPreScript() to inject a JavaScript script that runs before page navigation. The example overrides the navigator.permissions.query method to simulate permissions. If the script requires the DOM to be fully populated, use the 'onLoad' option.

```php
$page->addPreScript('// Simulate navigator permissions;
const originalQuery = window.navigator.permissions.query;
window.navigator.permissions.query = (parameters) => (
    parameters.name === 'notifications' ?
        Promise.resolve({ state: Notification.permission }) :
        originalQuery(parameters)
);');
```

```php
$page->addPreScript($script, ['onLoad' => true]);
```

--------------------------------

### Persistent Browser Connection with BrowserFactory::connectToBrowser

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Shares a single Chrome instance across scripts by storing the WebSocket URI in a file. On first run, creates a browser with 'keepAlive' => true and saves the URI; on subsequent runs, connects to the existing instance. If the connection fails (BrowserConnectionFailed), starts a new browser and updates the file.

```php
use \HeadlessChromium\BrowserFactory;
use \HeadlessChromium\Exception\BrowserConnectionFailed;

$socketFile = '/tmp/chrome-php-demo-socket';

// path to the file to store websocket's uri
$socket = \file_get_contents($socketFile);

try {
    $browser = BrowserFactory::connectToBrowser($socket);
} catch (BrowserConnectionFailed $e) {
    // The browser was probably closed, start it again
    $factory = new BrowserFactory();
    $browser = $factory->createBrowser([
        'keepAlive' => true,
    ]);

    // save the uri to be able to connect again to browser
    \file_put_contents($socketFile, $browser->getSocketUri(), LOCK_EX);
}
```

--------------------------------

### Get Opened Pages (Tabs) with $browser->getPages()

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Retrieves the list of currently opened pages (tabs) in the browser. Useful for iterating over existing tabs.

```php
$pages = $browser->getPages();
```

--------------------------------

### Find all elements on a page by XPath selector

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Creates a page, navigates to example.com, waits for navigation, and searches for elements matching the XPath '//div/*/a'.

```php
$page = $browser->createPage();
$page->navigate('http://example.com')->waitForNavigation();

$elem = $page->dom()->search('//div/*/a');
```

--------------------------------

### Create browser with per-instance options

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Options passed directly to createBrowser apply only to that browser instance. The default options are ignored for that creation. Subsequent calls without options use the factory defaults.

```php
use HeadlessChromium\BrowserFactory;

$browserFactory = new BrowserFactory();
$browser = $browserFactory->createBrowser([
    'windowSize'   => [1920, 1000],
    'enableImages' => false,
]);

// this browser will be created without any options
$browser2 = $browserFactory->createBrowser();
```

--------------------------------

### Find one element by CSS selector

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Creates a page, navigates to example.com, waits for navigation, and finds the first element matching the CSS selector '#index_email'.

```php
$page = $browser->createPage();
$page->navigate('http://example.com')->waitForNavigation();

$elem = $page->dom()->querySelector('#index_email');
```

--------------------------------

### Take a screenshot with $page->screenshot()

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Navigates to a page, waits for navigation, takes a screenshot with options (format, quality, optimizeForSpeed), and saves it to a file. The 'format' defaults to 'png' with possible values 'png', 'jpeg', 'webp'. 'quality' only applies to 'jpeg' or 'webp' and defaults to 100. 'optimizeForSpeed' defaults to false.

```php
// navigate
$navigation = $page->navigate('http://example.com');

// wait for the page to be loaded
$navigation->waitForNavigation();

// take a screenshot
$screenshot = $page->screenshot([
    'format'  => 'jpeg',  // default to 'png' - possible values: 'png', 'jpeg', 'webp'
    'quality' => 80,      // only when format is 'jpeg' or 'webp' - default 100
    'optimizeForSpeed' => true // default to 'false' - Optimize image encoding for speed, not for resulting size
]);

// save the screenshot
$screenshot->saveToFile('/some/place/file.jpg');
```

--------------------------------

### Create a standalone Browser from a WebSocket connection

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Creates a Connection to a Chrome DevTools WebSocket URI, connects, and then creates a Browser instance from that connection. This is for standalone browser usage without the higher-level BrowserFactory.

```php
use HeadlessChromium\Communication\Connection;
use HeadlessChromium\Browser;

// Chrome devtools URI
$webSocketUri = 'ws://127.0.0.1:9222/devtools/browser/xxx';

// create connection given a WebSocket URI
$connection = new Connection($webSocketUri);
$connection->connect();

// create browser
$browser = new Browser($connection);
```

--------------------------------

### Set HTTP authentication credentials with Page::authenticate

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Sets credentials to answer HTTP authentication challenges before navigating. If credentials are rejected, an AuthenticationFailed exception is thrown while waiting for navigation. The origin restricts credentials to that origin; omit it to answer every challenge. Intercepts requests via the DevTools fetch domain, so avoid combining with custom Fetch.enable usage.

```php
use HeadlessChromium\Exception\AuthenticationFailed;

try {
    $page->authenticate('username', 'password', 'https://example.com');
    $page->navigate('https://example.com/protected')->waitForNavigation();
} catch (AuthenticationFailed $e) {
    // invalid credentials
}
```

--------------------------------

### Navigate with custom referrer option

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Shows how to pass navigation options such as 'referrer' to the navigate() method. The options include strict, referrer, referrerPolicy, and transitionType.

```php
// navigate with a custom referrer
$navigation = $page->navigate('http://example.com', ['referrer' => 'https://google.com/']);
```

--------------------------------

### Create a New Page (Tab) with $browser->createPage()

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Creates a new page (tab) in the browser. Use this to open a new tab for navigation or scripting.

```php
$page = $browser->createPage();
```

--------------------------------

### Set download path for a page

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Sets the directory where downloaded files will be saved. Must be called after creating the page.

```php
// After creating a page.
$page->setDownloadPath('/path/to/save/downloaded/files');
```

--------------------------------

### Print page as PDF with $page->pdf()

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Generates a PDF of the current page with configurable options such as landscape, printBackground, displayHeaderFooter, preferCSSPageSize, margins, paper size, header/footer templates, and scale. The PDF can be saved to a file or streamed directly to the browser output.

```php
// navigate
$navigation = $page->navigate('http://example.com');

// wait for the page to be loaded
$navigation->waitForNavigation();

$options = [
    'landscape'           => true,             // default to false
    'printBackground'     => true,             // default to false
    'displayHeaderFooter' => true,             // default to false
    'preferCSSPageSize'   => true,             // default to false (reads parameters directly from @page)
    'marginTop'           => 0.0,              // defaults to ~0.4 (must be a float, value in inches)
    'marginBottom'        => 1.4,              // defaults to ~0.4 (must be a float, value in inches)
    'marginLeft'          => 5.0,              // defaults to ~0.4 (must be a float, value in inches)
    'marginRight'         => 1.0,              // defaults to ~0.4 (must be a float, value in inches)
    'paperWidth'          => 6.0,              // defaults to 8.5 (must be a float, value in inches)
    'paperHeight'         => 6.0,              // defaults to 11.0 (must be a float, value in inches)
    'headerTemplate'      => '<div>foo</div>', // see details above
    'footerTemplate'      => '<div>foo</div>', // see details above
    'scale'               => 1.2,              // defaults to 1.0 (must be a float)
];

// print as pdf (in memory binaries)
$pdf = $page->pdf($options);

// save the pdf
$pdf->saveToFile('/some/place/file.pdf');

// or directly output pdf without saving
header('Content-Description: File Transfer');
header('Content-Type: application/pdf');
header('Content-Disposition: inline; filename=filename.pdf');
header('Content-Transfer-Encoding: binary');
header('Expires: 0');
header('Cache-Control: must-revalidate, post-check=0, pre-check=0');
header('Pragma: public');

$outputStream = fopen('php://output', 'w');

$pdf->saveToStream($outputStream);

fclose($outputStream);
```

--------------------------------

### Connection::connect

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Establishes a connection to the Chrome DevTools WebSocket endpoint.

```APIDOC
## Connection::connect

### Description
Establishes a connection to the Chrome DevTools WebSocket endpoint.

### Method
Connection::connect

### Parameters
None.

### Request Example
```php
$connection = new Connection($webSocketUri);
$connection->connect();
```

### Response
No return value.
```

--------------------------------

### Debug options: connection delay and verbose logging

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Additional debug options for createBrowser: 'connectionDelay' adds a delay between instructions, and 'debugLogger' enables verbose mode. The debugLogger can be a resource string, a resource, or an object implementing Psr\Log\LoggerInterface.

```php
[
    'connectionDelay' => 0.8,            // add 0.8 second of delay between each instruction sent to Chrome,
    'debugLogger'     => 'php://stdout', // will enable verbose mode
]
```

--------------------------------

### Page::navigate

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Navigates the page to a given URL.

```APIDOC
## Page::navigate

### Description
Navigates the page to a given URL.

### Method
Page::navigate

### Parameters
- **url** (string) - Required - The URL to navigate to.

### Request Example
```php
$page->navigate('http://example.com');
```

### Response
Returns a navigation object with waitForNavigation method.
```

--------------------------------

### Connect to Chrome DevTools Protocol and send a message

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Creates a Connection to a Chrome DevTools WebSocket URI, connects, sends a 'Target.activateTarget' message, and waits up to 1000ms for a response. This is advanced usage that bypasses higher-level communication logic.

```php
use HeadlessChromium\Communication\Connection;
use HeadlessChromium\Communication\Message;

// Chrome devtools URI
$webSocketUri = 'ws://127.0.0.1:9222/devtools/browser/xxx';

// create a connection
$connection = new Connection($webSocketUri);
$connection->connect();

// send method "Target.activateTarget"
$responseReader = $connection->sendMessage(new Message('Target.activateTarget', ['targetId' => 'xxx']));

// wait up to 1000ms for a response
$response = $responseReader->waitForResponse(1000);
```

--------------------------------

### Keyboard API

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Simulates keyboard input, including raw keys, text, and key combinations.

```APIDOC
## Keyboard API

### Description
Provides methods to type text, press raw keys, and simulate key combinations.

### Methods
- **typeRawKey(key)** - Types a raw key, such as 'Tab'.
- **typeText(text)** - Types the given text.
- **setKeyInterval(milliseconds)** - Sets a delay between keystrokes.
- **press(key)** - Presses a key (case-insensitive).
- **type(key)** - Presses and releases a key.
- **release(key)** - Releases a key. If no key is specified, releases all pressed keys.

### Key Aliases
- Control: `Control`, `Ctrl`, `Ctr`
- Alt: `Alt`, `AltGr`, `Alt Gr`
- Meta: `Meta`, `Command`, `Cmd`
- Shift: `Shift`

### Request Example
```php
$page->keyboard()
    ->typeRawKey('Tab')
    ->typeText('bar');

$page->keyboard()->setKeyInterval(10);

$page->keyboard()
    ->press('control')
        ->type('a')
    ->release('Control');

$page->keyboard()
    ->press('Ctrl')
        ->type('c')
        ->type('V')
    ->release();
```

```

--------------------------------

### Click an element and send text

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Performs a click on the element and sends the text 'Sample text' to it using sendKeys.

```php
$elem->click();
$elem->sendKeys('Sample text');
```

--------------------------------

### Page::authenticate

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Sets credentials to answer HTTP authentication challenges. The origin restricts credentials to specific origins; omit to answer all challenges. Throws AuthenticationFailed if credentials are rejected.

```APIDOC
## Page::authenticate

### Description
Sets credentials to answer HTTP authentication challenges, such as basic authentication or proxy authentication. The origin restricts credentials to challenges from that origin; omit to answer every challenge. Throws AuthenticationFailed if credentials are rejected.

### Method
Page::authenticate

### Parameters
- **username** (string) - Required - The username for authentication.
- **password** (string) - Required - The password for authentication.
- **origin** (string) - Optional - The origin (scheme, host, port) to restrict credentials to. Omit to answer all challenges.

### Request Example
```php
$page->authenticate('username', 'password', 'https://example.com');
```

### Response
No return value. Throws AuthenticationFailed exception on rejection.

### Error Handling
- **AuthenticationFailed** - Thrown when credentials are rejected while waiting for navigation.
```

--------------------------------

### Use custom Chrome executable 'chromium-browser'

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Creates a BrowserFactory with a custom executable path. By default, the factory uses the CHROME_PATH environment variable or guesses the executable path; this overrides it with 'chromium-browser'.

```php
use HeadlessChromium\BrowserFactory;

// replace default 'chrome' with 'chromium-browser'
$browserFactory = new BrowserFactory('chromium-browser');
```

--------------------------------

### Set page HTML with default and custom options

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Shows how to set the page HTML using setHtml(). The first call uses defaults (3000ms timeout and 'load' event). The second call specifies a timeout of 10000ms and the Page::NETWORK_IDLE event. This method completely replaces the current page HTML.

```php
// Basic
$page->setHtml('<p>text</p>');

// Specific timeout & event
$page->setHtml('<p>text</p>', 10000, Page::NETWORK_IDLE);
```

--------------------------------

### Full-page screenshot with captureBeyondViewport

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Capture the full page layout (not just the viewport) by setting 'captureBeyondViewport' to true and using $page->getFullPageClip() as the clip. The 'format' option defaults to 'png' with possible values 'png', 'jpeg', 'webp'.

```php
// navigate
$navigation = $page->navigate('https://example.com');

// wait for the page to be loaded
$navigation->waitForNavigation();

$screenshot = $page->screenshot([
    'captureBeyondViewport' => true,
    'clip' => $page->getFullPageClip(),
    'format' => 'jpeg', // default to 'png' - possible values: 'png', 'jpeg', 'webp'
]);

// save the screenshot
$screenshot->saveToFile('/some/place/file.jpg');
```

--------------------------------

### Create a session and send a message to a target

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Creates a session for a given target ID using Connection::createSession (attachToTarget) and sends a 'Page.reload' message synchronously via Target.sendMessageToTarget.

```php
// given a target id
$targetId = 'yyy';

// create a session for this target (attachToTarget)
$session = $connection->createSession($targetId);

// send message to this target (Target.sendMessageToTarget)
$response = $session->sendMessageSync(new Message('Page.reload'));
```

--------------------------------

### navigate

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Navigates the page to a given URL and returns a Navigation object that can be used to wait for the page to load. Supports custom referrer and other options.

```APIDOC
## navigate

### Description
Navigates the page to the specified URL. Returns a Navigation object that can be used to wait for the page to load.

### Method
navigate

### Parameters
- **url** (string) - Required - The URL to navigate to.
- **options** (array) - Optional - An associative array with the following keys:
  - **referrer** (string) - Optional - The referrer URL to send with the navigation request.
  - **referrerPolicy** (string) - Optional - The referrer policy to use.
  - **transitionType** (string) - Optional - The transition type for the navigation.
  - **strict** (bool) - Optional - Whether to use strict mode.

### Return Value
Returns a Navigation object. Use `waitForNavigation()` on this object to wait for the page to load.

### Example
```php
$navigation = $page->navigate('http://example.com');
$navigation->waitForNavigation();
```

### Notes
- The `waitForNavigation()` method waits for the 'load' event by default, with a timeout of 30 seconds.
- You can specify a different event and timeout by passing arguments to `waitForNavigation()`.
- Available events: `Page::DOM_CONTENT_LOADED`, `Page::FIRST_CONTENTFUL_PAINT`, `Page::FIRST_IMAGE_PAINT`, `Page::FIRST_MEANINGFUL_PAINT`, `Page::FIRST_PAINT`, `Page::INIT`, `Page::INTERACTIVE_TIME`, `Page::LOAD`, `Page::NETWORK_IDLE`.
- Exceptions: `OperationTimedOut` if the page takes too long to load, `NavigationExpired` if the page is replaced during navigation.
```

--------------------------------

### Handle navigation timeout and expiration exceptions

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Shows how to catch OperationTimedOut and NavigationExpired exceptions when waiting for navigation. OperationTimedOut indicates the page took too long to load; NavigationExpired indicates the page was replaced by another page.

```php
use HeadlessChromium\Exception\OperationTimedOut;
use HeadlessChromium\Exception\NavigationExpired;

try {
    $navigation->waitForNavigation()
} catch (OperationTimedOut $e) {
    // too long to load
} catch (NavigationExpired $e) {
    // An other page was loaded
}
```

--------------------------------

### Close the Browser with $browser->close()

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Closes the browser instance. Use this to clean up resources when done.

```php
$browser->close();
```

--------------------------------

### getHtml

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Returns the current page HTML as a string.

```APIDOC
## getHtml

### Description
Returns the current page HTML as a string.

### Method
getHtml

### Parameters
None.

### Return Value
Returns a string containing the page HTML.

### Example
```php
$html = $page->getHtml();
```
```

--------------------------------

### Browser::createPage

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Creates a new page (tab) in the browser.

```APIDOC
## Browser::createPage

### Description
Creates a new page (tab) in the browser.

### Method
Browser::createPage

### Parameters
None.

### Request Example
```php
$page = $browser->createPage();
```

### Response
Returns a Page object.
```

--------------------------------

### BrowserFactory::createBrowser

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Creates a new browser instance. Options passed directly to this method are used only for that single browser creation, while options set via setOptions or addOptions persist across multiple creations.

```APIDOC
## BrowserFactory::createBrowser

### Description
Creates a new browser instance. Options passed directly to this method are used only for that single browser creation, while options set via setOptions or addOptions persist across multiple creations.

### Method
createBrowser

### Parameters
#### Options (array) - Optional
- **connectionDelay** (int) - Default: 0 - Delay to apply between each operation for debugging purposes
- **customFlags** (array) - Default: none - An array of flags to pass to the command line. Eg: ['--option1', '--option2=someValue']
- **debugLogger** (string|resource|PSR-3 logger) - Default: null - A string (e.g "php://stdout"), or resource, or PSR-3 logger instance to print debug messages
- **disableJavascript** (bool) - Default: false - Disable JavaScript execution on every page created via createPage()
- **disableNotifications** (bool) - Default: false - Disable browser notifications
- **enableImages** (bool) - Default: true - Toggles loading of images
- **envVariables** (array) - Default: none - An array of environment variables to pass to the process (example DISPLAY variable)
- **headers** (array) - Default: none - An array of custom HTTP headers
- **headless** (bool) - Default: true - Enable or disable headless mode
- **ignoreCertificateErrors** (bool) - Default: false - Set Chrome to ignore SSL errors
- **keepAlive** (bool) - Default: false - Set to true to keep alive the Chrome instance when the script terminates
- **noSandbox** (bool) - Default: false - Enable no sandbox mode, useful to run in a docker container
- **noProxyServer** (bool) - Default: false - Don't use a proxy server, always make direct connections. Overrides other proxy settings.
- **proxyBypassList** (string) - Default: none - Specifies a list of hosts for whom we bypass proxy settings and use direct connections
- **proxyServer** (string) - Default: none - Proxy server to use. usage: 127.0.0.1:8080 (authorisation with credentials does not work)
- **sendSyncDefaultTimeout** (int) - Default: 5000 - Default timeout (ms) for sending sync messages
- **startupTimeout** (int) - Default: 30 - Maximum time in seconds to wait for Chrome to start
- **userAgent** (string) - Default: none - User agent to use for the whole browser (see page API for alternative)
- **userDataDir** (string) - Default: none - Chrome user data dir (default: a new empty dir is generated temporarily)
- **userCrashDumpsDir** (string) - Default: none - The directory crashpad should store dumps in (crash reporter will be enabled automatically)
- **windowSize** (array) - Default: none - Size of the window. usage: $width, $height - see also Page::setViewport
- **excludedSwitches** (array) - Default: none - An array of Chrome flags that should be removed from the default set (example --enable-automation)

### Request Example
```php
$browserFactory = new BrowserFactory();
$browser = $browserFactory->createBrowser([
    'windowSize'   => [1920, 1000],
    'enableImages' => false,
]);
```

### Response
Returns a Browser instance.

```

--------------------------------

### Screenshot an area on a page using Clip

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Use the 'clip' option with a HeadlessChromium\Clip object to capture a specific rectangular area. The Clip constructor takes left corner coordinates (x, y) and width/height. The screenshot is saved to a file.

```php
use HeadlessChromium\Clip;

// navigate
$navigation = $page->navigate('http://example.com');

// wait for the page to be loaded
$navigation->waitForNavigation();

// create a rectangle by specifying to left corner coordinates + width and height
$x = 10;
$y = 10;
$width = 100;
$height = 100;
$clip = new Clip($x, $y, $width, $height);

// take the screenshot (in memory binaries)
$screenshot = $page->screenshot([
    'clip'  => $clip,
]);

// save the screenshot
$screenshot->saveToFile('/some/place/file.jpg');
```

--------------------------------

### Set viewport size with $page->setViewport()

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Changes the viewport size for the current page without affecting other pages. The method returns a promise-like object, so call ->await() to wait for the operation to complete.

```php
$width = 600;
$height = 300;
$page->setViewport($width, $height)
    ->await(); // wait for the operation to complete
```

--------------------------------

### Connection::createSession

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Creates a session for a given target ID, attaching to the target.

```APIDOC
## Connection::createSession

### Description
Creates a session for a given target ID, attaching to the target.

### Method
Connection::createSession

### Parameters
- **targetId** (string) - Required - The target ID to attach to.

### Request Example
```php
$session = $connection->createSession($targetId);
```

### Response
Returns a Session object.
```

--------------------------------

### Disable headless mode for debugging

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Creates a browser with headless mode disabled to ease debugging. The 'headless' option is set to false in the createBrowser options array.

```php
use HeadlessChromium\BrowserFactory;

$browserFactory = new BrowserFactory();

$browser = $browserFactory->createBrowser([
    'headless' => false, // disable headless mode
]);
```

--------------------------------

### Page::waitForNavigation

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Waits for the navigation to complete.

```APIDOC
## Page::waitForNavigation

### Description
Waits for the navigation to complete.

### Method
Page::waitForNavigation

### Parameters
None.

### Request Example
```php
$page->navigate('http://example.com')->waitForNavigation();
```

### Response
No return value.
```

--------------------------------

### Wait for navigation with custom event and timeout

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Shows how to change the timeout and event for waitForNavigation(). Uses Page::DOM_CONTENT_LOADED and a 10000ms timeout. Requires importing HeadlessChromium\Page.

```php
use HeadlessChromium\Page;

// wait 10secs for the event "DOMContentLoaded" to be triggered
$navigation->waitForNavigation(Page::DOM_CONTENT_LOADED, 10000);
```

--------------------------------

### getFullPageClip

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Returns a Clip object representing the full-page layout, used for full-page screenshots.

```APIDOC
## getFullPageClip

### Description
Returns a Clip object representing the full-page layout, used for full-page screenshots.

### Method
getFullPageClip

### Parameters
None.

### Request Example
```php
$clip = $page->getFullPageClip();
```

### Response
Returns a Clip object.
```

--------------------------------

### Upload a file to an input element

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Sends a file path to the element, typically a file input, to upload the file.

```php
$elem->sendFile('/path/to/file');
```

--------------------------------

### Mouse API: find elements and click

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Uses the `find` method to search for elements using querySelector and moves the cursor to a random position over it. Throws ElementNotFoundException if the element is not found. The method attempts to scroll right and down to bring the element into view.

```php
try {
    $page->mouse()->find('#a')->click(); // find and click at an element with id "a"

    $page->mouse()->find('.a', 10); // find the 10th or last element with class "a"
} catch (ElementNotFoundException $exception) {
    // element not found
}
```

--------------------------------

### setHtml

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Replaces the entire page HTML with the provided HTML string. Optionally waits for a specific event and timeout.

```APIDOC
## setHtml

### Description
Replaces the entire page HTML with the provided HTML string. Optionally waits for a specific event and timeout.

### Method
setHtml

### Parameters
- **html** (string) - Required - The HTML content to set.
- **timeout** (int) - Optional - The timeout in milliseconds to wait for the page to unload. Defaults to 3000.
- **event** (string) - Optional - The event to wait for. Defaults to `Page::LOAD`.

### Return Value
No return value.

### Example
```php
$page->setHtml('<p>text</p>');
$page->setHtml('<p>text</p>', 10000, Page::NETWORK_IDLE);
```

### Notes
- This method completely replaces the current page HTML, it does not append.
```

--------------------------------

### pdf

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Prints the page as a PDF. Supports various options for layout, margins, headers, footers, and scaling.

```APIDOC
## pdf

### Description
Prints the page as a PDF. Supports various options for layout, margins, headers, footers, and scaling.

### Method
pdf

### Parameters
- **options** (array) - Optional - An associative array of options:
  - **landscape** (bool) - Optional - Default: false.
  - **printBackground** (bool) - Optional - Default: false.
  - **displayHeaderFooter** (bool) - Optional - Default: false.
  - **preferCSSPageSize** (bool) - Optional - Default: false.
  - **marginTop** (float) - Optional - Default: ~0.4 (inches).
  - **marginBottom** (float) - Optional - Default: ~0.4 (inches).
  - **marginLeft** (float) - Optional - Default: ~0.4 (inches).
  - **marginRight** (float) - Optional - Default: ~0.4 (inches).
  - **paperWidth** (float) - Optional - Default: 8.5 (inches).
  - **paperHeight** (float) - Optional - Default: 11.0 (inches).
  - **headerTemplate** (string) - Optional - HTML template for the header. Supported classes: date, title, url, pageNumber, totalPages.
  - **footerTemplate** (string) - Optional - HTML template for the footer. Supported classes: date, title, url, pageNumber, totalPages.
  - **scale** (float) - Optional - Default: 1.0.

### Request Example
```php
// navigate
$navigation = $page->navigate('http://example.com');

// wait for the page to be loaded
$navigation->waitForNavigation();

$options = [
    'landscape'           => true,             // default to false
    'printBackground'     => true,             // default to false
    'displayHeaderFooter' => true,             // default to false
    'preferCSSPageSize'   => true,             // default to false (reads parameters directly from @page)
    'marginTop'           => 0.0,              // defaults to ~0.4 (must be a float, value in inches)
    'marginBottom'        => 1.4,              // defaults to ~0.4 (must be a float, value in inches)
    'marginLeft'          => 5.0,              // defaults to ~0.4 (must be a float, value in inches)
    'marginRight'         => 1.0,              // defaults to ~0.4 (must be a float, value in inches)
    'paperWidth'          => 6.0,              // defaults to 8.5 (must be a float, value in inches)
    'paperHeight'         => 6.0,              // defaults to 11.0 (must be a float, value in inches)
    'headerTemplate'      => '<div>foo</div>', // see details above
    'footerTemplate'      => '<div>foo</div>', // see details above
    'scale'               => 1.2,              // defaults to 1.0 (must be a float)
];

// print as pdf (in memory binaries)
$pdf = $page->pdf($options);

// save the pdf
$pdf->saveToFile('/some/place/file.pdf');
```

### Response
Returns a PDF object with `saveToFile` and `saveToStream` methods.
```

--------------------------------

### setViewport

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Sets the viewport size (emulation) for the current page without affecting other pages. The method returns a promise-like object that can be awaited to wait for the operation to complete.

```APIDOC
## setViewport

### Description
Sets the viewport size (emulation) for the current page without affecting other pages. The method returns a promise-like object that can be awaited to wait for the operation to complete.

### Method
setViewport

### Parameters
- **width** (int) - Required - The viewport width in pixels.
- **height** (int) - Required - The viewport height in pixels.

### Request Example
```php
$width = 600;
$height = 300;
$page->setViewport($width, $height)
    ->await(); // wait for the operation to complete
```

### Response
Returns a promise-like object that resolves when the operation is complete.
```

--------------------------------

### BrowserFactory::setOptions

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Sets persistent options that will be applied to all subsequently created browsers. Options set here will be merged with any options passed directly to createBrowser.

```APIDOC
## BrowserFactory::setOptions

### Description
Sets persistent options that will be applied to all subsequently created browsers. Options set here will be merged with any options passed directly to createBrowser.

### Method
setOptions

### Parameters
#### Options (array) - Required
- **connectionDelay** (int) - Default: 0 - Delay to apply between each operation for debugging purposes
- **customFlags** (array) - Default: none - An array of flags to pass to the command line. Eg: ['--option1', '--option2=someValue']
- **debugLogger** (string|resource|PSR-3 logger) - Default: null - A string (e.g "php://stdout"), or resource, or PSR-3 logger instance to print debug messages
- **disableJavascript** (bool) - Default: false - Disable JavaScript execution on every page created via createPage()
- **disableNotifications** (bool) - Default: false - Disable browser notifications
- **enableImages** (bool) - Default: true - Toggles loading of images
- **envVariables** (array) - Default: none - An array of environment variables to pass to the process (example DISPLAY variable)
- **headers** (array) - Default: none - An array of custom HTTP headers
- **headless** (bool) - Default: true - Enable or disable headless mode
- **ignoreCertificateErrors** (bool) - Default: false - Set Chrome to ignore SSL errors
- **keepAlive** (bool) - Default: false - Set to true to keep alive the Chrome instance when the script terminates
- **noSandbox** (bool) - Default: false - Enable no sandbox mode, useful to run in a docker container
- **noProxyServer** (bool) - Default: false - Don't use a proxy server, always make direct connections. Overrides other proxy settings.
- **proxyBypassList** (string) - Default: none - Specifies a list of hosts for whom we bypass proxy settings and use direct connections
- **proxyServer** (string) - Default: none - Proxy server to use. usage: 127.0.0.1:8080 (authorisation with credentials does not work)
- **sendSyncDefaultTimeout** (int) - Default: 5000 - Default timeout (ms) for sending sync messages
- **startupTimeout** (int) - Default: 30 - Maximum time in seconds to wait for Chrome to start
- **userAgent** (string) - Default: none - User agent to use for the whole browser (see page API for alternative)
- **userDataDir** (string) - Default: none - Chrome user data dir (default: a new empty dir is generated temporarily)
- **userCrashDumpsDir** (string) - Default: none - The directory crashpad should store dumps in (crash reporter will be enabled automatically)
- **windowSize** (array) - Default: none - Size of the window. usage: $width, $height - see also Page::setViewport
- **excludedSwitches** (array) - Default: none - An array of Chrome flags that should be removed from the default set (example --enable-automation)

### Request Example
```php
$browserFactory->setOptions([
    'windowSize' => [1920, 1000],
]);
```

### Response
No return value.

```

--------------------------------

### Mouse API: scroll down and up

Source: https://github.com/chrome-php/chrome/blob/1.16/README.md

Emulates the mouse wheel to scroll up and down in a page, frame, or element.

```php
$page->mouse()
    ->scrollDown(100) // scroll down 100px
    ->scrollUp(50);   // scroll up 50px
```
Tokens:
Raw