This page covers specifics of using php-webdriver with Firefox browser and Geckodriver.

1. Installation
2. Start Geckodriver
3. FirefoxOptions
4. Firefox Profile

First you need to install the Firefox browser. However, this is not enough, as each supported browser also needs its browser driver, in the case of Firefox it is Geckodriver (the name came from "Gecko" - browser engine used by Firefox). Browser driver is a binary file which enables the browser to be controlled using WebDriver protocol.

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

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

⚠️ Make sure you have compatible version of Firefox and Geckodriver. This is most easily done by using latest stable version of Firefox and the latest released version of Geckodriver.

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

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

If you installed geckodriver in your system PATH, you can start it like this without any additional steps:

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

When geckodriver binary is installed elsewhere, define path to the binary using WEBDRIVER_FIREFOX_DRIVER environment variable:

putenv('WEBDRIVER_FIREFOX_DRIVER=/path/to/geckodriver');
$driver = FirefoxDriver::start();

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

$ export WEBDRIVER_FIREFOX_DRIVER=/path/to/geckodriver
$ php my-test.php

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

// ... your code

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

For this case, you start geckodriver instance by yourself. It must be kept running while you start your tests. This scenario is suitable for basic local development, and also when you need to adjust the way geckodriver is started (for example the port number) or when you want to define the browser using DesiredCapabilities object.

$ geckodriver # or geckodriver.exe on Windows

Now start your PHP script in another terminal window:

// my-test.php
$serverUrl = 'http://localhost:4444';
$driver = RemoteWebDriver::create($serverUrl, DesiredCapabilities::firefox());

$ 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.

For managing Firefox-specific capabilities, you can use FirefoxOptions class.

Full list of available firefoxOptions could be found in Mozilla documentation.

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

// Create an instance of FirefoxOptions:
$firefoxOptions = new FirefoxOptions();

// Configure $firefoxOptions, see examples bellow
$firefoxOptions->addArguments([/*...*/]);
$firefoxOptions->setPreference('example.preference', 'value');

// Create $capabilities and add configuration from FirefoxOptions
$capabilities = DesiredCapabilities::firefox();
$capabilities->setCapability(FirefoxOptions::CAPABILITY, $firefoxOptions);

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

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

Default value of about:config entries (Firefox preferences) could be modified using prefs field:

$firefoxOptions->setPreference('javascript.options.showInConsole', false);
$firefoxOptions->setPreference('dom.ipc.processCount', 4);

More information about the preferences can by found in Firefox documentation.

$firefoxOptions->setOption('binary', '/home/user/Downloads/firefox-esr');

Another option how to adjust Firefox behavior is to use custom profile. This profile is transferred to the target machine where Firefox runs.

Custom Firefox Profile could be used for example to start Firefox with installed extensions, custom certificates etc. However, for setting custom preferences we recommend using the setPreference() method on FirefoxOptions instead.

$profile = new FirefoxProfile();

$profile->addExtension('path/to/FirefoxExtension.xpi');

$firefoxOptions = new FirefoxOptions();
$firefoxOptions->setProfile($profile);

$capabilities = DesiredCapabilities::firefox();
$capabilities->setCapability(FirefoxOptions::CAPABILITY, $firefoxOptions);

$driver = RemoteWebDriver::create('http://localhost:4444', $capabilities);