Source for file browser.php

Documentation is available at browser.php

  1. <?php
  2. /**
  3.  *  Base include file for SimpleTest
  4.  *  @package    SimpleTest
  5.  *  @subpackage WebTester
  6.  *  @version    $Id: browser.php 1940 2009-08-05 17:49:31Z dgheath $
  7.  */
  8.  
  9. /**#@+
  10.  *  include other SimpleTest class files
  11.  */
  12. require_once(dirname(__FILE__) . '/simpletest.php');
  13. require_once(dirname(__FILE__) . '/http.php');
  14. require_once(dirname(__FILE__) . '/encoding.php');
  15. require_once(dirname(__FILE__) . '/page.php');
  16. require_once(dirname(__FILE__) . '/php_parser.php');
  17. require_once(dirname(__FILE__) . '/tidy_parser.php');
  18. require_once(dirname(__FILE__) . '/selector.php');
  19. require_once(dirname(__FILE__) . '/frames.php');
  20. require_once(dirname(__FILE__) . '/user_agent.php');
  21. if (! SimpleTest::getParsers()) {
  22.     SimpleTest::setParsers(array(new SimplePHPPageBuilder()));
  23. }
  24. /**#@-*/
  25.  
  26. if (!defined('DEFAULT_MAX_NESTED_FRAMES')) {
  27.     define('DEFAULT_MAX_NESTED_FRAMES', 3);
  28. }
  29.  
  30. /**
  31.  *    Browser history list.
  32.  *    @package SimpleTest
  33.  *    @subpackage WebTester
  34.  */
  35. class SimpleBrowserHistory {
  36.     private $sequence;
  37.     private $position;
  38.  
  39.     /**
  40.      *    Starts empty.
  41.      *    @access public
  42.      */
  43.     function __construct() {
  44.         $this->sequence = array();
  45.         $this->position = -1;
  46.     }
  47.  
  48.     /**
  49.      *    Test for no entries yet.
  50.      *    @return boolean        True if empty.
  51.      *    @access private
  52.      */
  53.     protected function isEmpty() {
  54.         return ($this->position == -1);
  55.     }
  56.  
  57.     /**
  58.      *    Test for being at the beginning.
  59.      *    @return boolean        True if first.
  60.      *    @access private
  61.      */
  62.     protected function atBeginning() {
  63.         return ($this->position == 0) && ! $this->isEmpty();
  64.     }
  65.  
  66.     /**
  67.      *    Test for being at the last entry.
  68.      *    @return boolean        True if last.
  69.      *    @access private
  70.      */
  71.     protected function atEnd() {
  72.         return ($this->position + 1 >= count($this->sequence)) && ! $this->isEmpty();
  73.     }
  74.  
  75.     /**
  76.      *    Adds a successfully fetched page to the history.
  77.      *    @param SimpleUrl $url                 URL of fetch.
  78.      *    @param SimpleEncoding $parameters     Any post data with the fetch.
  79.      *    @access public
  80.      */
  81.     function recordEntry($url, $parameters) {
  82.         $this->dropFuture();
  83.         array_push(
  84.                 $this->sequence,
  85.                 array('url' => $url, 'parameters' => $parameters));
  86.         $this->position++;
  87.     }
  88.  
  89.     /**
  90.      *    Last fully qualified URL for current history
  91.      *    position.
  92.      *    @return SimpleUrl        URL for this position.
  93.      *    @access public
  94.      */
  95.     function getUrl() {
  96.         if ($this->isEmpty()) {
  97.             return false;
  98.         }
  99.         return $this->sequence[$this->position]['url'];
  100.     }
  101.  
  102.     /**
  103.      *    Parameters of last fetch from current history
  104.      *    position.
  105.      *    @return SimpleFormEncoding    Post parameters.
  106.      *    @access public
  107.      */
  108.     function getParameters() {
  109.         if ($this->isEmpty()) {
  110.             return false;
  111.         }
  112.         return $this->sequence[$this->position]['parameters'];
  113.     }
  114.  
  115.     /**
  116.      *    Step back one place in the history. Stops at
  117.      *    the first page.
  118.      *    @return boolean     True if any previous entries.
  119.      *    @access public
  120.      */
  121.     function back() {
  122.         if ($this->isEmpty() || $this->atBeginning()) {
  123.             return false;
  124.         }
  125.         $this->position--;
  126.         return true;
  127.     }
  128.  
  129.     /**
  130.      *    Step forward one place. If already at the
  131.      *    latest entry then nothing will happen.
  132.      *    @return boolean     True if any future entries.
  133.      *    @access public
  134.      */
  135.     function forward() {
  136.         if ($this->isEmpty() || $this->atEnd()) {
  137.             return false;
  138.         }
  139.         $this->position++;
  140.         return true;
  141.     }
  142.  
  143.     /**
  144.      *    Ditches all future entries beyond the current
  145.      *    point.
  146.      *    @access private
  147.      */
  148.     protected function dropFuture() {
  149.         if ($this->isEmpty()) {
  150.             return;
  151.         }
  152.         while (! $this->atEnd()) {
  153.             array_pop($this->sequence);
  154.         }
  155.     }
  156. }
  157.  
  158. /**
  159.  *    Simulated web browser. This is an aggregate of
  160.  *    the user agent, the HTML parsing, request history
  161.  *    and the last header set.
  162.  *    @package SimpleTest
  163.  *    @subpackage WebTester
  164.  */
  165. class SimpleBrowser {
  166.     private $user_agent;
  167.     private $page;
  168.     private $history;
  169.     private $ignore_frames;
  170.     private $maximum_nested_frames;
  171.     private $parser;
  172.  
  173.     /**
  174.      *    Starts with a fresh browser with no
  175.      *    cookie or any other state information. The
  176.      *    exception is that a default proxy will be
  177.      *    set up if specified in the options.
  178.      *    @access public
  179.      */
  180.     function __construct() {
  181.         $this->user_agent = $this->createUserAgent();
  182.         $this->user_agent->useProxy(
  183.                 SimpleTest::getDefaultProxy(),
  184.                 SimpleTest::getDefaultProxyUsername(),
  185.                 SimpleTest::getDefaultProxyPassword());
  186.         $this->page = new SimplePage();
  187.         $this->history = $this->createHistory();
  188.         $this->ignore_frames = false;
  189.         $this->maximum_nested_frames = DEFAULT_MAX_NESTED_FRAMES;
  190.     }
  191.  
  192.     /**
  193.      *    Creates the underlying user agent.
  194.      *    @return SimpleFetcher    Content fetcher.
  195.      *    @access protected
  196.      */
  197.     protected function createUserAgent() {
  198.         return new SimpleUserAgent();
  199.     }
  200.  
  201.     /**
  202.      *    Creates a new empty history list.
  203.      *    @return SimpleBrowserHistory    New list.
  204.      *    @access protected
  205.      */
  206.     protected function createHistory() {
  207.         return new SimpleBrowserHistory();
  208.     }
  209.  
  210.     /**
  211.      *    Get the HTML parser to use. Can be overridden by
  212.      *    setParser. Otherwise scans through the available parsers and
  213.      *    uses the first one which is available.
  214.      *    @return object SimplePHPPageBuilder or SimpleTidyPageBuilder
  215.      */
  216.     protected function getParser() {
  217.         if ($this->parser) {
  218.             return $this->parser;
  219.         }
  220.         foreach (SimpleTest::getParsers() as $parser) {
  221.             if ($parser->can()) {
  222.                 return $parser;
  223.             }
  224.         }
  225.     }
  226.  
  227.     /**
  228.      *    Override the default HTML parser, allowing parsers to be plugged in.
  229.      *    @param object           A parser object instance.
  230.      */
  231.     public function setParser($parser) {
  232.         $this->parser = $parser;
  233.     }
  234.  
  235.     /**
  236.      *    Disables frames support. Frames will not be fetched
  237.      *    and the frameset page will be used instead.
  238.      *    @access public
  239.      */
  240.     function ignoreFrames() {
  241.         $this->ignore_frames = true;
  242.     }
  243.  
  244.     /**
  245.      *    Enables frames support. Frames will be fetched from
  246.      *    now on.
  247.      *    @access public
  248.      */
  249.     function useFrames() {
  250.         $this->ignore_frames = false;
  251.     }
  252.  
  253.     /**
  254.      *    Switches off cookie sending and recieving.
  255.      *    @access public
  256.      */
  257.     function ignoreCookies() {
  258.         $this->user_agent->ignoreCookies();
  259.     }
  260.  
  261.     /**
  262.      *    Switches back on the cookie sending and recieving.
  263.      *    @access public
  264.      */
  265.     function useCookies() {
  266.         $this->user_agent->useCookies();
  267.     }
  268.  
  269.     /**
  270.      *    Parses the raw content into a page. Will load further
  271.      *    frame pages unless frames are disabled.
  272.      *    @param SimpleHttpResponse $response    Response from fetch.
  273.      *    @param integer $depth                  Nested frameset depth.
  274.      *    @return SimplePage                     Parsed HTML.
  275.      *    @access private
  276.      */
  277.     protected function parse($response, $depth = 0) {
  278.         $page = $this->buildPage($response);
  279.         if ($this->ignore_frames || ! $page->hasFrames() || ($depth > $this->maximum_nested_frames)) {
  280.             return $page;
  281.         }
  282.         $frameset = new SimpleFrameset($page);
  283.         foreach ($page->getFrameset() as $key => $url) {
  284.             $frame = $this->fetch($url, new SimpleGetEncoding(), $depth + 1);
  285.             $frameset->addFrame($frame, $key);
  286.         }
  287.         return $frameset;
  288.     }
  289.  
  290.     /**
  291.      *    Assembles the parsing machinery and actually parses
  292.      *    a single page. Frees all of the builder memory and so
  293.      *    unjams the PHP memory management.
  294.      *    @param SimpleHttpResponse $response    Response from fetch.
  295.      *    @return SimplePage                     Parsed top level page.
  296.      */
  297.     protected function buildPage($response) {
  298.         return $this->getParser()->parse($response);
  299.     }
  300.  
  301.     /**
  302.      *    Fetches a page. Jointly recursive with the parse()
  303.      *    method as it descends a frameset.
  304.      *    @param string/SimpleUrl $url          Target to fetch.
  305.      *    @param SimpleEncoding $encoding       GET/POST parameters.
  306.      *    @param integer $depth                 Nested frameset depth protection.
  307.      *    @return SimplePage                    Parsed page.
  308.      *    @access private
  309.      */
  310.     protected function fetch($url, $encoding, $depth = 0) {
  311.         $response = $this->user_agent->fetchResponse($url, $encoding);
  312.         if ($response->isError()) {
  313.             return new SimplePage($response);
  314.         }
  315.         return $this->parse($response, $depth);
  316.     }
  317.  
  318.     /**
  319.      *    Fetches a page or a single frame if that is the current
  320.      *    focus.
  321.      *    @param SimpleUrl $url                   Target to fetch.
  322.      *    @param SimpleEncoding $parameters       GET/POST parameters.
  323.      *    @return string                          Raw content of page.
  324.      *    @access private
  325.      */
  326.     protected function load($url, $parameters) {
  327.         $frame = $url->getTarget();
  328.         if (! $frame || ! $this->page->hasFrames() || (strtolower($frame) == '_top')) {
  329.             return $this->loadPage($url, $parameters);
  330.         }
  331.         return $this->loadFrame(array($frame), $url, $parameters);
  332.     }
  333.  
  334.     /**
  335.      *    Fetches a page and makes it the current page/frame.
  336.      *    @param string/SimpleUrl $url            Target to fetch as string.
  337.      *    @param SimplePostEncoding $parameters   POST parameters.
  338.      *    @return string                          Raw content of page.
  339.      *    @access private
  340.      */
  341.     protected function loadPage($url, $parameters) {
  342.         $this->page = $this->fetch($url, $parameters);
  343.         $this->history->recordEntry(
  344.                 $this->page->getUrl(),
  345.                 $this->page->getRequestData());
  346.         return $this->page->getRaw();
  347.     }
  348.  
  349.     /**
  350.      *    Fetches a frame into the existing frameset replacing the
  351.      *    original.
  352.      *    @param array $frames                    List of names to drill down.
  353.      *    @param string/SimpleUrl $url            Target to fetch as string.
  354.      *    @param SimpleFormEncoding $parameters   POST parameters.
  355.      *    @return string                          Raw content of page.
  356.      *    @access private
  357.      */
  358.     protected function loadFrame($frames, $url, $parameters) {
  359.         $page = $this->fetch($url, $parameters);
  360.         $this->page->setFrame($frames, $page);
  361.         return $page->getRaw();
  362.     }
  363.  
  364.     /**
  365.      *    Removes expired and temporary cookies as if
  366.      *    the browser was closed and re-opened.
  367.      *    @param string/integer $date   Time when session restarted.
  368.      *                                   If omitted then all persistent
  369.      *                                   cookies are kept.
  370.      *    @access public
  371.      */
  372.     function restart($date = false) {
  373.         $this->user_agent->restart($date);
  374.     }
  375.  
  376.     /**
  377.      *    Adds a header to every fetch.
  378.      *    @param string $header       Header line to add to every
  379.      *                                 request until cleared.
  380.      *    @access public
  381.      */
  382.     function addHeader($header) {
  383.         $this->user_agent->addHeader($header);
  384.     }
  385.  
  386.     /**
  387.      *    Ages the cookies by the specified time.
  388.      *    @param integer $interval    Amount in seconds.
  389.      *    @access public
  390.      */
  391.     function ageCookies($interval) {
  392.         $this->user_agent->ageCookies($interval);
  393.     }
  394.  
  395.     /**
  396.      *    Sets an additional cookie. If a cookie has
  397.      *    the same name and path it is replaced.
  398.      *    @param string $name       Cookie key.
  399.      *    @param string $value      Value of cookie.
  400.      *    @param string $host       Host upon which the cookie is valid.
  401.      *    @param string $path       Cookie path if not host wide.
  402.      *    @param string $expiry     Expiry date.
  403.      *    @access public
  404.      */
  405.     function setCookie($name, $value, $host = false, $path = '/', $expiry = false) {
  406.         $this->user_agent->setCookie($name, $value, $host, $path, $expiry);
  407.     }
  408.  
  409.     /**
  410.      *    Reads the most specific cookie value from the
  411.      *    browser cookies.
  412.      *    @param string $host        Host to search.
  413.      *    @param string $path        Applicable path.
  414.      *    @param string $name        Name of cookie to read.
  415.      *    @return string             False if not present, else the
  416.      *                                value as a string.
  417.      *    @access public
  418.      */
  419.     function getCookieValue($host, $path, $name) {
  420.         return $this->user_agent->getCookieValue($host, $path, $name);
  421.     }
  422.  
  423.     /**
  424.      *    Reads the current cookies for the current URL.
  425.      *    @param string $name   Key of cookie to find.
  426.      *    @return string        Null if there is no current URL, false
  427.      *                           if the cookie is not set.
  428.      *    @access public
  429.      */
  430.     function getCurrentCookieValue($name) {
  431.         return $this->user_agent->getBaseCookieValue($name, $this->page->getUrl());
  432.     }
  433.  
  434.     /**
  435.      *    Sets the maximum number of redirects before
  436.      *    a page will be loaded anyway.
  437.      *    @param integer $max        Most hops allowed.
  438.      *    @access public
  439.      */
  440.     function setMaximumRedirects($max) {
  441.         $this->user_agent->setMaximumRedirects($max);
  442.     }
  443.  
  444.     /**
  445.      *    Sets the maximum number of nesting of framed pages
  446.      *    within a framed page to prevent loops.
  447.      *    @param integer $max        Highest depth allowed.
  448.      *    @access public
  449.      */
  450.     function setMaximumNestedFrames($max) {
  451.         $this->maximum_nested_frames = $max;
  452.     }
  453.  
  454.     /**
  455.      *    Sets the socket timeout for opening a connection.
  456.      *    @param integer $timeout      Maximum time in seconds.
  457.      *    @access public
  458.      */
  459.     function setConnectionTimeout($timeout) {
  460.         $this->user_agent->setConnectionTimeout($timeout);
  461.     }
  462.  
  463.     /**
  464.      *    Sets proxy to use on all requests for when
  465.      *    testing from behind a firewall. Set URL
  466.      *    to false to disable.
  467.      *    @param string $proxy        Proxy URL.
  468.      *    @param string $username     Proxy username for authentication.
  469.      *    @param string $password     Proxy password for authentication.
  470.      *    @access public
  471.      */
  472.     function useProxy($proxy, $username = false, $password = false) {
  473.         $this->user_agent->useProxy($proxy, $username, $password);
  474.     }
  475.  
  476.     /**
  477.      *    Fetches the page content with a HEAD request.
  478.      *    Will affect cookies, but will not change the base URL.
  479.      *    @param string/SimpleUrl $url                Target to fetch as string.
  480.      *    @param hash/SimpleHeadEncoding $parameters  Additional parameters for
  481.      *                                                 HEAD request.
  482.      *    @return boolean                             True if successful.
  483.      *    @access public
  484.      */
  485.     function head($url, $parameters = false) {
  486.         if (! is_object($url)) {
  487.             $url = new SimpleUrl($url);
  488.         }
  489.         if ($this->getUrl()) {
  490.             $url = $url->makeAbsolute($this->getUrl());
  491.         }
  492.         $response = &$this->user_agent->fetchResponse($url, new SimpleHeadEncoding($parameters));
  493.         return ! $response->isError();
  494.     }
  495.  
  496.     /**
  497.      *    Fetches the page content with a simple GET request.
  498.      *    @param string/SimpleUrl $url                Target to fetch.
  499.      *    @param hash/SimpleFormEncoding $parameters  Additional parameters for
  500.      *                                                 GET request.
  501.      *    @return string                              Content of page or false.
  502.      *    @access public
  503.      */
  504.     function get($url, $parameters = false) {
  505.         if (! is_object($url)) {
  506.             $url = new SimpleUrl($url);
  507.         }
  508.         if ($this->getUrl()) {
  509.             $url = $url->makeAbsolute($this->getUrl());
  510.         }
  511.         return $this->load($url, new SimpleGetEncoding($parameters));
  512.     }
  513.  
  514.     /**
  515.      *    Fetches the page content with a POST request.
  516.      *    @param string/SimpleUrl $url                Target to fetch as string.
  517.      *    @param hash/SimpleFormEncoding $parameters  POST parameters.
  518.      *    @return string                              Content of page.
  519.      *    @access public
  520.      */
  521.     function post($url, $parameters = false) {
  522.         if (! is_object($url)) {
  523.             $url = new SimpleUrl($url);
  524.         }
  525.         if ($this->getUrl()) {
  526.             $url = $url->makeAbsolute($this->getUrl());
  527.         }
  528.         return $this->load($url, new SimplePostEncoding($parameters));
  529.     }
  530.  
  531.     /**
  532.      *    Equivalent to hitting the retry button on the
  533.      *    browser. Will attempt to repeat the page fetch. If
  534.      *    there is no history to repeat it will give false.
  535.      *    @return string/boolean   Content if fetch succeeded
  536.      *                              else false.
  537.      *    @access public
  538.      */
  539.     function retry() {
  540.         $frames = $this->page->getFrameFocus();
  541.         if (count($frames) > 0) {
  542.             $this->loadFrame(
  543.                     $frames,
  544.                     $this->page->getUrl(),
  545.                     $this->page->getRequestData());
  546.             return $this->page->getRaw();
  547.         }
  548.         if ($url = $this->history->getUrl()) {
  549.             $this->page = $this->fetch($url, $this->history->getParameters());
  550.             return $this->page->getRaw();
  551.         }
  552.         return false;
  553.     }
  554.  
  555.     /**
  556.      *    Equivalent to hitting the back button on the
  557.      *    browser. The browser history is unchanged on
  558.      *    failure. The page content is refetched as there
  559.      *    is no concept of content caching in SimpleTest.
  560.      *    @return boolean     True if history entry and
  561.      *                         fetch succeeded
  562.      *    @access public
  563.      */
  564.     function back() {
  565.         if (! $this->history->back()) {
  566.             return false;
  567.         }
  568.         $content = $this->retry();
  569.         if (! $content) {
  570.             $this->history->forward();
  571.         }
  572.         return $content;
  573.     }
  574.  
  575.     /**
  576.      *    Equivalent to hitting the forward button on the
  577.      *    browser. The browser history is unchanged on
  578.      *    failure. The page content is refetched as there
  579.      *    is no concept of content caching in SimpleTest.
  580.      *    @return boolean     True if history entry and
  581.      *                         fetch succeeded
  582.      *    @access public
  583.      */
  584.     function forward() {
  585.         if (! $this->history->forward()) {
  586.             return false;
  587.         }
  588.         $content = $this->retry();
  589.         if (! $content) {
  590.             $this->history->back();
  591.         }
  592.         return $content;
  593.     }
  594.  
  595.     /**
  596.      *    Retries a request after setting the authentication
  597.      *    for the current realm.
  598.      *    @param string $username    Username for realm.
  599.      *    @param string $password    Password for realm.
  600.      *    @return boolean            True if successful fetch. Note
  601.      *                                that authentication may still have
  602.      *                                failed.
  603.      *    @access public
  604.      */
  605.     function authenticate($username, $password) {
  606.         if (! $this->page->getRealm()) {
  607.             return false;
  608.         }
  609.         $url = $this->page->getUrl();
  610.         if (! $url) {
  611.             return false;
  612.         }
  613.         $this->user_agent->setIdentity(
  614.                 $url->getHost(),
  615.                 $this->page->getRealm(),
  616.                 $username,
  617.                 $password);
  618.         return $this->retry();
  619.     }
  620.  
  621.     /**
  622.      *    Accessor for a breakdown of the frameset.
  623.      *    @return array   Hash tree of frames by name
  624.      *                     or index if no name.
  625.      *    @access public
  626.      */
  627.     function getFrames() {
  628.         return $this->page->getFrames();
  629.     }
  630.  
  631.     /**
  632.      *    Accessor for current frame focus. Will be
  633.      *    false if no frame has focus.
  634.      *    @return integer/string/boolean    Label if any, otherwise
  635.      *                                       the position in the frameset
  636.      *                                       or false if none.
  637.      *    @access public
  638.      */
  639.     function getFrameFocus() {
  640.         return $this->page->getFrameFocus();
  641.     }
  642.  
  643.     /**
  644.      *    Sets the focus by index. The integer index starts from 1.
  645.      *    @param integer $choice    Chosen frame.
  646.      *    @return boolean           True if frame exists.
  647.      *    @access public
  648.      */
  649.     function setFrameFocusByIndex($choice) {
  650.         return $this->page->setFrameFocusByIndex($choice);
  651.     }
  652.  
  653.     /**
  654.      *    Sets the focus by name.
  655.      *    @param string $name    Chosen frame.
  656.      *    @return boolean        True if frame exists.
  657.      *    @access public
  658.      */
  659.     function setFrameFocus($name) {
  660.         return $this->page->setFrameFocus($name);
  661.     }
  662.  
  663.     /**
  664.      *    Clears the frame focus. All frames will be searched
  665.      *    for content.
  666.      *    @access public
  667.      */
  668.     function clearFrameFocus() {
  669.         return $this->page->clearFrameFocus();
  670.     }
  671.  
  672.     /**
  673.      *    Accessor for last error.
  674.      *    @return string        Error from last response.
  675.      *    @access public
  676.      */
  677.     function getTransportError() {
  678.         return $this->page->getTransportError();
  679.     }
  680.  
  681.     /**
  682.      *    Accessor for current MIME type.
  683.      *    @return string    MIME type as string; e.g. 'text/html'
  684.      *    @access public
  685.      */
  686.     function getMimeType() {
  687.         return $this->page->getMimeType();
  688.     }
  689.  
  690.     /**
  691.      *    Accessor for last response code.
  692.      *    @return integer    Last HTTP response code received.
  693.      *    @access public
  694.      */
  695.     function getResponseCode() {
  696.         return $this->page->getResponseCode();
  697.     }
  698.  
  699.     /**
  700.      *    Accessor for last Authentication type. Only valid
  701.      *    straight after a challenge (401).
  702.      *    @return string    Description of challenge type.
  703.      *    @access public
  704.      */
  705.     function getAuthentication() {
  706.         return $this->page->getAuthentication();
  707.     }
  708.  
  709.     /**
  710.      *    Accessor for last Authentication realm. Only valid
  711.      *    straight after a challenge (401).
  712.      *    @return string    Name of security realm.
  713.      *    @access public
  714.      */
  715.     function getRealm() {
  716.         return $this->page->getRealm();
  717.     }
  718.  
  719.     /**
  720.      *    Accessor for current URL of page or frame if
  721.      *    focused.
  722.      *    @return string    Location of current page or frame as
  723.      *                       a string.
  724.      */
  725.     function getUrl() {
  726.         $url = $this->page->getUrl();
  727.         return $url ? $url->asString() : false;
  728.     }
  729.  
  730.     /**
  731.      *    Accessor for base URL of page if set via BASE tag
  732.      *    @return string    base URL
  733.      */
  734.     function getBaseUrl() {
  735.         $url = $this->page->getBaseUrl();
  736.         return $url ? $url->asString() : false;
  737.     }
  738.  
  739.     /**
  740.      *    Accessor for raw bytes sent down the wire.
  741.      *    @return string      Original text sent.
  742.      *    @access public
  743.      */
  744.     function getRequest() {
  745.         return $this->page->getRequest();
  746.     }
  747.  
  748.     /**
  749.      *    Accessor for raw header information.
  750.      *    @return string      Header block.
  751.      *    @access public
  752.      */
  753.     function getHeaders() {
  754.         return $this->page->getHeaders();
  755.     }
  756.  
  757.     /**
  758.      *    Accessor for raw page information.
  759.      *    @return string      Original text content of web page.
  760.      *    @access public
  761.      */
  762.     function getContent() {
  763.         return $this->page->getRaw();
  764.     }
  765.  
  766.     /**
  767.      *    Accessor for plain text version of the page.
  768.      *    @return string      Normalised text representation.
  769.      *    @access public
  770.      */
  771.     function getContentAsText() {
  772.         return $this->page->getText();
  773.     }
  774.  
  775.     /**
  776.      *    Accessor for parsed title.
  777.      *    @return string     Title or false if no title is present.
  778.      *    @access public
  779.      */
  780.     function getTitle() {
  781.         return $this->page->getTitle();
  782.     }
  783.  
  784.     /**
  785.      *    Accessor for a list of all links in current page.
  786.      *    @return array   List of urls with scheme of
  787.      *                     http or https and hostname.
  788.      *    @access public
  789.      */
  790.     function getUrls() {
  791.         return $this->page->getUrls();
  792.     }
  793.  
  794.     /**
  795.      *    Sets all form fields with that name.
  796.      *    @param string $label   Name or label of field in forms.
  797.      *    @param string $value   New value of field.
  798.      *    @return boolean        True if field exists, otherwise false.
  799.      *    @access public
  800.      */
  801.     function setField($label, $value, $position=false) {
  802.         return $this->page->setField(new SimpleByLabelOrName($label), $value, $position);
  803.     }
  804.  
  805.     /**
  806.      *    Sets all form fields with that name. Will use label if
  807.      *    one is available (not yet implemented).
  808.      *    @param string $name    Name of field in forms.
  809.      *    @param string $value   New value of field.
  810.      *    @return boolean        True if field exists, otherwise false.
  811.      *    @access public
  812.      */
  813.     function setFieldByName($name, $value, $position=false) {
  814.         return $this->page->setField(new SimpleByName($name), $value, $position);
  815.     }
  816.  
  817.     /**
  818.      *    Sets all form fields with that id attribute.
  819.      *    @param string/integer $id   Id of field in forms.
  820.      *    @param string $value        New value of field.
  821.      *    @return boolean             True if field exists, otherwise false.
  822.      *    @access public
  823.      */
  824.     function setFieldById($id, $value) {
  825.         return $this->page->setField(new SimpleById($id), $value);
  826.     }
  827.  
  828.     /**
  829.      *    Accessor for a form element value within the page.
  830.      *    Finds the first match.
  831.      *    @param string $label       Field label.
  832.      *    @return string/boolean     A value if the field is
  833.      *                                present, false if unchecked
  834.      *                                and null if missing.
  835.      *    @access public
  836.      */
  837.     function getField($label) {
  838.         return $this->page->getField(new SimpleByLabelOrName($label));
  839.     }
  840.  
  841.     /**
  842.      *    Accessor for a form element value within the page.
  843.      *    Finds the first match.
  844.      *    @param string $name        Field name.
  845.      *    @return string/boolean     A string if the field is
  846.      *                                present, false if unchecked
  847.      *                                and null if missing.
  848.      *    @access public
  849.      */
  850.     function getFieldByName($name) {
  851.         return $this->page->getField(new SimpleByName($name));
  852.     }
  853.  
  854.     /**
  855.      *    Accessor for a form element value within the page.
  856.      *    @param string/integer $id  Id of field in forms.
  857.      *    @return string/boolean     A string if the field is
  858.      *                                present, false if unchecked
  859.      *                                and null if missing.
  860.      *    @access public
  861.      */
  862.     function getFieldById($id) {
  863.         return $this->page->getField(new SimpleById($id));
  864.     }
  865.  
  866.     /**
  867.      *    Clicks the submit button by label. The owning
  868.      *    form will be submitted by this.
  869.      *    @param string $label    Button label. An unlabeled
  870.      *                             button can be triggered by 'Submit'.
  871.      *    @param hash $additional Additional form data.
  872.      *    @return string/boolean  Page on success.
  873.      *    @access public
  874.      */
  875.     function clickSubmit($label = 'Submit', $additional = false) {
  876.         if (! ($form = $this->page->getFormBySubmit(new SimpleByLabel($label)))) {
  877.             return false;
  878.         }
  879.         $success = $this->load(
  880.                 $form->getAction(),
  881.                 $form->submitButton(new SimpleByLabel($label), $additional));
  882.         return ($success ? $this->getContent() : $success);
  883.     }
  884.  
  885.     /**
  886.      *    Clicks the submit button by name attribute. The owning
  887.      *    form will be submitted by this.
  888.      *    @param string $name     Button name.
  889.      *    @param hash $additional Additional form data.
  890.      *    @return string/boolean  Page on success.
  891.      *    @access public
  892.      */
  893.     function clickSubmitByName($name, $additional = false) {
  894.         if (! ($form = $this->page->getFormBySubmit(new SimpleByName($name)))) {
  895.             return false;
  896.         }
  897.         $success = $this->load(
  898.                 $form->getAction(),
  899.                 $form->submitButton(new SimpleByName($name), $additional));
  900.         return ($success ? $this->getContent() : $success);
  901.     }
  902.  
  903.     /**
  904.      *    Clicks the submit button by ID attribute of the button
  905.      *    itself. The owning form will be submitted by this.
  906.      *    @param string $id       Button ID.
  907.      *    @param hash $additional Additional form data.
  908.      *    @return string/boolean  Page on success.
  909.      *    @access public
  910.      */
  911.     function clickSubmitById($id, $additional = false) {
  912.         if (! ($form = $this->page->getFormBySubmit(new SimpleById($id)))) {
  913.             return false;
  914.         }
  915.         $success = $this->load(
  916.                 $form->getAction(),
  917.                 $form->submitButton(new SimpleById($id), $additional));
  918.         return ($success ? $this->getContent() : $success);
  919.     }
  920.  
  921.     /**
  922.      *    Tests to see if a submit button exists with this
  923.      *    label.
  924.      *    @param string $label    Button label.
  925.      *    @return boolean         True if present.
  926.      *    @access public
  927.      */
  928.     function isSubmit($label) {
  929.         return (boolean)$this->page->getFormBySubmit(new SimpleByLabel($label));
  930.     }
  931.  
  932.     /**
  933.      *    Clicks the submit image by some kind of label. Usually
  934.      *    the alt tag or the nearest equivalent. The owning
  935.      *    form will be submitted by this. Clicking outside of
  936.      *    the boundary of the coordinates will result in
  937.      *    a failure.
  938.      *    @param string $label    ID attribute of button.
  939.      *    @param integer $x       X-coordinate of imaginary click.
  940.      *    @param integer $y       Y-coordinate of imaginary click.
  941.      *    @param hash $additional Additional form data.
  942.      *    @return string/boolean  Page on success.
  943.      *    @access public
  944.      */
  945.     function clickImage($label, $x = 1, $y = 1, $additional = false) {
  946.         if (! ($form = $this->page->getFormByImage(new SimpleByLabel($label)))) {
  947.             return false;
  948.         }
  949.         $success = $this->load(
  950.                 $form->getAction(),
  951.                 $form->submitImage(new SimpleByLabel($label), $x, $y, $additional));
  952.         return ($success ? $this->getContent() : $success);
  953.     }
  954.  
  955.     /**
  956.      *    Clicks the submit image by the name. Usually
  957.      *    the alt tag or the nearest equivalent. The owning
  958.      *    form will be submitted by this. Clicking outside of
  959.      *    the boundary of the coordinates will result in
  960.      *    a failure.
  961.      *    @param string $name     Name attribute of button.
  962.      *    @param integer $x       X-coordinate of imaginary click.
  963.      *    @param integer $y       Y-coordinate of imaginary click.
  964.      *    @param hash $additional Additional form data.
  965.      *    @return string/boolean  Page on success.
  966.      *    @access public
  967.      */
  968.     function clickImageByName($name, $x = 1, $y = 1, $additional = false) {
  969.         if (! ($form = $this->page->getFormByImage(new SimpleByName($name)))) {
  970.             return false;
  971.         }
  972.         $success = $this->load(
  973.                 $form->getAction(),
  974.                 $form->submitImage(new SimpleByName($name), $x, $y, $additional));
  975.         return ($success ? $this->getContent() : $success);
  976.     }
  977.  
  978.     /**
  979.      *    Clicks the submit image by ID attribute. The owning
  980.      *    form will be submitted by this. Clicking outside of
  981.      *    the boundary of the coordinates will result in
  982.      *    a failure.
  983.      *    @param integer/string $id    ID attribute of button.
  984.      *    @param integer $x            X-coordinate of imaginary click.
  985.      *    @param integer $y            Y-coordinate of imaginary click.
  986.      *    @param hash $additional      Additional form data.
  987.      *    @return string/boolean       Page on success.
  988.      *    @access public
  989.      */
  990.     function clickImageById($id, $x = 1, $y = 1, $additional = false) {
  991.         if (! ($form = $this->page->getFormByImage(new SimpleById($id)))) {
  992.             return false;
  993.         }
  994.         $success = $this->load(
  995.                 $form->getAction(),
  996.                 $form->submitImage(new SimpleById($id), $x, $y, $additional));
  997.         return ($success ? $this->getContent() : $success);
  998.     }
  999.  
  1000.     /**
  1001.      *    Tests to see if an image exists with this
  1002.      *    title or alt text.
  1003.      *    @param string $label    Image text.
  1004.      *    @return boolean         True if present.
  1005.      *    @access public
  1006.      */
  1007.     function isImage($label) {
  1008.         return (boolean)$this->page->getFormByImage(new SimpleByLabel($label));
  1009.     }
  1010.  
  1011.     /**
  1012.      *    Submits a form by the ID.
  1013.      *    @param string $id       The form ID. No submit button value
  1014.      *                             will be sent.
  1015.      *    @return string/boolean  Page on success.
  1016.      *    @access public
  1017.      */
  1018.     function submitFormById($id) {
  1019.         if (! ($form = $this->page->getFormById($id))) {
  1020.             return false;
  1021.         }
  1022.         $success = $this->load(
  1023.                 $form->getAction(),
  1024.                 $form->submit());
  1025.         return ($success ? $this->getContent() : $success);
  1026.     }
  1027.  
  1028.     /**
  1029.      *    Finds a URL by label. Will find the first link
  1030.      *    found with this link text by default, or a later
  1031.      *    one if an index is given. The match ignores case and
  1032.      *    white space issues.
  1033.      *    @param string $label     Text between the anchor tags.
  1034.      *    @param integer $index    Link position counting from zero.
  1035.      *    @return string/boolean   URL on success.
  1036.      *    @access public
  1037.      */
  1038.     function getLink($label, $index = 0) {
  1039.         $urls = $this->page->getUrlsByLabel($label);
  1040.         if (count($urls) == 0) {
  1041.             return false;
  1042.         }
  1043.         if (count($urls) < $index + 1) {
  1044.             return false;
  1045.         }
  1046.         return $urls[$index];
  1047.     }
  1048.  
  1049.     /**
  1050.      *    Follows a link by label. Will click the first link
  1051.      *    found with this link text by default, or a later
  1052.      *    one if an index is given. The match ignores case and
  1053.      *    white space issues.
  1054.      *    @param string $label     Text between the anchor tags.
  1055.      *    @param integer $index    Link position counting from zero.
  1056.      *    @return string/boolean   Page on success.
  1057.      *    @access public
  1058.      */
  1059.     function clickLink($label, $index = 0) {
  1060.         $url = $this->getLink($label, $index);
  1061.         if ($url === false) {
  1062.             return false;
  1063.         }
  1064.         $this->load($url, new SimpleGetEncoding());
  1065.         return $this->getContent();
  1066.     }
  1067.  
  1068.     /**
  1069.      *    Finds a link by id attribute.
  1070.      *    @param string $id        ID attribute value.
  1071.      *    @return string/boolean   URL on success.
  1072.      *    @access public
  1073.      */
  1074.     function getLinkById($id) {
  1075.         return $this->page->getUrlById($id);
  1076.     }
  1077.  
  1078.     /**
  1079.      *    Follows a link by id attribute.
  1080.      *    @param string $id        ID attribute value.
  1081.      *    @return string/boolean   Page on success.
  1082.      *    @access public
  1083.      */
  1084.     function clickLinkById($id) {
  1085.         if (! ($url = $this->getLinkById($id))) {
  1086.             return false;
  1087.         }
  1088.         $this->load($url, new SimpleGetEncoding());
  1089.         return $this->getContent();
  1090.     }
  1091.  
  1092.     /**
  1093.      *    Clicks a visible text item. Will first try buttons,
  1094.      *    then links and then images.
  1095.      *    @param string $label        Visible text or alt text.
  1096.      *    @return string/boolean      Raw page or false.
  1097.      *    @access public
  1098.      */
  1099.     function click($label) {
  1100.         $raw = $this->clickSubmit($label);
  1101.         if (! $raw) {
  1102.             $raw = $this->clickLink($label);
  1103.         }
  1104.         if (! $raw) {
  1105.             $raw = $this->clickImage($label);
  1106.         }
  1107.         return $raw;
  1108.     }
  1109.  
  1110.     /**
  1111.      *    Tests to see if a click target exists.
  1112.      *    @param string $label    Visible text or alt text.
  1113.      *    @return boolean         True if target present.
  1114.      *    @access public
  1115.      */
  1116.     function isClickable($label) {
  1117.         return $this->isSubmit($label) || ($this->getLink($label) !== false) || $this->isImage($label);
  1118.     }
  1119. }
  1120. ?>

Documentation generated on Thu, 01 Oct 2009 20:54:24 -0500 by phpDocumentor 1.4.2