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