HTTP Client class


Summary

Examples of use

Section to be completed

A minimal example

include "Net/HTTP/Client.php";

$http = new Net_HTTP_Client();
$http->Connect( "somehost", 80 ) or die( "Connect problem" );
$status = $http->Get( "/index.html" );
if( $status != 200 )
die( "Problem : " . $http->getStatusMessage() );
else
echo $http->getBody();
$http->Disconnect();


Using HTTP/1.1 persistent connexions

$http = new Net_HTTP_Client( "dir.yahoo.com", 80 );
$http->setProtocolVersion( "1.1" );
$http->addHeader( "Host", "dir.yahoo.com" );
$http->addHeader( "Connection", "keep-alive" );

if( $http->Get( "/Reference/Libraries/" ) == 200 )
$page1 = $http->getBody();

if( $http->Get( "/News_and_Media/" ) == 200 )
$page2 = $http->getBody();
$http->disconnect();


Methods

Net_HTTP_Client

Class constructor
parameters host and port are optional, but when defined, the connection is immediate.
seeAlso : Connect method

setDebug( flags )

Turn on debug messages
$client->setDebug( DBGTRACE | DBGINDATA );

Flags is a bit mask of following debug modes:
DBGTRACE to trace methods calls stack
DBGINDATA to debug data received from server
DBGOUTDATA to debug data sent
DBGLOW to debug low-level (usually internal) methods
DBGSOCK to debug socket-level stuff

Connect( host, port )

open the connection to the server
host is the server address (or IP)
port is the optional server listening port, defaults to 80
return true if successfull, false is connection failed. Use getStatusMessage to examine the error problem

Disconnect()

close the connection to the server

setProxy( proxyHost, proxyPort )

Instruct the class to use a connect through a proxy. Tested only against HTTP proxies (Squid etc.)

proxyHost is the proxy address, proxyPort the proxy port, usually 80 or 8080

setProtocolVersion( version )

Define the HTTP protocol version to use
version is a string representing the version number, with one digit: "0.9", "1.0", "1.1"
return false if the version number is bad, true if OK

Note that for some obscure reasons, persistent connexions sometimes fail with some versions of PHP (4.0.6 notably)
Socket gurus, you may track down the problem in the processBody() code.

setHeaders( headers )

Define all HTTP headers to be sent during next requests.
headers is an array containing the headers in the form "headerName" => "headerValue"
header names are case sensitive in this class.

addHeader( headerName, headerValue )

Define a request header to be sent during next requests. headerName is case sensitive
headerName HTTP header name
headerValue HTTP header value

removeHeader( headerName )

unset a request header
headerName is the header name. Be aware i choose to use case sensitive headers.

Head( uri )

issue a HEAD request
$uri is a string containing the URI of the document ( the part of the URL after the host and port /)
Returns the status code received from server (200 if ok)
To examine the headers content, see getResponseHeaders method

Get( uri )

issue a GET http request
$uri is the URI of the document
Returns the status code received from server (200 if ok)
see Also getHeaders & getBody methods

Post( uri, query_params )

issue a POST http request
uri is the URI of the document
query_params is an hash array containg the form parameters to send
Returns the status code received from server (200 if ok)

Example

$params = array( "login" => "scott", "password" => "tiger" );
$status = $http->post( "/login.php", $params );


Put( uri, filecontent )

Send a PUT request
PUT is the method to sending a file on the server. it is *not* widely supported
uri the location of the file on the server. dont forget the heading "/"
filecontent is the content of the file. binary content accepted
Returns the status code as a string, 201 (Created) if OK.

Move( srcUri, destUri, overwrite )

Move or rename a resource on the server, using the MOVE request.
srcUri is the current file location on the server. dont forget the heading slash /
destUri the destination location on the server. this is *not* a full URL
overwrite is a boolean set to true to overwrite an existing destination.
Return the response status code as a string, 204 (Unchanged) if OK.

Copy( srcUri, destUri, overwrite )

Copy an existing file on the server into a new place, using the COPY HTTP-DAV request

srcUri is the current file location on the server. dont forget the heading "/"
destUri is the destination location on the server. this is *not* a full URL
overwrite indicates whether to overwrite (true) or leave (false) an existing destination. overwrite by default
Returns the status code 204 (Unchanged) if OK.

$status = $http->Copy( "/sources/client.php", "/backup/client-0.4.php", true );

MkCol( uri )

Send a MKCOL HTTP-DAV request
Create a collection (usually a directory) on the server.
uri is the collection's location on the server.
Return the status code, 201 (Created) if OK

Delete( uri )

Delete a file on the server using the "DELETE" HTTP-DAV request
uri the location of the file on the server.
Returns the status code (204 if OK)

Note: This HTTP method is *not* widely supported, and only partially supports "collection"
deletion, as the XML response is not parsed.

PropFind( uri, scope )

Retrieves meta informations about a resource on the server, using the WebDav PROPFIND method
The XML reply body is not parsed, therfore you will have to do it :)

uri the location of the file on the server
scope set the scope of the request, (somehow similar to the LDAP scope notion):
To retrieve infos about the node only (0), for the node and its direct children (1), or "Infinity" infos for the node and all its descendant nodes.

Returns the response status code, 207 (Multi-Status) if OK

getHeaders()

return the response headers. Headers are returned as an (headername => value) array.
To be called after a request, to examine the headers returned by server: Set-Cookie, Location or whatever.

$status = $http->Get( "/" );
...
// document is somewhere else
if( $status == 301 || $status == 302 || $status == 307 )
{
$headers = $http->getHeaders();
$status = $http->Get( $headers["Location"] );
}


getBody()

return a string containing the response body, to be used after a Get or Post call for instance.

getStatus()

Return the server status code for the last request.
HTTP codes are divided in classes (where x is a digit)

- 20x : request processed OK
- 30x : document moved
- 40x : client error ( bad url, document not found, etc...)
- 50x : server error

getStatusMessage()

Returns the full response status of the last request, in the form "CODE Message"
Example : 404 Document not found

Other methods

sendCommand, makeURI, processReply, processHeader, processBody, readReply, flushReply
These methods are for class own use, therefore not documented

Informations

Version : 0.5

Licence : GPL

TODO : OPTIONS method, remaining WebDAV methods: PROPPATCH LOCK UNLOCK

Changes

0.1 initial version
0.2 documentation completed: getHeaders(), getBody(), Post(), Connect()
0.3 DAV enhancements: Put() method
0.4 continued DAV support: + Delete(), Move(), MkCol(), Propfind() methods
added url property, remove host and port properties abd cnaged Connect, Net_HTTP_Client (use of this.url)
0.5 debug support setDebug()
processBody() : use non-blocking to fix a socket problem

References

RFC2616 "Hypertext Transfer Protocol -- HTTP/1.1"
http://lwest.free.fr/doc/protocols/http/rfc2616.html

RFC2518 "HTTP Extensions for Distributed Authoring WEBDAV"
http://lwest.free.fr/doc/protocols/http/rfc2518.html

WebDAV Community Site
http://www.webdav.org


Documentation generated by RfcEngine