# HTTP Client class

Net_HTTP_Client est un composant Client HTTP qui implemente toutes les méthodes
HTTP et la plupart des méthodes de WebDAV le standard de publication Web.
Télécharger httpclient.zip cette archive au format ZIP contient la classe et la documentation

### Informations

Version : 0.7
Licence : GPL
Lastmod : Sep 2002
Author : Leo West

### Documentation

- Synopsis
  - Exemple simple
  - Utilisation d'une connexion persistente HTTP/1.1
- Méthodes principales
  - Net_HTTP_Client( [host, port] )
  - Connect( host, port )
  - Disconnect()
  - setHeaders( headers )
  - removeHeader( headerName )
  - setCredentials( username, password )
  - setProtocolVersion( version )
  - setProxy( proxyHost, proxyPort )
  - addHeader( headerName, headerValue )
  - addCookie( cookieName, cookieValue )
  - removeCookies()
  - Get( uri )
  - getHeaders()
  - getBody()
  - Head( uri )
  - Options( uri )
  - Post( uri, query_params )
- Méthodes WebDAV
  - Copy( srcUri, destUri, overwrite )
  - Delete( uri )
  - Move( srcUri, destUri, overwrite )
  - MkCol( uri )
  - PropFind( uri, scope )
  - Put( uri, filecontent )
  - Lock( uri, lockScope, lockType, lockOwner )
  - Unlock( uri, lockToken )
- Diagnostics and debug
  - getStatus()
  - getStatusMessage()
  - setDebug( flags )
  - Other methods
- Changelog
- References

### Synopsis

#### Exemple simple

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();

#### Utilisation d'une connexion persistente HTTP/1.1

$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();

### Méthodes principales

#### Net_HTTP_Client( [host, port] )

Constructeur
Les parametres host and port sont optionnels. Lorqu'ils sont définis, la connexion est initiée immédiatement.
voir : Connect

#### Connect( host, port )

Ouvre la connexion au serveur
host l'addresse du serveur
port le port du serveur, par defaut 80
Renvoie true si succes, false si la connexion a échouée. Utilisez getStatusMessage pour examiner le message d'erreur.

#### Disconnect()

Ferme la connexion.

#### setHeaders( headers )

Défini les entêtes HTTP à envoyer au serveur lors des requêtes suivnates.
headers un tableau associatif contenant les entêtes sous la forme "headerName" => "headerValue"
Attention : Les nom d'entête (headerName) sont case-sensitive pour l'instant dans ce composant.

#### removeHeader( headerName )

retire l'entête HTTP headerName
headerName le nom de l'entête

#### setCredentials( username, password )

Défini l'identifiant et le mot de passe pour les prochaines requêtes. A utiliser pour accéder a des ressource protégées sur le serveur.
Seul le schéma d'autehtnication "Basic" est supporté actuellement
username l'identifiant
password Le mot de passe en clair

#### setProtocolVersion( version )

Defini la version du protocole HTTP à utiliser.
version une chaine représentant la version, au choix: "0.9", "1.0", "1.1"
renvoie false si la version est incorrecte

#### setProxy( proxyHost, proxyPort )

Indique au composant d'utiliser un Proxy. Testé seulement sur les proxies HTTP (Squid etc.)
proxyHost l'adresse du proxy, proxyPort le port du proxy, par ex. 80 ou 8080

#### addHeader( headerName, headerValue )

Ajoute une entête HTTP à envoyer lors des prochaines requêtes. headerName est "case sensitive"
headerName Nom de l'entête
headerValue Valeur de l'entête

#### addCookie( cookieName, cookieValue )

défini un cookie, utilisé lors des requêtes suivantes
Le cookie est de type "session". Normalement les cookies sont définis par le serveur, mais ce hack permet par exemple de définir une session. cookieName Nom du cookie
cookieValue Valeur du cookie
[depuis v0.7]

#### removeCookies( )

supprime tous les cookies défini jusqu'alors.
[depuis v0.7]

#### Get( uri )

Envoie une requête GET
$uri L'URI, cad. le chemin du document relatif a la racine du serveur, exemple /index.html.
Renvoie le code de statut reçue du serveur (200 si succès)
Voir aussi getHeaders, getBody
Get() accepte également une URL complète, dans ce cas il ouvre une connexion sur le serveur.

// avec une URI
$http->connect( "fr.yahoo.com" );
$status = $http->Get( "/" );
// meme chose avec une URL
$status = $http->Get( "http://fr.yahoo.com/" );

#### getHeaders()

Renvoie les entêtes HTTP de la réponse. Les entêtes sont renvoyés sous la forme
d'un tableau associatif (nom => valeur ).
A utiliser après une requête, par ex. pour examiner les entêtes du genre: Set-Cookie, Location ...

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

#### getBody()

Renvoie le corps de la réponse sous forme de chaine.

#### Head( uri )

Envoie une requête HEAD
uri est l'URI du document
Renvoie le code de statut reçue du serveur (200 si succès)
Pour examiner le contenu des headers, voir getResponseHeaders()

#### Options( uri )

Envoie une requête OPTIONS
uri est l'URI du document, en général "/"
Renvoie les options supportées par le serveur dans un tableau
[depuis v0.7]

#### Post( uri, query_params )

Envoie une requête POST
uri l'URI de la ressource
query_params un tableau associatif contenant les paramètres de la requête (par ex. du formulaire)
Renvoie le code de statut reçue du serveur (200 si succès)

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

### Méthodes WebDAV

#### Copy( srcUri, destUri, overwrite )

Copie une ressource existante à un nouvel emplacement en utilisant la requête COPY
srcUri l'emplacement actuel de la ressource sur le serveur. N'oubliez pas le / de tête.
destUri l'emplacement de destination. n'indiquez *pas* une URL complète!
overwrite true si la destination peut etre écrasée (défaut), false sinon
Renvoie le code de statut reçue du serveur (204 si succès)
$status = $http->Copy( "/sources/client.php", "/backup/client-0.4.php", true );

#### Delete( uri )

Supprime une ressource sur le serveur en utilisant la requête DELETE
uri URI de l'emplacement de la ressource sur le serveur.
Renvoie le code de statut reçue du serveur (204 si succès)
Note: Cette méthode HTTP n'est pas toujours implémentée sur les serveurs.

#### Move( srcUri, destUri, overwrite )

Déplace (renomme) une ressource sur le serveur en utilisant la requête MOVE
srcUri l'emplacement actuel de la ressource sur le serveur. N'oubliez pas le / de tête.
destUri l'emplacement de destination. n'indiquez *pas* une URL complète!
overwrite true si la destination peut etre écrasée (défaut), false sinon
Renvoie le code de statut reçue du serveur (204 si succès)

#### MkCol( uri )

Crée une collection sur le serveur (généralement un repertoire) via une requête MKCOL
uri URI relative de la collection
Renvoie le code de statut, 201 (Created) si succès.

#### PropFind( uri, scope )

Récupère un ensemble de meta-informations à propos d'une ressource sur le serveur
La réponse au format XML n'est pas interprétée, vous aurez à le faire dans votre code.
uri URI de la ressource
scope Défini le scope de la requête. 0 pour obtenir des infos sur le noeud seulement, 1 pour le noued et ses enfants directs, "Infinity" pour l'arborescence complète sous le noeud
Renvoie le code de status, 207 (Multi-Status) si OK

#### Put( uri, filecontent )

Envoie un fichier sur le serveur via la requête PUT
uri l'emplacement de destiination du fichier sur le serveur. N'oubliez pas le / de tête
filecontent is the content of the file. binary content accepted
Returns the status code as a string, 201 (Created) if OK.

#### Lock( uri, lockScope, lockType, lockOwner )

WARNING: experimental
Lock a ressource on the server and return 200 if locking went OK.
The XML reply is not parsed for now [translate: Your help is welcome].
uri URL of the resource to lock
lockScope scope of the lock. Use "exclusive" for an private lock, "inclusive" for a shared lock.
lockType Access type for the lock : Use "write", ?
lockOwner An URL representing the owner of this lock

$reply = $http->Lock( "/docs/manual.html", "inclusive", "write", "leo@leo.com" );
if( $reply != 200 ) {
$msg = $http->getStatusMessage();
die( "Unlock problem, server says $msg" );
} else {
$xmlResponse = $http->getBody();
// TODO : parse the XML response here
}

#### Unlock( uri, lockToken )

WARNING: experimental
Release a lock on a remote file and return the response code (204 if unlock OK)
uri The relative URL of the resource to unlock
lockToken The lock token given at lock time, eg: opaquelocktoken:e71d4fae-5dec-22d6-fea5-00a0c91e6be4

$token = "opaquelocktoken:e71d4fae-5dec-22d6-fea5-00a0c91e6be4";
$reply = $http->Unlock( "/docs/manual.html", $token );
if( $reply != 204 ) {
$msg = $http->getStatusMessage();
die( "Unlock problem, server says $msg" );
}

### Diagnostics and debug

#### 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

#### 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

#### Other methods

sendCommand, makeURI, processReply, processHeader, processBody, readReply, flushReply
These methods are private therefore not documented and USUALLY NOT FOR DIRECT USE.

### Changelog

    	0.1 initial version
    	0.2 documentation completed
    	    + getHeaders(), getBody()
    		 o Post(), Connect()
    	0.3 DAV enhancements:
    		 + Put() method
    	0.4 continued DAV support
    		 + Delete(), Move(), MkCol(), Propfind()  methods
    		 o added url property, remove host and port properties
    		 o Connect, Net_HTTP_Client (use of this.url)
    		 o processBody() : use non-blocking to fix a socket pblm
    	0.5 debug support
    		 + setDebug()
    		 + debug levels definitions (DBG*)
    	0.6 + Lock() method
    		 + setCredentials() method and fix - thanks Thomas Olsen
    		 + support for Get( full_url )
    		 o fix POST call (duplicate content-length) - thanks to Javier Sixto
    	0.7 + OPTIONS method support
    	    + addCookie and removeCookies methods
    	    o fix the "0" problem
    	    o fix undefined variable warning

### 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