Class SimpleBrowser

Description

Simulated web browser. This is an aggregate of the user agent, the HTML parsing, request history and the last header set.

Located in /browser.php (line 157)


	
			
Method Summary
 SimpleBrowser __construct ()
 void addHeader (string $header)
 void ageCookies (integer $interval)
 boolean authenticate (string $username, string $password)
 boolean back ()
 void clearFrameFocus ()
 string/boolean click (string $label)
 string/boolean clickImage (string $label, [integer $x = 1], [integer $y = 1], [hash $additional = false])
 string/boolean clickImageById (integer/string $id, [integer $x = 1], [integer $y = 1], [hash $additional = false])
 string/boolean clickImageByName (string $name, [integer $x = 1], [integer $y = 1], [hash $additional = false])
 string/boolean clickLink (string $label, [integer $index = 0])
 string/boolean clickLinkById (string $id)
 string/boolean clickSubmit ([string $label = 'Submit'], [hash $additional = false])
 string/boolean clickSubmitById (string $id, [hash $additional = false])
 string/boolean clickSubmitByName (string $name, [hash $additional = false])
 SimpleFetcher createUserAgent ()
 string delete (string/SimpleUrl $url, [hash/SimpleFormEncoding $parameters = false])
 SimplePage fetch (string/SimpleUrl $url, SimpleEncoding $encoding, [integer $depth = 0])
 boolean forward ()
 string get (string/SimpleUrl $url, [hash/SimpleFormEncoding $parameters = false])
 string getAuthentication ()
 string getBaseUrl ()
 string getContent ()
 string getContentAsText ()
 string getCookieValue (string $host, string $path, string $name)
 string getCurrentCookieValue (string $name)
 string/boolean getField (string $label)
 string/boolean getFieldById (string/integer $id)
 string/boolean getFieldByName (string $name)
 integer/string/boolean getFrameFocus ()
 array getFrames ()
 string getHeaders ()
 string/boolean getLink (string $label, [integer $index = 0])
 string/boolean getLinkById (string $id)
 string getMimeType ()
 object SimplePHPPageBuilder getParser ()
 string getRealm ()
 string getRequest ()
 integer getResponseCode ()
 string getTitle ()
 string getTransportError ()
 string getUrl ()
 array getUrls ()
 boolean head (string/SimpleUrl $url, [hash/SimpleHeadEncoding $parameters = false])
 void ignoreCookies ()
 void ignoreFrames ()
 boolean isClickable (string $label)
 boolean isImage (string $label)
 boolean isSubmit (string $label)
 string load (SimpleUrl $url, SimpleEncoding $parameters)
 string loadFrame (array $frames, string/SimpleUrl $url, SimpleFormEncoding $parameters)
 string loadPage (string/SimpleUrl $url, SimplePostEncoding $parameters)
 SimplePage parse (SimpleHttpResponse $response, [integer $depth = 0])
 string post (string/SimpleUrl $url, [hash/SimpleFormEncoding $parameters = false], [string $content_type = false])
 string put (string/SimpleUrl $url, [hash/SimpleFormEncoding $parameters = false], [string $content_type = false])
 void restart ([string/integer $date = false])
 string/boolean retry ()
 void setConnectionTimeout (integer $timeout)
 void setCookie (string $name, string $value, [string $host = false], [string $path = '/'], [string $expiry = false])
 boolean setField (string $label, string $value, [ $position = false])
 boolean setFieldById (string/integer $id, string $value)
 boolean setFieldByName (string $name, string $value, [ $position = false])
 boolean setFrameFocus (string $name)
 boolean setFrameFocusByIndex (integer $choice)
 void setMaximumNestedFrames (integer $max)
 void setMaximumRedirects (integer $max)
 void setParser (object A $parser)
 string/boolean submitFormById (string $id)
 void useCookies ()
 void useFrames ()
 void useProxy (string $proxy, [string $username = false], [string $password = false])
Methods
Constructor __construct (line 172)

Starts with a fresh browser with no cookie or any other state information. The exception is that a default proxy will be set up if specified in the options.

  • access: public
SimpleBrowser __construct ()
addHeader (line 374)

Adds a header to every fetch.

  • access: public
void addHeader (string $header)
  • string $header: Header line to add to every request until cleared.
ageCookies (line 383)

Ages the cookies by the specified time.

  • access: public
void ageCookies (integer $interval)
  • integer $interval: Amount in seconds.
authenticate (line 629)

Retries a request after setting the authentication for the current realm.

  • return: True if successful fetch. Note that authentication may still have failed.
  • access: public
boolean authenticate (string $username, string $password)
  • string $username: Username for realm.
  • string $password: Password for realm.
back (line 588)

Equivalent to hitting the back button on the browser. The browser history is unchanged on failure. The page content is refetched as there is no concept of content caching in SimpleTest.

  • return: True if history entry and fetch succeeded
  • access: public
boolean back ()
buildPage (line 289)

Assembles the parsing machinery and actually parses a single page. Frees all of the builder memory and so unjams the PHP memory management.

  • return: Parsed top level page.
  • access: protected
SimplePage buildPage (SimpleHttpResponse $response)
clearFrameFocus (line 692)

Clears the frame focus. All frames will be searched for content.

  • access: public
void clearFrameFocus ()
click (line 1123)

Clicks a visible text item. Will first try buttons, then links and then images.

  • return: Raw page or false.
  • access: public
string/boolean click (string $label)
  • string $label: Visible text or alt text.
clickImage (line 969)

Clicks the submit image by some kind of label. Usually

the alt tag or the nearest equivalent. The owning form will be submitted by this. Clicking outside of the boundary of the coordinates will result in a failure.

  • return: Page on success.
  • access: public
string/boolean clickImage (string $label, [integer $x = 1], [integer $y = 1], [hash $additional = false])
  • string $label: ID attribute of button.
  • integer $x: X-coordinate of imaginary click.
  • integer $y: Y-coordinate of imaginary click.
  • hash $additional: Additional form data.
clickImageById (line 1014)

Clicks the submit image by ID attribute. The owning form will be submitted by this. Clicking outside of the boundary of the coordinates will result in a failure.

  • return: Page on success.
  • access: public
string/boolean clickImageById (integer/string $id, [integer $x = 1], [integer $y = 1], [hash $additional = false])
  • integer/string $id: ID attribute of button.
  • integer $x: X-coordinate of imaginary click.
  • integer $y: Y-coordinate of imaginary click.
  • hash $additional: Additional form data.
clickImageByName (line 992)

Clicks the submit image by the name. Usually

the alt tag or the nearest equivalent. The owning form will be submitted by this. Clicking outside of the boundary of the coordinates will result in a failure.

  • return: Page on success.
  • access: public
string/boolean clickImageByName (string $name, [integer $x = 1], [integer $y = 1], [hash $additional = false])
  • string $name: Name attribute of button.
  • integer $x: X-coordinate of imaginary click.
  • integer $y: Y-coordinate of imaginary click.
  • hash $additional: Additional form data.
clickLink (line 1083)

Follows a link by label. Will click the first link found with this link text by default, or a later one if an index is given. The match ignores case and white space issues.

  • return: Page on success.
  • access: public
string/boolean clickLink (string $label, [integer $index = 0])
  • string $label: Text between the anchor tags.
  • integer $index: Link position counting from zero.
clickLinkById (line 1108)

Follows a link by id attribute.

  • return: Page on success.
  • access: public
string/boolean clickLinkById (string $id)
  • string $id: ID attribute value.
clickSubmit (line 899)

Clicks the submit button by label. The owning form will be submitted by this.

  • return: Page on success.
  • access: public
string/boolean clickSubmit ([string $label = 'Submit'], [hash $additional = false])
  • string $label: Button label. An unlabeled button can be triggered by 'Submit'.
  • hash $additional: Additional form data.
clickSubmitById (line 935)

Clicks the submit button by ID attribute of the button itself. The owning form will be submitted by this.

  • return: Page on success.
  • access: public
string/boolean clickSubmitById (string $id, [hash $additional = false])
  • string $id: Button ID.
  • hash $additional: Additional form data.
clickSubmitByName (line 917)

Clicks the submit button by name attribute. The owning form will be submitted by this.

  • return: Page on success.
  • access: public
string/boolean clickSubmitByName (string $name, [hash $additional = false])
  • string $name: Button name.
  • hash $additional: Additional form data.
createHistory (line 198)

Creates a new empty history list.

  • return: New list.
  • access: protected
SimpleBrowserHistory createHistory ()
createUserAgent (line 189)

Creates the underlying user agent.

  • return: Content fetcher.
  • access: protected
SimpleFetcher createUserAgent ()
delete (line 548)

Sends a DELETE request and fetches the response.

  • return: Content of page or false.
  • access: public
string delete (string/SimpleUrl $url, [hash/SimpleFormEncoding $parameters = false])
  • string/SimpleUrl $url: Target to fetch.
  • hash/SimpleFormEncoding $parameters: Additional parameters for DELETE request.
fetch (line 302)

Fetches a page. Jointly recursive with the parse() method as it descends a frameset.

  • return: Parsed page.
  • access: protected
SimplePage fetch (string/SimpleUrl $url, SimpleEncoding $encoding, [integer $depth = 0])
  • string/SimpleUrl $url: Target to fetch.
  • SimpleEncoding $encoding: GET/POST parameters.
  • integer $depth: Nested frameset depth protection.
forward (line 608)

Equivalent to hitting the forward button on the browser. The browser history is unchanged on failure. The page content is refetched as there is no concept of content caching in SimpleTest.

  • return: True if history entry and fetch succeeded
  • access: public
boolean forward ()
get (line 497)

Fetches the page content with a simple GET request.

  • return: Content of page or false.
  • access: public
string get (string/SimpleUrl $url, [hash/SimpleFormEncoding $parameters = false])
  • string/SimpleUrl $url: Target to fetch.
  • hash/SimpleFormEncoding $parameters: Additional parameters for GET request.
getAuthentication (line 729)

Accessor for last Authentication type. Only valid straight after a challenge (401).

  • return: Description of challenge type.
  • access: public
string getAuthentication ()
getBaseUrl (line 758)

Accessor for base URL of page if set via BASE tag

  • return: base URL
string getBaseUrl ()
getContent (line 786)

Accessor for raw page information.

  • return: Original text content of web page.
  • access: public
string getContent ()
getContentAsText (line 795)

Accessor for plain text version of the page.

  • return: Normalised text representation.
  • access: public
string getContentAsText ()
getCookieValue (line 411)

Reads the most specific cookie value from the browser cookies.

  • return: False if not present, else the value as a string.
  • access: public
string getCookieValue (string $host, string $path, string $name)
  • string $host: Host to search.
  • string $path: Applicable path.
  • string $name: Name of cookie to read.
getCurrentCookieValue (line 422)

Reads the current cookies for the current URL.

  • return: Null if there is no current URL, false if the cookie is not set.
  • access: public
string getCurrentCookieValue (string $name)
  • string $name: Key of cookie to find.
getField (line 861)

Accessor for a form element value within the page.

Finds the first match.

  • return: A value if the field is present, false if unchecked and null if missing.
  • access: public
string/boolean getField (string $label)
  • string $label: Field label.
getFieldById (line 886)

Accessor for a form element value within the page.

  • return: A string if the field is present, false if unchecked and null if missing.
  • access: public
string/boolean getFieldById (string/integer $id)
  • string/integer $id: Id of field in forms.
getFieldByName (line 874)

Accessor for a form element value within the page.

Finds the first match.

  • return: A string if the field is present, false if unchecked and null if missing.
  • access: public
string/boolean getFieldByName (string $name)
  • string $name: Field name.
getFrameFocus (line 663)

Accessor for current frame focus. Will be false if no frame has focus.

  • return: Label if any, otherwise the position in the frameset or false if none.
  • access: public
integer/string/boolean getFrameFocus ()
getFrames (line 651)

Accessor for a breakdown of the frameset.

  • return: Hash tree of frames by name or index if no name.
  • access: public
array getFrames ()
getHeaders (line 777)

Accessor for raw header information.

  • return: Header block.
  • access: public
string getHeaders ()
getLink (line 1062)

Finds a URL by label. Will find the first link found with this link text by default, or a later one if an index is given. The match ignores case and white space issues.

  • return: URL on success.
  • access: public
string/boolean getLink (string $label, [integer $index = 0])
  • string $label: Text between the anchor tags.
  • integer $index: Link position counting from zero.
getLinkById (line 1098)

Finds a link by id attribute.

  • return: URL on success.
  • access: public
string/boolean getLinkById (string $id)
  • string $id: ID attribute value.
getMimeType (line 710)

Accessor for current MIME type.

  • return: MIME type as string; e.g. 'text/html'
  • access: public
string getMimeType ()
getParser (line 208)

Get the HTML parser to use. Can be overridden by setParser. Otherwise scans through the available parsers and uses the first one which is available.

  • return: or SimpleTidyPageBuilder
  • access: protected
object SimplePHPPageBuilder getParser ()
getRealm (line 739)

Accessor for last Authentication realm. Only valid straight after a challenge (401).

  • return: Name of security realm.
  • access: public
string getRealm ()
getRequest (line 768)

Accessor for raw bytes sent down the wire.

  • return: Original text sent.
  • access: public
string getRequest ()
getResponseCode (line 719)

Accessor for last response code.

  • return: Last HTTP response code received.
  • access: public
integer getResponseCode ()
getTitle (line 804)

Accessor for parsed title.

  • return: Title or false if no title is present.
  • access: public
string getTitle ()
getTransportError (line 701)

Accessor for last error.

  • return: Error from last response.
  • access: public
string getTransportError ()
getUrl (line 749)

Accessor for current URL of page or frame if focused.

  • return: Location of current page or frame as a string.
string getUrl ()
getUrls (line 814)

Accessor for a list of all links in current page.

  • return: List of urls with scheme of http or https and hostname.
  • access: public
array getUrls ()
head (line 477)

Fetches the page content with a HEAD request.

Will affect cookies, but will not change the base URL.

  • return: True if successful.
  • access: public
boolean head (string/SimpleUrl $url, [hash/SimpleHeadEncoding $parameters = false])
  • string/SimpleUrl $url: Target to fetch as string.
  • hash/SimpleHeadEncoding $parameters: Additional parameters for HEAD request.
ignoreCookies (line 249)

Switches off cookie sending and recieving.

  • access: public
void ignoreCookies ()
ignoreFrames (line 232)

Disables frames support. Frames will not be fetched and the frameset page will be used instead.

  • access: public
void ignoreFrames ()
isClickable (line 1140)

Tests to see if a click target exists.

  • return: True if target present.
  • access: public
boolean isClickable (string $label)
  • string $label: Visible text or alt text.
isImage (line 1031)

Tests to see if an image exists with this title or alt text.

  • return: True if present.
  • access: public
boolean isImage (string $label)
  • string $label: Image text.
isSubmit (line 952)

Tests to see if a submit button exists with this label.

  • return: True if present.
  • access: public
boolean isSubmit (string $label)
  • string $label: Button label.
load (line 318)

Fetches a page or a single frame if that is the current focus.

  • return: Raw content of page.
  • access: protected
string load (SimpleUrl $url, SimpleEncoding $parameters)
loadFrame (line 350)

Fetches a frame into the existing frameset replacing the original.

  • return: Raw content of page.
  • access: protected
string loadFrame (array $frames, string/SimpleUrl $url, SimpleFormEncoding $parameters)
  • array $frames: List of names to drill down.
  • string/SimpleUrl $url: Target to fetch as string.
  • SimpleFormEncoding $parameters: POST parameters.
loadPage (line 333)

Fetches a page and makes it the current page/frame.

  • return: Raw content of page.
  • access: protected
string loadPage (string/SimpleUrl $url, SimplePostEncoding $parameters)
  • string/SimpleUrl $url: Target to fetch as string.
  • SimplePostEncoding $parameters: POST parameters.
parse (line 269)

Parses the raw content into a page. Will load further frame pages unless frames are disabled.

  • return: Parsed HTML.
  • access: protected
SimplePage parse (SimpleHttpResponse $response, [integer $depth = 0])
  • SimpleHttpResponse $response: Response from fetch.
  • integer $depth: Nested frameset depth.
post (line 515)

Fetches the page content with a POST request.

  • return: Content of page.
  • access: public
string post (string/SimpleUrl $url, [hash/SimpleFormEncoding $parameters = false], [string $content_type = false])
  • string/SimpleUrl $url: Target to fetch as string.
  • hash/SimpleFormEncoding $parameters: POST parameters or request body.
  • string $content_type: MIME Content-Type of the request body
put (line 533)

Fetches the page content with a PUT request.

  • return: Content of page.
  • access: public
string put (string/SimpleUrl $url, [hash/SimpleFormEncoding $parameters = false], [string $content_type = false])
  • string/SimpleUrl $url: Target to fetch as string.
  • hash/SimpleFormEncoding $parameters: PUT request body.
  • string $content_type: MIME Content-Type of the request body
restart (line 364)

Removes expired and temporary cookies as if the browser was closed and re-opened.

  • access: public
void restart ([string/integer $date = false])
  • string/integer $date: Time when session restarted. If omitted then all persistent cookies are kept.
retry (line 563)

Equivalent to hitting the retry button on the browser. Will attempt to repeat the page fetch. If there is no history to repeat it will give false.

  • return: Content if fetch succeeded else false.
  • access: public
string/boolean retry ()
setConnectionTimeout (line 451)

Sets the socket timeout for opening a connection.

  • access: public
void setConnectionTimeout (integer $timeout)
  • integer $timeout: Maximum time in seconds.
setCookie (line 397)

Sets an additional cookie. If a cookie has the same name and path it is replaced.

  • access: public
void setCookie (string $name, string $value, [string $host = false], [string $path = '/'], [string $expiry = false])
  • string $name: Cookie key.
  • string $value: Value of cookie.
  • string $host: Host upon which the cookie is valid.
  • string $path: Cookie path if not host wide.
  • string $expiry: Expiry date.
setField (line 825)

Sets all form fields with that name.

  • return: True if field exists, otherwise false.
  • access: public
boolean setField (string $label, string $value, [ $position = false])
  • string $label: Name or label of field in forms.
  • string $value: New value of field.
  • $position
setFieldById (line 848)

Sets all form fields with that id attribute.

  • return: True if field exists, otherwise false.
  • access: public
boolean setFieldById (string/integer $id, string $value)
  • string/integer $id: Id of field in forms.
  • string $value: New value of field.
setFieldByName (line 837)

Sets all form fields with that name. Will use label if one is available (not yet implemented).

  • return: True if field exists, otherwise false.
  • access: public
boolean setFieldByName (string $name, string $value, [ $position = false])
  • string $name: Name of field in forms.
  • string $value: New value of field.
  • $position
setFrameFocus (line 683)

Sets the focus by name.

  • return: True if frame exists.
  • access: public
boolean setFrameFocus (string $name)
  • string $name: Chosen frame.
setFrameFocusByIndex (line 673)

Sets the focus by index. The integer index starts from 1.

  • return: True if frame exists.
  • access: public
boolean setFrameFocusByIndex (integer $choice)
  • integer $choice: Chosen frame.
setMaximumNestedFrames (line 442)

Sets the maximum number of nesting of framed pages within a framed page to prevent loops.

  • access: public
void setMaximumNestedFrames (integer $max)
  • integer $max: Highest depth allowed.
setMaximumRedirects (line 432)

Sets the maximum number of redirects before a page will be loaded anyway.

  • access: public
void setMaximumRedirects (integer $max)
  • integer $max: Most hops allowed.
setParser (line 223)

Override the default HTML parser, allowing parsers to be plugged in.

  • access: public
void setParser (object A $parser)
  • object A $parser: parser object instance.
submitFormById (line 1042)

Submits a form by the ID.

  • return: Page on success.
  • access: public
string/boolean submitFormById (string $id)
  • string $id: The form ID. No submit button value will be sent.
useCookies (line 257)

Switches back on the cookie sending and recieving.

  • access: public
void useCookies ()
useFrames (line 241)

Enables frames support. Frames will be fetched from now on.

  • access: public
void useFrames ()
useProxy (line 464)

Sets proxy to use on all requests for when testing from behind a firewall. Set URL to false to disable.

  • access: public
void useProxy (string $proxy, [string $username = false], [string $password = false])
  • string $proxy: Proxy URL.
  • string $username: Proxy username for authentication.
  • string $password: Proxy password for authentication.

Documentation generated on Sun, 31 Oct 2010 16:31:00 -0500 by phpDocumentor 1.4.3