source: trunk/server/www/vendors/simpletest/user_agent.php @ 6

Last change on this file since 6 was 6, checked in by sander, 11 years ago

Added SimpleTest? test framework

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