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

Documentation generated on Sun, 04 May 2008 09:21:19 -0500 by phpDocumentor 1.3.0