User Agent class
This class is based on UserAgent.pm <http://search.cpan.org/author/GAAS/libwww-perl-5.65/lib/LWP/UserAgent.pm> from the libwww-perl collection <http://www.linpro.no/lwp/>. A lot of the documentation here has been copied from the perl files.
The User_Agent is a class implementing a HTTP user agent in PHP. It brings together the HTTP_Request, HTTP_Response and the Protocol classes that form the rest of the core of HTTP Navigator library. For simple uses this class can be used directly to dispatch WWW requests, alternatively it can be subclassed for application-specific behaviour.
In normal use the application creates a User_Agent object, and then configures it with values for timeouts, proxies, name, etc. It then creates an instance of HTTP_Request for the request that needs to be performed. This request is then passed to one of the User_Agent's request() methods, which dispatches it using the relevant protocol, and returns a HTTP_Response object.
There are convenience methods for sending the most common request types; get(), head() and post().
Example:
or:
1 $ua =& new User_Agent(array('timeout' => 30, 'cookie_jar' => true));
2 $response =& $ua->get('http://www.k1m.com/');
1 $request =& new HTTP_Request('GET', new URL('http://www.k1m.com/'));
2 // then one of these:
3 $response =& $ua->request($request); // or
4 $response =& $ua->request($request, new File('/tmp/sss')); // or
5 $response =& $ua->request($request, new Callback('function'));
TODO:
Located in Program_Root/User_Agent.php (line 75)
Agent - sent as a 'User-Agent' header
Auth - basic auth details
Connection cache
Cookie jar
From - email address
Gzip support
HTTP version
Keep alive (total number of connections to keep alive)
Lax redirect
Max content size
Exclude from proxy - requests to these domains will not go through a proxy
Parse HTML head
Protocols allowed
Protocols forbidden
Proxy details
Requests Redirectable
Timeout (in seconds)
Read / write timeout (seconds)
Constructor.
Key/value pair arguments may be provided to set up the initial state of the user agent. The following options correspond to attribute methods described below:
KEY DEFAULT
----------- --------------------
agent "HTTP-Navigator/#.##"
from null
timeout 180
max_size null
http_version '1.1'
cookie_jar null
lax_redirect false
parse_head false
connection_cache null
protocols_allowed null
protocols_forbidden null
gzip_support false
scheme_implementor null
requests_redirectable ('GET', 'HEAD')
string or array
string or array
GET
URL object, or string
HTTP_Headers object
Get cookie jar
Example:
1 $cookie_jar =& $ua->get_cookie_jar();
Get proxy
Example:
1 $proxy = $ua->get_proxy('HTTP');
get_proxy() returns a URL object holding proxy details.
HEAD
URL object, or string
HTTP_Headers object
Is redirect ok.
This method is called by request() before it tries to follow a redirection to the request. This should return a true value if redirection is permissible.
The default implementation will return true unless:
(passed by reference)
Parse HTML head
Extracts some headers from the HTML <head> element and adds them to the response headers.
POST
URL object, or string
associative array
HTTP_Headers object
Prepare request
This method modifies given HTTP_Request object by setting up various headers based on the attributes of the $ua. The headers affected are: User-Agent, From, Range and Cookie.
passed by reference
PUT
URL object, or string
HTTP_Headers object
Request
Process a request, including redirects and security. This method may actually send several different simple requests.
The arguments are the same as for send_request() and simple_request().
Send request.
This method dispatches a single WWW request on behalf of a user, and returns the response received. The request is sent off unmodified, without passing it through prepare_request().
The $request should be a reference to a HTTP_Request object with values defined for at least the method and url attributes.
If $arg is a File object it is taken as a file where the content of the response is stored.
If $arg is a Callback object, or derived from the Callback class, chunks of the content will be passed to the call() method as they are received.
If $arg is omitted, then the content is stored in the response object itself.
(passed by reference)
Set connection_cache
(passed by reference)
Set cookie jar
Get/set the cookie jar object to use. The only requirement is that the cookie jar object must implement the extract_cookies($request) and add_cookie_header($response) methods. These methods will then be invoked by the user agent as requests are sent and responses are received. Normally this will be a Cookie_Jar object or some subclass.
The default is to have no cookie_jar, i.e. never automatically add "Cookie" headers to the requests.
If you pass a string holding the filename of the cookies file, an instance of the Cookie_Jar class will be created holding the cookies found in the file. See examples below for different ways of enabling the cookie jar.
Examples:
1 // setting the cookie jar by file
2 $ua->set_cookie_jar(new File('/path/to/cookies.txt'));
3 // setting the cookie jar by passing a Cookie_Jar object by reference
4 $cookie_jar =& new Cookie_Jar(array('file_persistent' => '/path/to/cookies.txt'));
5 $ua->set_cookie_jar(array(&$cookie_jar));
6 // disabling cookie jar
7 $ua->set_cookie_jar(false);
8 // enabling cookie jar (will create a new empty cookie jar)
9 $ua->set_cookie_jar(true);
(passed by reference)
Set credentials.
It is probably better to extend User_Agent and specialise get_basic_credentials() to look up the auth info however you like.
Example:
or
1 $ua->set_credentials('www.domain.com:80', 'MySpace', 'user', 'password');
1 $url =& new URL('http://www.domain.com');
2 $ua->set_credentials($url, 'MySpace', 'user', 'password');
URL object, or string
Set Gzip support
Returns true if $enable is true and gzinflate() function exists. False otherwise
Example:
1 $ua->set_gzip_support(true);
Set lax redirect
If enabled, a 302 response will be treated as a 303 response. This is useful if you want a followup request to a 302 response to be handled as a GET request regardless of the original request method.
Note: I'm not sure if this is a good way to handle it, so the effect of lax redirect might change in future.
Set maximum content size.
Pass an integer, or null if you don't want a limit. Get/set the size limit for response content. The default is null, which means that there is no limit. If the returned response content is only partial, because the size limit was exceeded, then a "Client-Aborted" header will be added to the response.
Set protocols_allowed.
Set protocols_forbidden.
Set proxy
Examples:
1 $ua->set_proxy(array('http', 'ftp'), 'http://proxy.sn.no:8001/');
2 $ua->set_proxy('gopher', 'http://proxy.sn.no:8001/');
The first form specifies that the URL is to be used for proxying of access methods listed in the list in the first method argument, i.e. 'http' and 'ftp'.
The second form shows a shorthand form for specifying proxy URL for a single access scheme.
single scheme can be specified as a string, multiple schemes in an array.
URL object or URL string.
Set requests_redirectable.
Set scheme implementor - calls Protocol::implementor()
Example:
1 $ua->set_scheme_implementor(array('HTTPS'=>'Protocol_CURL'));
associative array with scheme as key and Protocol_* class as value.
Simple request
This method dispatches a single WWW request on behalf of a user, and returns the response received. If differs from send_request() by automatically calling the prepare_request() method before the request is sent.
The arguments are the same as for send_request().
passed by reference
see send_request()
Uncompress content
Note: only handles gzip encoding at the moment. This method will, if successful in uncompressing, replace the body of the response to hold the uncompressed content and remove the relevant encoding value from the 'content-encoding' header.
HTTP_Response
Documention generated on Wed, 16 Jul 2003 01:04:08 +0100 by phpDocumentor 1.2.0