1# php-webdriver – Selenium WebDriver bindings for PHP
2
3[![Latest stable version](https://img.shields.io/packagist/v/php-webdriver/webdriver.svg?style=flat-square&label=Packagist)](https://packagist.org/packages/php-webdriver/webdriver)
4[![GitHub Actions build status](https://img.shields.io/github/workflow/status/php-webdriver/php-webdriver/Tests?style=flat-square&label=GitHub%20Actions)](https://github.com/php-webdriver/php-webdriver/actions)
5[![SauceLabs test status](https://img.shields.io/github/workflow/status/php-webdriver/php-webdriver/Sauce%20Labs?style=flat-square&label=SauceLabs)](https://saucelabs.com/u/php-webdriver)
6[![Total downloads](https://img.shields.io/packagist/dd/php-webdriver/webdriver.svg?style=flat-square&label=Downloads)](https://packagist.org/packages/php-webdriver/webdriver)
7
8## Description
9Php-webdriver library is PHP language binding for Selenium WebDriver, which allows you to control web browsers from PHP.
10
11This library is compatible with Selenium server version 2.x, 3.x and 4.x.
12
13The library supports [JsonWireProtocol](https://github.com/SeleniumHQ/selenium/wiki/JsonWireProtocol) and also
14implements **experimental support** of [W3C WebDriver](https://w3c.github.io/webdriver/webdriver-spec.html).
15The W3C WebDriver support is not yet full-featured, however it should allow to control Firefox via Geckodriver and new
16versions of Chrome and Chromedriver with just a slight limitations.
17
18The concepts of this library are very similar to the "official" Java, .NET, Python and Ruby bindings from the
19[Selenium project](https://github.com/SeleniumHQ/selenium/).
20
21## Installation
22
23Installation is possible using [Composer](https://getcomposer.org/).
24
25If you don't already use Composer, you can download the `composer.phar` binary:
26
27    curl -sS https://getcomposer.org/installer | php
28
29Then install the library:
30
31    php composer.phar require php-webdriver/webdriver
32
33## Upgrade from version <1.8.0
34
35Starting from version 1.8.0, the project has been renamed from `facebook/php-webdriver` to `php-webdriver/webdriver`.
36
37In order to receive the new version and future updates, **you need to rename it in your composer.json**:
38
39```diff
40"require": {
41-    "facebook/webdriver": "(version you use)",
42+    "php-webdriver/webdriver": "(version you use)",
43}
44```
45
46and run `composer update`.
47
48## Getting started
49
50### 1. Start server (aka. remote end)
51
52To control a browser, you need to start a *remote end* (server), which will listen to the commands sent
53from this library and will execute them in the respective browser.
54
55This could be Selenium standalone server, but for local development, you can send them directly to so-called "browser driver" like Chromedriver or Geckodriver.
56
57#### a) Chromedriver
58
59�� Below you will find a simple example. Make sure to read our wiki for [more information on Chrome/Chromedriver](https://github.com/php-webdriver/php-webdriver/wiki/Chrome).
60
61Install the latest Chrome and [Chromedriver](https://sites.google.com/a/chromium.org/chromedriver/downloads).
62Make sure to have a compatible version of Chromedriver and Chrome!
63
64Run `chromedriver` binary, you can pass `port` argument, so that it listens on port 4444:
65
66```sh
67chromedriver --port=4444
68```
69
70#### b) Geckodriver
71
72�� Below you will find a simple example. Make sure to read our wiki for [more information on Firefox/Geckodriver](https://github.com/php-webdriver/php-webdriver/wiki/Firefox).
73
74Install the latest Firefox and [Geckodriver](https://github.com/mozilla/geckodriver/releases).
75Make sure to have a compatible version of Geckodriver and Firefox!
76
77Run `geckodriver` binary (it start to listen on port 4444 by default):
78
79```sh
80geckodriver
81```
82
83#### c) Selenium standalone server
84
85Selenium server can be useful when you need to execute multiple tests at once,
86when you run tests in several different browsers (like on your CI server), or when you need to distribute tests amongst
87several machines in grid mode (where one Selenium server acts as a hub, and others connect to it as nodes).
88
89Selenium server then act like a proxy and takes care of distributing commands to the respective nodes.
90
91The latest version can be found on the [Selenium download page](https://www.selenium.dev/downloads/).
92
93�� You can find [further Selenium server information](https://github.com/php-webdriver/php-webdriver/wiki/Selenium-server)
94in our wiki.
95
96#### d) Docker
97
98Selenium server could also be started inside Docker container - see [docker-selenium project](https://github.com/SeleniumHQ/docker-selenium).
99
100### 2. Create a Browser Session
101
102When creating a browser session, be sure to pass the url of your running server.
103
104For example:
105
106```php
107// Chromedriver (if started using --port=4444 as above)
108$serverUrl = 'http://localhost:4444';
109// Geckodriver
110$serverUrl = 'http://localhost:4444';
111// selenium-server-standalone-#.jar (version 2.x or 3.x)
112$serverUrl = 'http://localhost:4444/wd/hub';
113// selenium-server-standalone-#.jar (version 4.x)
114$serverUrl = 'http://localhost:4444';
115```
116
117Now you can start browser of your choice:
118
119```php
120use Facebook\WebDriver\Remote\RemoteWebDriver;
121
122// Chrome
123$driver = RemoteWebDriver::create($serverUrl, DesiredCapabilities::chrome());
124// Firefox
125$driver = RemoteWebDriver::create($serverUrl, DesiredCapabilities::firefox());
126// Microsoft Edge
127$driver = RemoteWebDriver::create($serverUrl, DesiredCapabilities::microsoftEdge());
128```
129
130### 3. Customize Desired Capabilities
131
132Desired capabilities define properties of the browser you are about to start.
133
134They can be customized:
135
136```php
137use Facebook\WebDriver\Firefox\FirefoxOptions;
138use Facebook\WebDriver\Remote\DesiredCapabilities;
139
140$desiredCapabilities = DesiredCapabilities::firefox();
141
142// Disable accepting SSL certificates
143$desiredCapabilities->setCapability('acceptSslCerts', false);
144
145// Add arguments via FirefoxOptions to start headless firefox
146$firefoxOptions = new FirefoxOptions();
147$firefoxOptions->addArguments(['-headless']);
148$desiredCapabilities->setCapability(FirefoxOptions::CAPABILITY, $firefoxOptions);
149
150$driver = RemoteWebDriver::create($serverUrl, $desiredCapabilities);
151```
152
153Capabilities can also be used to [�� configure a proxy server](https://github.com/php-webdriver/php-webdriver/wiki/HowTo-Work-with-proxy) which the browser should use.
154
155To configure browser-specific capabilities, you may use [�� ChromeOptions](https://github.com/php-webdriver/php-webdriver/wiki/Chrome#chromeoptions)
156or [�� FirefoxOptions](https://github.com/php-webdriver/php-webdriver/wiki/Firefox#firefoxoptions).
157
158* See [legacy JsonWire protocol](https://github.com/SeleniumHQ/selenium/wiki/DesiredCapabilities) documentation or [W3C WebDriver specification](https://w3c.github.io/webdriver/#capabilities) for more details.
159
160### 4. Control your browser
161
162```php
163// Go to URL
164$driver->get('https://en.wikipedia.org/wiki/Selenium_(software)');
165
166// Find search element by its id, write 'PHP' inside and submit
167$driver->findElement(WebDriverBy::id('searchInput')) // find search input element
168    ->sendKeys('PHP') // fill the search box
169    ->submit(); // submit the whole form
170
171// Find element of 'History' item in menu by its css selector
172$historyButton = $driver->findElement(
173    WebDriverBy::cssSelector('#ca-history a')
174);
175// Read text of the element and print it to output
176echo 'About to click to a button with text: ' . $historyButton->getText();
177
178// Click the element to navigate to revision history page
179$historyButton->click();
180
181// Make sure to always call quit() at the end to terminate the browser session
182$driver->quit();
183```
184
185See [example.php](example.php) for full example scenario.
186Visit our GitHub wiki for [�� php-webdriver command reference](https://github.com/php-webdriver/php-webdriver/wiki/Example-command-reference) and further examples.
187
188**NOTE:** Above snippets are not intended to be a working example by simply copy-pasting. See [example.php](example.php) for a working example.
189
190## Changelog
191For latest changes see [CHANGELOG.md](CHANGELOG.md) file.
192
193## More information
194
195Some basic usage example is provided in [example.php](example.php) file.
196
197How-tos are provided right here in [�� our GitHub wiki](https://github.com/php-webdriver/php-webdriver/wiki).
198
199If you don't use IDE, you may use [API documentation of php-webdriver](https://php-webdriver.github.io/php-webdriver/latest/).
200
201You may also want to check out the Selenium project [docs](https://selenium.dev/documentation/en/) and [wiki](https://github.com/SeleniumHQ/selenium/wiki).
202
203## Testing framework integration
204
205To take advantage of automatized testing you may want to integrate php-webdriver to your testing framework.
206There are some projects already providing this:
207
208- [Symfony Panther](https://github.com/symfony/panther) uses php-webdriver and integrates with PHPUnit using `PantherTestCase`
209- [Laravel Dusk](https://laravel.com/docs/dusk) is another project using php-webdriver, could be used for testing via `DuskTestCase`
210- [Steward](https://github.com/lmc-eu/steward) integrates php-webdriver directly to [PHPUnit](https://phpunit.de/), and provides parallelization
211- [Codeception](http://codeception.com) testing framework provides BDD-layer on top of php-webdriver in its [WebDriver module](http://codeception.com/docs/modules/WebDriver)
212- You can also check out this [blogpost](http://codeception.com/11-12-2013/working-with-phpunit-and-selenium-webdriver.html) + [demo project](https://github.com/DavertMik/php-webdriver-demo), describing simple [PHPUnit](https://phpunit.de/) integration
213
214## Support
215
216We have a great community willing to help you!
217
218❓ Do you have a **question, idea or some general feedback**? Visit our [Discussions](https://github.com/php-webdriver/php-webdriver/discussions) page.
219(Alternatively, you can [look for many answered questions also on StackOverflow](https://stackoverflow.com/questions/tagged/php+selenium-webdriver)).
220
221�� Something isn't working, and you want to **report a bug**? [Submit it here](https://github.com/php-webdriver/php-webdriver/issues/new) as a new issue.
222
223�� Looking for a **how-to** or **reference documentation**? See [our wiki](https://github.com/php-webdriver/php-webdriver/wiki).
224
225## Contributing ❤️
226
227We love to have your help to make php-webdriver better. See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for more information about contributing and developing php-webdriver.
228
229Php-webdriver is community project - if you want to join the effort with maintaining and developing this library, the best is to look on [issues marked with "help wanted"](https://github.com/php-webdriver/php-webdriver/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)
230label. Let us know in the issue comments if you want to contribute and if you want any guidance, and we will be delighted to help you to prepare your pull request.
231