Features

Requirements

Installation

$ composer require chrome-php/chrome

Usage

useHeadlessChromium\BrowserFactory;$browserFactory =newBrowserFactory();// 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();}

Using different Chrome executable

useHeadlessChromium\BrowserFactory;// replace default 'chrome' with 'chromium-browser'$browserFactory =newBrowserFactory('chromium-browser');

Debugging

useHeadlessChromium\BrowserFactory;$browserFactory =newBrowserFactory();$browser =$browserFactory->createBrowser(['headless' =>false,// disable headless mode]);

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

API

Browser Factory

useHeadlessChromium\BrowserFactory;$browserFactory =newBrowserFactory();$browser =$browserFactory->createBrowser(['windowSize'   => [1920,1000],'enableImages' =>false,]);// this browser will be created without any options$browser2 =$browserFactory->createBrowser();

$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();

Available options

Persistent Browser

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 =newBrowserFactory();$browser =$factory->createBrowser(['keepAlive' =>true,    ]);// save the uri to be able to connect again to browser\file_put_contents($socketFile,$browser->getSocketUri(),LOCK_EX);}

Browser API

Create a new page (tab)

$page =$browser->createPage();

Get opened pages (tabs)

$pages =$browser->getPages();

Close the browser

$browser->close();

Set a script to evaluate before every page created by this browser will navigate

$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));');

Page API

Navigate to an URL

// navigate$navigation =$page->navigate('http://example.com');// wait for the page to be loaded$navigation->waitForNavigation();

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

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

Evaluate script on the page

// 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();

Call a function

$evaluation =$page->callFunction("function(a, b) {\n    window.foo = a + b;\n}",    [1,2]);$value =$evaluation->getReturnValue();

Add a script tag

$page->addScriptTag(['content' =>file_get_contents('path/to/jquery.js')])->waitForResponse();$page->evaluate('$(".my.element").html()');

$page->addScriptTag(['url' =>'https://code.jquery.com/jquery-3.3.1.min.js'])->waitForResponse();$page->evaluate('$(".my.element").html()');

Set the page HTML

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

Get the page HTML

$html =$page->getHtml();

Add a script to evaluate upon page navigation

$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));');

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

Set viewport size

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

Make a screenshot

// 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');

useHeadlessChromium\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 =newClip($x,$y,$width,$height);// take the screenshot (in memory binaries)$screenshot =$page->screenshot(['clip'  =>$clip,]);// save the screenshot$screenshot->saveToFile('/some/place/file.jpg');

// 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');

Print as PDF

// 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 savingheader('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');echobase64_decode($pdf->getBase64());

Save downloads

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

Mouse API

$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();

$page->mouse()    ->scrollDown(100)// scroll down 100px    ->scrollUp(50);// scroll up 50px

Finding elements

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}

Keyboard API

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

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

Key combinations

// 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

Key aliases

Cookie API

Set Cookie

useHeadlessChromium\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();

Get Cookies

useHeadlessChromium\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}

Set user agent

$page->setUserAgent('my user-agent');

Advanced usage

useHeadlessChromium\Communication\Connection;useHeadlessChromium\Communication\Message;// Chrome devtools URI$webSocketUri ='ws://127.0.0.1:9222/devtools/browser/xxx';// create a connection$connection =newConnection($webSocketUri);$connection->connect();// send method "Target.activateTarget"$responseReader =$connection->sendMessage(newMessage('Target.activateTarget', ['targetId' =>'xxx']));// wait up to 1000ms for a response$response =$responseReader->waitForResponse(1000);

Create a session and send a message to the target

// 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(newMessage('Page.reload'));

Debugging

$connection->setConnectionDelay(500);// wait for 500ms between each operation to ease debugging

Browser (standalone)

useHeadlessChromium\Communication\Connection;useHeadlessChromium\Browser;// Chrome devtools URI$webSocketUri ='ws://127.0.0.1:9222/devtools/browser/xxx';// create connection given a WebSocket URI$connection =newConnection($webSocketUri);$connection->connect();// create browser$browser =newBrowser($connection);

Interacting with DOM

$page =$browser->createPage();$page->navigate('http://example.com')->waitForNavigation();$elem =$page->dom()->querySelector('#index_email');

$elem =$page->dom()->querySelector('#index_email');$elem->querySelectorAll('a.link');

$page =$browser->createPage();$page->navigate('http://example.com')->waitForNavigation();$elem =$page->dom()->search('//div/*/a');

$page =$browser->createPage();$page->navigate('http://example.com')->waitForNavigation();$page->waitUntilContainsElement('div[data-name=\"el\"]');

useHeadlessChromium\Dom\Selector\XPathSelector;$page =$browser->createPage();$page->navigate('http://example.com')->waitForNavigation();$page->waitUntilContainsElement(newXPathSelector('//div[contains(text(), "content")]'));

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

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

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

Contributing

License