php-webdriver: PHP Bindings for Selenium WebDriver Browser Automation

What php-webdriver Is and the Selenium Architecture

php-webdriver is described as "PHP language binding for Selenium WebDriver, which allows you to control web browsers from PHP." It is the PHP client in the Selenium ecosystem, providing the same concepts as the official Java, JavaScript, .NET, Python, and Ruby bindings.

The library does not launch browsers directly. It sends commands over HTTP to a remote end (the browser driver), which translates them into native browser actions. The remote end can be:

- A browser driver running locally: Chromedriver for Chrome, Geckodriver for Firefox. These accept connections on port 4444 by default and are suited for single-browser local testing. - A Selenium standalone server: used for multi-browser runs, CI environments, or distributing tests across nodes in a Selenium Grid. - A Docker container from the docker-selenium project.

This separation means php-webdriver does not contain browser-specific code. New browser versions are handled by updating the browser driver binary, not the PHP library itself. The library supports Selenium server versions 2.x, 3.x, and 4.x, as well as both the modern W3C WebDriver protocol and the legacy JsonWireProtocol.

Installing and the Package Rename from facebook/php-webdriver

Install via Composer. First download the installer if Composer is not already available:

curl -sS https://getcomposer.org/installer | php

Then require the library:

php composer.phar require php-webdriver/webdriver

Projects migrating from the original package (which was published as `facebook/webdriver` before version 1.8.0) must rename the dependency in composer.json:

"require": {
-    "facebook/webdriver": "(version you use)",
+    "php-webdriver/webdriver": "(version you use)",
}

After editing composer.json, run `composer update`. The namespace in the source code remains `Facebook\WebDriver` for backwards compatibility, even after the rename. Existing `use Facebook\WebDriver\...` statements in your code do not need to change.

Starting a Browser Driver and Creating a Session

Before creating a browser session, start the browser driver. For Chromedriver:

chromedriver --port=4444

For Geckodriver (Firefox), it listens on port 4444 by default:

geckodriver

For a Selenium standalone server version 2.x or 3.x, the URL uses the /wd/hub path: `http://localhost:4444/wd/hub`. For version 4.x, the URL is `http://localhost:4444` without the path.

Create a browser session with RemoteWebDriver:

use Facebook\WebDriver\Remote\RemoteWebDriver;

// Chrome
$driver = RemoteWebDriver::create($serverUrl, DesiredCapabilities::chrome());
// Firefox
$driver = RemoteWebDriver::create($serverUrl, DesiredCapabilities::firefox());
// Microsoft Edge
$driver = RemoteWebDriver::create($serverUrl, DesiredCapabilities::microsoftEdge());

The $serverUrl variable must point to the running browser driver or Selenium server. A session represents a single browser instance. Multiple sessions can run simultaneously against a Selenium Grid.

Controlling the Browser: Navigation, Element Finding, and Input

Once a session is open, the driver object exposes the full WebDriver API. Navigate to a URL:

$driver->get('https://en.wikipedia.org/wiki/Selenium_(software)');

Find an element and interact with it:

$driver->findElement(WebDriverBy::id('searchInput')) // find search input element
    ->sendKeys('PHP') // fill the search box
    ->submit(); // submit the whole form

Read element text:

$historyButton = $driver->findElement(
    WebDriverBy::cssSelector('#ca-history a')
);
echo 'About to click to a button with text: ' . $historyButton->getText();

WebDriverBy supports locating elements by id, name, class name, CSS selector, XPath, tag name, and link text. The README notes that complete examples are available in example.php in the repository root and in the GitHub wiki command reference.

Customizing Capabilities: Headless Mode and SSL Settings

Desired capabilities configure the browser before a session starts. To run Firefox in headless mode:

use Facebook\WebDriver\Firefox\FirefoxOptions;
use Facebook\WebDriver\Remote\DesiredCapabilities;

$desiredCapabilities = DesiredCapabilities::firefox();

// Disable accepting SSL certificates
$desiredCapabilities->setCapability('acceptSslCerts', false);

// Add arguments via FirefoxOptions to start headless firefox
$firefoxOptions = new FirefoxOptions();
$firefoxOptions->addArguments(['-headless']);
$desiredCapabilities->setCapability(FirefoxOptions::CAPABILITY, $firefoxOptions);

$driver = RemoteWebDriver::create($serverUrl, $desiredCapabilities);

Chrome has a corresponding ChromeOptions class for setting Chrome-specific flags including headless mode. The README also notes that DesiredCapabilities can configure a proxy server for the browser to use, documented in the GitHub wiki.

Running Tests with Selenium Server for Multi-Browser CI

For running tests in multiple browsers simultaneously or across multiple machines, the Selenium standalone server coordinates browser sessions as a hub. Each node in the grid runs a browser driver and registers with the hub. The PHP code connects to the hub URL and specifies the desired browser through DesiredCapabilities; the hub routes the session to an available node.

This architecture is the standard approach in CI environments where test suites must pass in Chrome, Firefox, and Edge before deployment. The docker-selenium project (github.com/SeleniumHQ/docker-selenium) provides pre-built Docker images that contain both the Selenium server and the browser, which simplifies CI setup compared to installing browsers and drivers directly on build agents.

The library is agnostic to whether the remote end is a local driver, a standalone server, or a Selenium Grid hub. The only difference is the $serverUrl value passed to RemoteWebDriver::create().

Limitations and Version Compatibility Notes

php-webdriver requires that the browser driver version matches the installed browser version. Chromedriver releases are tied to specific Chrome versions; a mismatch produces a session creation error. This is an operational constraint, not a library limitation, but it creates friction in environments where Chrome or Firefox auto-updates without a corresponding update to the driver binary. The distinction between ChromeDriver and WebDriver is worth stating clearly: WebDriver is the protocol standard (the W3C specification) and Chromedriver is a binary that implements the server side of that protocol for Chrome specifically. php-webdriver is the client that speaks the WebDriver protocol, and Chromedriver is one of several remote ends it can connect to. Geckodriver serves the same role for Firefox.

The library supports Selenium server versions 2.x through 4.x, but the URL path changes between versions: /wd/hub for 2.x and 3.x, and the bare root path for 4.x. A wrong URL path produces a connection error that can be confusing to diagnose when switching between server versions.

The namespace is still `Facebook\WebDriver` after the rename from facebook/php-webdriver to php-webdriver/webdriver. This is intentional for backwards compatibility, so existing `use Facebook\WebDriver\...` statements do not need to change. The Composer package name and the PHP namespace no longer match, which is worth knowing when reading error messages or searching for documentation.

The library supports both W3C WebDriver and the legacy JsonWireProtocol. JsonWireProtocol support is retained for compatibility with older Selenium server versions. W3C WebDriver is the current standard and the protocol that all modern browser drivers implement.

The repository root includes example.php, a runnable scenario that demonstrates navigation, element finding, key input, and form submission against Wikipedia. The repository does not have GitHub releases; changes are tracked through commits and the CHANGELOG.md file. The last push to the repository was on 2026-09-25.

Editorial conclusion

php-webdriver is the correct library when you need to control a browser from PHP, whether for test automation, UI validation, or web scraping against JavaScript-heavy pages. Before starting, confirm you have a compatible browser driver (Chromedriver or Geckodriver) and that its version matches your browser version, because mismatches produce cryptic errors. Teams migrating from the old facebook/webdriver Composer package must rename it in composer.json and run composer update before receiving further updates.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. php-webdriver/php-webdriver on GitHub
4. README