This page covers specifics of using php-webdriver with Chrome/Chromium browser.

1. Installation
2. Start ChromeDriver
3. ChromeOptions
4. Chrome DevTools protocol

First you need to install Chrome / Chromium browser. However this is not enough, as each supported browser also needs its browser driver, in this case it is ChromeDriver. Browser driver is a binary file which enables the browser to be controlled using WebDriver protocol.

To use ChromeDriver, you will need to download chromedriver/chromedriver.exe executable. Make sure the path to chromedriver/chromedriver.exe is in your system PATH, so that you can easily start it. See official Selenium documentation covering PATH setup.

ℹ️ Chromedriver may be available in some Linux distributions (for example as chromium-chromedriver package in Ubuntu), so you can install the latest version using your system package manager.

⚠️ Make sure you have compatible version of Chrome and ChromeDriver (the major version number must match, for example Chrome 86.x needs ChromeDriver 86.x). If your tests started to suddenly fail, it may be possible your Chrome was auto-updated and your ChromeDriver is no longer compatible and needs to be updated to the latest version as well.

As with other browsers, there are multiple ways how to start ChromeDriver instance, each suitable for different scenario.

In this case php-webdriver takes care of starting and setting up chromedriver. This is suitable for simple cases, when you run the browser locally on your computer.

If you installed chromedriver in your system PATH, you can just start it like this:

$driver = ChromeDriver::start();
$driver->get('https://google.com');

When ChromeDriver is installed elsewhere, define path to chromedriver executable using WEBDRIVER_CHROME_DRIVER environment variable:

putenv('WEBDRIVER_CHROME_DRIVER=/path/to/chromedriver');
$driver = ChromeDriver::start();

or you can define the environment variable before starting the PHP script:

$ export WEBDRIVER_CHROME_DRIVER=/path/to/chromedriver
$ php my-test.php

// my-test.php
$driver = ChromeDriver::start();

// ... your code

// Don't forget to always call quit() at the end so that the chromedriver process is terminated
$driver->quit();

In this case you start chromedriver instance by yourself. It must be kept running while you start your tests. This scenario is suitable when you want to adjust the way chromedriver is started (for example the port number) or when you want to define the browser using `DesiredCapabilities object.

$ chromedriver --port=4444 # or chromedriver.exe on Windows

Now start your PHP script in another terminal window:

// my-test.php
$serverUrl = 'http://localhost:4444'; // if you don't start chromedriver with "--port=4444" as above, default port will be 9515
$driver = RemoteWebDriver::create($serverUrl, DesiredCapabilities::chrome());

$ php my-test.php

If you want to run your browser instances remotely (for example as a grid on CI server) or you want to start specific version of browser/Selenium in Docker, see Selenium server wiki page.

ChromeOptions is class managing additional capabilities specific to ChromeDriver. As such, those options are relevant only for Chromium-based browsers. The class has convenient methods for setting ChromeDriver-specific capabilities.

Full documentation of available ChromeOptions is available official ChromeDriver homepage.

See below for examples how to set and use ChromeOptions in php-webdriver:

// Create an instance of ChromeOptions:
$chromeOptions = new ChromeOptions();

// Configure $chromeOptions, see examples bellow:
$chromeOptions->addArguments(...);

// Create $capabilities and add configuration from ChromeOptions
$capabilities = DesiredCapabilities::chrome();
$capabilities->setCapability(ChromeOptions::CAPABILITY_W3C, $chromeOptions);

// Start the browser with $capabilities
// A) When using RemoteWebDriver::create()
$driver = RemoteWebDriver::create($serverUrl, $capabilities);
// B) When using ChromeDriver::start to start local Chromedriver
$driver = ChromeDriver::start($capabilities);

$chromeOptions->setBinary('/home/user/Downloads/my_chrome_binary');

Add command-line arguments to use when starting Chrome using addArguments() .

See full list of Chrome arguments.

$chromeOptions->addArguments(['--headless']);

$chromeOptions->addArguments(['--window-size=1024,768']);

$chromeOptions->addArguments(['--start-maximized']);

// Load extension from crx file
$chromeOptions->addExtensions([
    '/path/to/chrome/extension1.crx',
    '/path/to/chrome/extension2.crx',
]);

// Load base-64 extension from string
$chromeOptions->addEncodedExtensions([$base64EncodedExtension]);

Other options, not exposed via ChromeOptions, could be set using setExperimentalOption().

See ChromeDriver documentation for list of all options.

// Set profile preferences
// Please note most `prefs` are not supported with Chrome in headless mode, see https://bugs.chromium.org/p/chromium/issues/detail?id=775911
$chromeOptions->setExperimentalOption(
    'prefs', 
    ['enable_referrers' => false, 'intl.accept_languages' => 'cs,cs-CZ,en']
);

// Set other chrome-capability
$chromeOptions->setExperimentalOption('excludeSwitches', ['disable-popup-blocking']);

Using php-webdriver, you can also execute commands from Chrome DevTools protocol.

This may be quite useful in case you need some simple Chrome quirks (like changing user agent, manipulating geolocation etc.), and you still want all features and benefits of Selenium and WebDriver.

Because CDP commands are executed on top of WebDriver HTTP protocol, it does not provide the benefits of CDP control directly via WebSockets (for example binding to CDP events). This is possible using dedicated libraries, but this on the other hand works only with local Chrome and have other limitations.

$driver = ChromeDriver::start();

$devTools = $driver->getDevTools(); // returns ChromeDevToolsDriver instance

$driver = RemoteWebDriver::create($serverUrl, DesiredCapabilities::chrome());

$devTools = new ChromeDevToolsDriver($driver);

With ChromeDevToolsDriver instance in $devTools variable, you can execute various CDP commands.

See also official documentation.

$devTools->execute('Performance.enable');

$metrics = $devTools->execute('Performance.getMetrics');

$coordinates = [
    'latitude' => 50.1028,
    'longitude' => 14.4566,
    'accuracy' => 1,
];

$devTools->execute('Emulation.setGeolocationOverride', $coordinates);

$driver->get(/* URL of webpage which uses geolocation */);

Specifies whether to always send extra HTTP headers with the requests from this page.

$devTools->execute('Network.enable');
$devTools->execute('Network.setExtraHTTPHeaders', ['headers' => (object) ['My-Header' => 'My-Value']]);

// Following requests will include your additional headers:
$driver->get(/* URL */);

Override browser user agent with the given string.

$devTools->execute(
    'Network.setUserAgentOverride',
    ['userAgent' => 'Mozilla/5.0 (X11; Linux x86_64; rv:83.0) Gecko/20100101 Firefox/83.0']
);