Commit 12893d0b authored by Dries's avatar Dries
Browse files

- Patch #340283 by boombatower, dmitrig01 et al: abstract the simpletest...

- Patch #340283 by boombatower, dmitrig01 et al: abstract the simpletest broswer in its own class/object.
parent 8a6d8660
<?php
// $Id$
/**
* @file
* Browser API class.
*/
/**
* @defgroup browser Browser
* @{
* Provides a powerful text based browser through a class based API.
* The browser supports two HTTP backends natively: 1) PHP streams, and
* 2) curl. The browser also supports arbitrary HTTP request types in addtion
* to GET and POST, given that the backend supports them.
*
* The browser can be used to make a simple GET request to example.com as
* shown below.
* @code
* $browser = new Browser();
* $browser->get('http://example.com');
* @endcode
* The result of the GET request can be accessed in two ways: 1) the get()
* method returns an array defining the result of the request, or 2) the
* individual properties can be accessed from the browser instance via their
* respective access methods. The following demonstrates the properties that
* are avaialable and how to access them.
* @code
* $browser->getUrl();
* $browser->getResponseHeaders();
* $browser->getContent();
* @endcode
*
* When performing a POST request the following format is used.
* @code
* $browser = new Browser();
* $post = array(
* 'field_name1' => 'foo',
* 'checkbox1' => TRUE,
* 'multipleselect1[]' => array(
* 'value1',
* 'value2',
* ),
* );
* $browser->post('http://example.com/form', $post, 'Submit button text');
* @endcode
* To submit a multi-step form or to post to the current page the URL passed to
* post() may be set to NULL. If there were two steps on the form shown in the
* example above with the mutliple select field on the second page and a submit
* button with the title "Next" on the first page the code be as follows.
* @code
* $browser = new Browser();
* $post = array(
* 'field_name1' => 'foo',
* 'checkbox1' => TRUE,
* );
* $browser->post('http://example.com/form', $post, 'Next');
*
* $post = array(
* 'multipleselect1[]' => array(
* 'value1',
* 'value2',
* ),
* );
* $browser->post(NULL, $post, 'Final');
* @endcode
*/
/**
* Browser API class.
*
* All browser functionality is provided by this main class which manages the
* various aspects of the browser.
*/
class Browser {
/**
* Flag indicating if curl is available.
*
* @var boolean
*/
protected $curl;
/**
* The handle of the current curl connection.
*
* @var resource
*/
protected $handle;
/**
* The current cookie file used by curl.
*
* Cookies are not reused so they can be stored in memory instead of a file.
*
* @var mixed
*/
protected $cookieFile = NULL;
/**
* The request headers.
*
* @var array
*/
protected $requestHeaders = array();
/**
* The URL of the current page.
*
* @var string
*/
protected $url;
/**
* The response headers of the current page.
*
* @var Array
*/
protected $headers = array();
/**
* The raw content of the current page.
*
* @var string
*/
protected $content;
/**
* The BrowserPage class representing to the current page.
*
* @var BrowserPage
*/
protected $page;
/**
* Initialize the browser.
*
* @param $force_stream
* Force the use of the PHP stream wrappers insead of CURL. This is used
* during testing to force the use of the stream wrapper so it can be
* tested.
*/
public function __construct($force_stream = FALSE) {
$this->curl = $force_stream ? FALSE : function_exists('curl_init');
$this->setUserAgent('Drupal (+http://drupal.org/)');
if ($this->curl) {
$this->handle = curl_init();
curl_setopt_array($this->handle, $this->curlOptions());
}
else {
$this->handle = stream_context_create();
}
}
/**
* Check the the method is supported by the backend.
*
* @param $method
* The method string identifier.
*/
public function isMethodSupported($method) {
return $method == 'GET' || $method == 'POST';
}
/**
* Get the request headers.
*
* The request headers are sent in every request made by the browser with a
* few changes made the the individual request methods.
*
* @return
* Associative array of request headers.
*/
public function getRequestHeaders() {
return $this->requestHeaders;
}
/**
* Set the request headers.
*
* @param $headers
* Associative array of request headers.
*/
public function setRequestHeaders(array $headers) {
$this->requestHeaders = $headers;
}
/**
* Get the user-agent that the browser is identifying itself as.
*
* @return
* Browser user-agent.
*/
public function getUserAgent() {
return $this->requestHeaders['User-Agent'];
}
/**
* Set the user-agent that the browser will identify itself as.
*
* @param $agent
* User-agent to to identify as.
*/
public function setUserAgent($agent) {
$this->requestHeaders['User-Agent'] = $agent;
}
/**
* Get the URL of the current page.
*
* @return
* The URL of the current page.
*/
public function getUrl() {
return $this->url;
}
/**
* Get the response headers of the current page.
*
* @return
* The response headers of the current page.
*/
public function getResponseHeaders() {
return $this->headers;
}
/**
* Get the raw content of the current page.
*
* @return
* The raw content for the current page.
*/
public function getContent() {
return $this->content;
}
/**
* Get the BrowserPage instance for the current page.
*
* If the raw content is new and the page has not yet been parsed then parse
* the content and ensure that it is valid.
*
* @return
* BrowserPage instance for the current page.
*/
public function getPage() {
if (!isset($this->page)) {
$this->page = new BrowserPage($this->url, $this->headers, $this->content);
}
return $this->page;
}
/**
* Get the current state of the browser.
*
* @return
* An associative array containing state information, including: 1) url, 2)
* headers, 3) content.
* @see getUrl()
* @see getResponseHeaders()
* @see getContent()
*/
public function getState() {
return array(
'url' => $this->url,
'headers' => $this->headers,
'content' => $this->content,
);
}
/**
* Set the state of the browser.
*
* @param $url
* The URL of the current page.
* @param $headers
* The response headers of the current page.
* @param $content
* The raw content of the current page.
*/
public function setState($url, $headers, $content) {
$this->url = $url;
$this->headers = $headers;
$this->content = $content;
// Clear the page variable since the content has change.
unset($this->page);
$this->checkForRefresh();
}
/**
* Perform a GET request.
*
* @param $url
* Absolute URL to request.
* @return
* Associative array of state information, as returned by getState().
* @see getState().
*/
public function get($url) {
if ($this->curl) {
$this->curlExecute(array(
CURLOPT_HTTPGET => TRUE,
CURLOPT_URL => $url,
CURLOPT_NOBODY => FALSE,
));
}
else {
$this->streamExecute($url, array(
'method' => 'GET',
'header' => array(
'Content-Type' => 'application/x-www-form-urlencoded',
),
));
}
$this->refreshCheck();
return $this->getState();
}
/**
* Perform a POST request.
*
* @param $url
* Absolute URL to request, or NULL to submit the current page.
* @param $fields
* Associative array of fields to submit as POST variables.
* @param $submit
* Text contained in 'value' properly of submit button of which to press.
* @return
* Associative array of state information, as returned by
* browser_state_get().
* @see browser_state_get()
*/
public function post($url, array $fields, $submit) {
// If URL is set then request the page, otherwise use the current page.
if ($url) {
$this->get($url);
}
else {
$url = $this->url;
}
if (($page = $this->getPage()) === FALSE) {
return FALSE;
}
if (($form = $this->findForm($fields, $submit)) === FALSE) {
return FALSE;
}
// If form specified action then use that for the post url.
if ($form['action']) {
$url = $page->getAbsoluteUrl($form['action']);
}
if ($this->curl) {
$this->curlExecute(array(
CURLOPT_POST => TRUE,
CURLOPT_URL => $url,
CURLOPT_POSTFIELDS => http_build_query($form['post'], NULL, '&'),
));
}
else {
$this->streamExecute($url, array(
'method' => 'POST',
'header' => array(
'Content-Type' => 'application/x-www-form-urlencoded',
),
'content' => http_build_query($form['post'], NULL, '&'),
));
}
$this->refreshCheck();
return $this->getState();
}
/**
* Find the the form that patches the conditions.
*
* @param $fields
* Associative array of fields to submit as POST variables.
* @param $submit
* Text contained in 'value' properly of submit button of which to press.
* @return
* Form action and the complete post array containing default values if not
* overridden, or FALSE if no form matching the conditions was found.
*/
protected function findForm(array $fields, $submit) {
$page = $this->getPage();
$forms = $page->getForms();
foreach ($forms as $form) {
if (($post = $this->processForm($form, $fields, $submit)) !== FALSE) {
$action = (isset($form['action']) ? (string) $form['action'] : FALSE);
return array(
'action' => $action,
'post' => $post,
);
}
}
return FALSE;
}
/**
* Check the conditions against the specified form and process values.
*
* @param $form
* Form SimpleXMLElement object.
* @param $fields
* Associative array of fields to submit as POST variables.
* @param $submit
* Text contained in 'value' properly of submit button of which to press.
* @return
* The complete post array containing default values if not overridden, or
* FALSE if no form matching the conditions was found.
*/
protected function processForm($form, $fields, $submit) {
$page = $this->getPage();
$post = array();
$submit_found = FALSE;
$inputs = $page->getInputs($form);
foreach ($inputs as $input) {
$name = (string) $input['name'];
$html_value = isset($input['value']) ? (string) $input['value'] : '';
// Get type from input vs textarea and select.
$type = isset($input['type']) ? (string) $input['type'] : $input->getName();
if (isset($fields[$name])) {
if ($type == 'file') {
// Make sure the file path is the absolute path.
$file = realpath($fields[$name]);
if ($file && is_file($file)) {
// Signify that the post field is a file in case backend needs to
// perform additional processing.
$post[$name] = '@' . $file;
}
// Known type, field processed.
unset($fields[$name]);
}
elseif (($processed_value = $this->processField($input, $type, $fields[$name], $html_value)) !== NULL) {
// Value may be ommitted (checkbox).
if ($processed_value !== FALSE) {
if (is_array($processed_value)) {
$post += $processed_value;
}
else {
$post[$name] = $processed_value;
}
}
// Known type, field processed.
unset($fields[$name]);
}
}
// No post value for the field means that: no post field value specified,
// the value does not match the field (checkbox, radio, select), or the
// field is of an unknown type.
if (!isset($post[$name])) {
// No value specified so use default value (value in HTML).
if (($default_value = $this->getDefaultFieldValue($input, $type, $html_value)) !== NULL) {
$post[$name] = $default_value;
unset($fields[$name]);
}
}
// Check if the
if (($type == 'submit' || $type == 'image') && $submit == $html_value) {
$post[$name] = $html_value;
$submit_found = TRUE;
}
}
if ($submit_found) {
return $post;
}
return FALSE;
}
/**
* Get the value to be sent for the specified field.
*
* @param $input
* Input SimpleXMLElement object.
* @param $type
* Input type: text, textarea, password, radio, checkbox, or select.
* @param $new_value
* The new value to be assigned to the input.
* @param $html_value
* The cleaned default value for the input from the HTML value.
*/
protected function processField($input, $type, $new_value, $html_value) {
switch ($type) {
case 'text':
case 'textarea':
case 'password':
return $new_value;
case 'radio':
if ($new_value == $html_value) {
return $new_value;
}
return NULL;
case 'checkbox':
// If $new_value is set to FALSE then ommit checkbox value, otherwise
// pass original value.
if ($new_value === FALSE) {
return FALSE;
}
return $html_value;
case 'select':
// Remove the ending [] from multi-select element name.
$key = preg_replace('/\[\]$/', '', (string) $input['name']);
$options = $page->getSelectOptions($input);
$index = 0;
$out = array();
foreach ($options as $value => $text) {
if (is_array($value)) {
if (in_array($value, $new_value)) {
$out[$key . '[' . $index++ . ']'] = $value;
}
}
elseif ($new_value == $value) {
return $new_value;
}
}
return ($out ? $out : NULL);
default:
return NULL;
}
}
/**
* Get the cleaned default value for the input from the HTML value.
*
* @param $input
* Input SimpleXMLElement object.
* @param $type
* Input type: text, textarea, password, radio, checkbox, or select.
* @param $html_value
* The default value for the input, as specified in the HTML.
*/
protected function getDefaultFieldValue($input, $type, $html_value) {
switch ($type) {
case 'textarea':
return (string) $input;
case 'select':
// Remove the ending [] from multi-select element name.
$key = preg_replace('/\[\]$/', '', (string) $input['name']);
$single = empty($input['multiple']);
$options = $page->getSelectOptionElements($input);
$first = TRUE;
$index = 0;
$out = array();
foreach ($options as $option) {
// For single select, we load the first option, if there is a
// selected option that will overwrite it later.
if ($option['selected'] || ($first && $single)) {
$first = FALSE;
if ($single) {
$out[$key] = (string) $option['value'];
}
else {
$out[$key . '[' . $index++ . ']'] = (string) $option['value'];
}
}
return ($single ? $out[$key] : $out);
}
break;
case 'file':
return NULL;
case 'radio':
case 'checkbox':
if (!isset($input['checked'])) {
return NULL;
}
// Deliberately no break.
default:
return $html_value;
}
}
/**
* Perform a request of arbitrary type.
*
* Please use get() and post() for GET and POST requests respectively.
*
* @param $method
* The method string identifier.
* @param $url
* Absolute URL to request.
* @param $additional
* Additional parameters related to the particular request method.
* @return
* Associative array of state information, as returned by getState().
* @see getState().
*/
public function request($method, $url, array $additional) {
if (!$this->isMethodSupported($method)) {
return FALSE;
}
// TODO
}
/**
* Perform the request using the PHP stream wrapper.
*
* @param $url
* The url to request.
* @param $options
* The HTTP stream context options to be passed to
* stream_context_set_params().
*/
protected function streamExecute($url, array $options) {
// Global variable provided by PHP stream wapper.
global $http_response_header;
if (!isset($options['header'])) {
$options['header'] = array();
}
// Merge default request headers with the passed headers and generate
// header string to be sent in http request.
$headers = $this->requestHeaders + $options['header'];
$options['header'] = $this->headerString($headers);
// Update the handler options.
stream_context_set_params($this->handle, array(
'options' => array(
'http' => $options,
)