Source for file user_agent.php

Documentation is available at user_agent.php

  1. <?php
  2. /**
  3.  *  Base include file for SimpleTest
  4.  *  @package    SimpleTest
  5.  *  @subpackage WebTester
  6.  *  @version    $Id: user_agent.php 1723 2008-04-08 00:34:10Z lastcraft $
  7.  */
  8.  
  9. /**#@+
  10.  *  include other SimpleTest class files
  11.  */
  12. require_once(dirname(__FILE__) . '/cookies.php');
  13. require_once(dirname(__FILE__) . '/http.php');
  14. require_once(dirname(__FILE__) . '/encoding.php');
  15. require_once(dirname(__FILE__) . '/authentication.php');
  16. /**#@-*/
  17.  
  18. if (! defined('DEFAULT_MAX_REDIRECTS')) {
  19.     define('DEFAULT_MAX_REDIRECTS', 3);
  20. }
  21. if (! defined('DEFAULT_CONNECTION_TIMEOUT')) {
  22.     define('DEFAULT_CONNECTION_TIMEOUT', 15);
  23. }
  24.  
  25.  *    Fetches web pages whilst keeping track of
  26.  *    cookies and authentication.
  27.  *    @package SimpleTest
  28.  *    @subpackage WebTester
  29.  */
  30. class SimpleUserAgent {
  31.     var $_cookie_jar;
  32.     var $_cookies_enabled = true;
  33.     var $_authenticator;
  34.     var $_max_redirects = DEFAULT_MAX_REDIRECTS;
  35.     var $_proxy = false;
  36.     var $_proxy_username = false;
  37.     var $_proxy_password = false;
  38.     var $_connection_timeout = DEFAULT_CONNECTION_TIMEOUT;
  39.     var $_additional_headers = array();
  40.     
  41.     /**
  42.      *    Starts with no cookies, realms or proxies.
  43.      *    @access public
  44.      */
  45.     function SimpleUserAgent() {
  46.         $this->_cookie_jar = &new SimpleCookieJar();
  47.         $this->_authenticator = &new SimpleAuthenticator();
  48.     }
  49.     
  50.     /**
  51.      *    Removes expired and temporary cookies as if
  52.      *    the browser was closed and re-opened. Authorisation
  53.      *    has to be obtained again as well.
  54.      *    @param string/integer $date   Time when session restarted.
  55.      *                                   If omitted then all persistent
  56.      *                                   cookies are kept.
  57.      *    @access public
  58.      */
  59.     function restart($date = false) {
  60.         $this->_cookie_jar->restartSession($date);
  61.         $this->_authenticator->restartSession();
  62.     }
  63.     
  64.     /**
  65.      *    Adds a header to every fetch.
  66.      *    @param string $header       Header line to add to every
  67.      *                                 request until cleared.
  68.      *    @access public
  69.      */
  70.     function addHeader($header) {
  71.         $this->_additional_headers[] = $header;
  72.     }
  73.     
  74.     /**
  75.      *    Ages the cookies by the specified time.
  76.      *    @param integer $interval    Amount in seconds.
  77.      *    @access public
  78.      */
  79.     function ageCookies($interval) {
  80.         $this->_cookie_jar->agePrematurely($interval);
  81.     }
  82.     
  83.     /**
  84.      *    Sets an additional cookie. If a cookie has
  85.      *    the same name and path it is replaced.
  86.      *    @param string $name            Cookie key.
  87.      *    @param string $value           Value of cookie.
  88.      *    @param string $host            Host upon which the cookie is valid.
  89.      *    @param string $path            Cookie path if not host wide.
  90.      *    @param string $expiry          Expiry date.
  91.      *    @access public
  92.      */
  93.     function setCookie($name, $value, $host = false, $path = '/', $expiry = false) {
  94.         $this->_cookie_jar->setCookie($name, $value, $host, $path, $expiry);
  95.     }
  96.     
  97.     /**
  98.      *    Reads the most specific cookie value from the
  99.      *    browser cookies.
  100.      *    @param string $host        Host to search.
  101.      *    @param string $path        Applicable path.
  102.      *    @param string $name        Name of cookie to read.
  103.      *    @return string             False if not present, else the
  104.      *                                value as a string.
  105.      *    @access public
  106.      */
  107.     function getCookieValue($host, $path, $name) {
  108.         return $this->_cookie_jar->getCookieValue($host, $path, $name);
  109.     }
  110.     
  111.     /**
  112.      *    Reads the current cookies within the base URL.
  113.      *    @param string $name     Key of cookie to find.
  114.      *    @param SimpleUrl $base  Base URL to search from.
  115.      *    @return string/boolean  Null if there is no base URL, false
  116.      *                             if the cookie is not set.
  117.      *    @access public
  118.      */
  119.     function getBaseCookieValue($name, $base) {
  120.         if (! $base) {
  121.             return null;
  122.         }
  123.         return $this->getCookieValue($base->getHost(), $base->getPath(), $name);
  124.     }
  125.     
  126.     /**
  127.      *    Switches off cookie sending and recieving.
  128.      *    @access public
  129.      */
  130.     function ignoreCookies() {
  131.         $this->_cookies_enabled = false;
  132.     }
  133.     
  134.     /**
  135.      *    Switches back on the cookie sending and recieving.
  136.      *    @access public
  137.      */
  138.     function useCookies() {
  139.         $this->_cookies_enabled = true;
  140.     }
  141.     
  142.     /**
  143.      *    Sets the socket timeout for opening a connection.
  144.      *    @param integer $timeout      Maximum time in seconds.
  145.      *    @access public
  146.      */
  147.     function setConnectionTimeout($timeout) {
  148.         $this->_connection_timeout = $timeout;
  149.     }
  150.     
  151.     /**
  152.      *    Sets the maximum number of redirects before
  153.      *    a page will be loaded anyway.
  154.      *    @param integer $max        Most hops allowed.
  155.      *    @access public
  156.      */
  157.     function setMaximumRedirects($max) {
  158.         $this->_max_redirects = $max;
  159.     }
  160.     
  161.     /**
  162.      *    Sets proxy to use on all requests for when
  163.      *    testing from behind a firewall. Set URL
  164.      *    to false to disable.
  165.      *    @param string $proxy        Proxy URL.
  166.      *    @param string $username     Proxy username for authentication.
  167.      *    @param string $password     Proxy password for authentication.
  168.      *    @access public
  169.      */
  170.     function useProxy($proxy, $username, $password) {
  171.         if (! $proxy) {
  172.             $this->_proxy = false;
  173.             return;
  174.         }
  175.         if ((strncmp($proxy, 'http://', 7) != 0) && (strncmp($proxy, 'https://', 8) != 0)) {
  176.             $proxy = 'http://'. $proxy;
  177.         }
  178.         $this->_proxy = &new SimpleUrl($proxy);
  179.         $this->_proxy_username = $username;
  180.         $this->_proxy_password = $password;
  181.     }
  182.     
  183.     /**
  184.      *    Test to see if the redirect limit is passed.
  185.      *    @param integer $redirects        Count so far.
  186.      *    @return boolean                  True if over.
  187.      *    @access private
  188.      */
  189.     function _isTooManyRedirects($redirects) {
  190.         return ($redirects > $this->_max_redirects);
  191.     }
  192.     
  193.     /**
  194.      *    Sets the identity for the current realm.
  195.      *    @param string $host        Host to which realm applies.
  196.      *    @param string $realm       Full name of realm.
  197.      *    @param string $username    Username for realm.
  198.      *    @param string $password    Password for realm.
  199.      *    @access public
  200.      */
  201.     function setIdentity($host, $realm, $username, $password) {
  202.         $this->_authenticator->setIdentityForRealm($host, $realm, $username, $password);
  203.     }
  204.     
  205.     /**
  206.      *    Fetches a URL as a response object. Will keep trying if redirected.
  207.      *    It will also collect authentication realm information.
  208.      *    @param string/SimpleUrl $url      Target to fetch.
  209.      *    @param SimpleEncoding $encoding   Additional parameters for request.
  210.      *    @return SimpleHttpResponse        Hopefully the target page.
  211.      *    @access public
  212.      */
  213.     function &fetchResponse($url, $encoding) {
  214.         if ($encoding->getMethod() != 'POST') {
  215.             $url->addRequestParameters($encoding);
  216.             $encoding->clear();
  217.         }
  218.         $response = &$this->_fetchWhileRedirected($url, $encoding);
  219.         if ($headers = $response->getHeaders()) {
  220.             if ($headers->isChallenge()) {
  221.                 $this->_authenticator->addRealm(
  222.                         $url,
  223.                         $headers->getAuthentication(),
  224.                         $headers->getRealm());
  225.             }
  226.         }
  227.         return $response;
  228.     }
  229.     
  230.     /**
  231.      *    Fetches the page until no longer redirected or
  232.      *    until the redirect limit runs out.
  233.      *    @param SimpleUrl $url                  Target to fetch.
  234.      *    @param SimpelFormEncoding $encoding    Additional parameters for request.
  235.      *    @return SimpleHttpResponse             Hopefully the target page.
  236.      *    @access private
  237.      */
  238.     function &_fetchWhileRedirected($url, $encoding) {
  239.         $redirects = 0;
  240.         do {
  241.             $response = &$this->_fetch($url, $encoding);
  242.             if ($response->isError()) {
  243.                 return $response;
  244.             }
  245.             $headers = $response->getHeaders();
  246.             $location = new SimpleUrl($headers->getLocation());
  247.             $url = $location->makeAbsolute($url);
  248.             if ($this->_cookies_enabled) {
  249.                 $headers->writeCookiesToJar($this->_cookie_jar, $url);
  250.             }
  251.             if (! $headers->isRedirect()) {
  252.                 break;
  253.             }
  254.             $encoding = new SimpleGetEncoding();
  255.         } while (! $this->_isTooManyRedirects(++$redirects));
  256.         return $response;
  257.     }
  258.     
  259.     /**
  260.      *    Actually make the web request.
  261.      *    @param SimpleUrl $url                   Target to fetch.
  262.      *    @param SimpleFormEncoding $encoding     Additional parameters for request.
  263.      *    @return SimpleHttpResponse              Headers and hopefully content.
  264.      *    @access protected
  265.      */
  266.     function &_fetch($url, $encoding) {
  267.         $request = &$this->_createRequest($url, $encoding);
  268.         $response = &$request->fetch($this->_connection_timeout);
  269.         return $response;
  270.     }
  271.     
  272.     /**
  273.      *    Creates a full page request.
  274.      *    @param SimpleUrl $url                 Target to fetch as url object.
  275.      *    @param SimpleFormEncoding $encoding   POST/GET parameters.
  276.      *    @return SimpleHttpRequest             New request.
  277.      *    @access private
  278.      */
  279.     function &_createRequest($url, $encoding) {
  280.         $request = &$this->_createHttpRequest($url, $encoding);
  281.         $this->_addAdditionalHeaders($request);
  282.         if ($this->_cookies_enabled) {
  283.             $request->readCookiesFromJar($this->_cookie_jar, $url);
  284.         }
  285.         $this->_authenticator->addHeaders($request, $url);
  286.         return $request;
  287.     }
  288.     
  289.     /**
  290.      *    Builds the appropriate HTTP request object.
  291.      *    @param SimpleUrl $url                  Target to fetch as url object.
  292.      *    @param SimpleFormEncoding $parameters  POST/GET parameters.
  293.      *    @return SimpleHttpRequest              New request object.
  294.      *    @access protected
  295.      */
  296.     function &_createHttpRequest($url, $encoding) {
  297.         $request = &new SimpleHttpRequest($this->_createRoute($url), $encoding);
  298.         return $request;
  299.     }
  300.     
  301.     /**
  302.      *    Sets up either a direct route or via a proxy.
  303.      *    @param SimpleUrl $url   Target to fetch as url object.
  304.      *    @return SimpleRoute     Route to take to fetch URL.
  305.      *    @access protected
  306.      */
  307.     function &_createRoute($url) {
  308.         if ($this->_proxy) {
  309.             $route = &new SimpleProxyRoute(
  310.                     $url,
  311.                     $this->_proxy,
  312.                     $this->_proxy_username,
  313.                     $this->_proxy_password);
  314.         } else {
  315.             $route = &new SimpleRoute($url);
  316.         }
  317.         return $route;
  318.     }
  319.     
  320.     /**
  321.      *    Adds additional manual headers.
  322.      *    @param SimpleHttpRequest $request    Outgoing request.
  323.      *    @access private
  324.      */
  325.     function _addAdditionalHeaders(&$request) {
  326.         foreach ($this->_additional_headers as $header) {
  327.             $request->addHeaderLine($header);
  328.         }
  329.     }
  330. }
  331. ?>

Documentation generated on Sun, 04 May 2008 09:22:24 -0500 by phpDocumentor 1.3.0