Envoyer une requête HTTP à un service web
Les échanges directs entre des services sur le web sont devenus incontournables. Apprenez comment envoyer une requête HTTP(S) en GET ou en POST à un serveur et à publier une interface machine à machine.
NOTE : La fonction sendhttp et ses variantes de la librairie iZend est une application directe et plus complète de cet article.
Scénario
sendfax
est un service disponible sur le web qui permet d'envoyer un document par fax.
Un site propose ce service via un formulaire.
Un utilisateur remplit le formulaire et l'envoie au site. Le site en extrait les informations et les transmet au service. Le service valide la requête, l'exécute et renvoie un code de retour au site. Le site affiche le résultat de la requête à l'utilisateur.
Fax express
Remplissez le formulaire et appuyez sur le bouton Faxer. Essayez d'envoyer différents formulaires incomplets. NOTE : Dans cette version de démonstration, aucun fax n'est vraiment envoyé.
Le navigateur génère un document HTTP/POST et l'envoie à la fonction faxexpress
du site.
faxexpress
extrait le contenu du document et transmet directement la liste des numéros de téléphone et le fichier en pièce jointe au service sendfax
à l'aide de la fonction sendhttp
.
sendfax
analyse les paramètres de la requête.
En cas d'erreur, si la liste de numéros de téléphone est vide ou invalide ou si le fichier est manquant ou trop gros, le service renvoie un document HTTP contenant le texte KO_MISSINGNUMBER
, KO_BADNUMBER
, KO_MISSINGFILE
ou KO_BADFILE
.
NOTE : Un service réel aura probablement d'autres paramètres tels qu'un identifiant et un mot de passe.
Si tous les paramètres sont corrects, le service envoie le fax et retourne un document HTTP contenant le texte OK
ou KO_FAXNOTSENT
en cas d'erreur.
Le site analyse la réponse du service, le code de retour HTTP et le contenu du document, et renvoie un document au navigateur contenant soit un message de confirmation, soit un ou plusieurs messages d'erreur.
Tout le dialogue entre le site et le service, entre faxpress
et sendfax
, est en HTTP correct.
Un service élaboré peut très bien retourné différents code HTTP, tel que 400 Bad Request
quand une requête est rejetée ou 403 Forbidden
si le demandeur ne peut pas être identifié.
Le format des données échangées entre un client et un service peut aussi être plus complexe et le contenu du dialogue encodé en PHP sérialisé ou en XML.
Réalisation
Organisez le contenu de votre site en créant dans la racine du site les dossiers public pour les pages publiées sur le web, api pour les points d'entrée du service et library pour les fonctions en PHP. Ajoutez les fichiers faxexpress.php, sendfax.php et sendhttp.php respectivement dans les dossiers public, api et library avec les contenus suivants :
- /
- public
- faxexpress.php
- api
- sendfax.php
- library
- sendhttp.php
- public
- <?php
- require_once 'sendhttp.php';
Charge le code de la fonction sendhttp
.
- define('OK', 'OK');
- define('KO_MISSINGNUMBER', 'KO_MISSINGNUMBER');
- define('KO_BADNUMBER', 'KO_BADNUMBER');
- define('KO_MISSINGFILE', 'KO_MISSINGFILE');
- define('KO_BADFILE', 'KO_BADFILE');
- define('KO_FAXNOTSENT', 'KO_FAXNOTSENT');
Définit les codes de retour renvoyés par le service.
- $site_host=$_SERVER['SERVER_NAME'];
- $path='/api/sendfax.php';
- $proto='http';
Initialise l'adresse du serveur et le chemin d'accès du service. Mettez de préférence $proto
à 'https
' si le serveur est sécurisé.
- $to=$files=false;
- $action='init';
- if (isset($_POST['fax_send'])) {
- $action='send';
- }
- switch($action) {
- case 'send':
- if (isset($_POST['fax_to'])) {
- preg_match_all('/([\d]+)/', $_POST['fax_to'], $r);
- $to=implode(' ', $r[0]);
- }
- if (isset($_FILES['fax_document']['tmp_name']) and $_FILES['fax_document']['tmp_name']) {
- $name=$_FILES['fax_document']['name'];
- $tmp_name=$_FILES['fax_document']['tmp_name'];
- $type=$_FILES['fax_document']['type'];
- $files=array('document' => array('name' => $name, 'type' => $type, 'tmp_name' => $tmp_name));
- }
- break;
- default:
- break;
- }
Initialise les paramètres du formulaire, en extrait l'action demandée puis la liste des numéros de téléphone et le fichier en pièce jointe.
- $fax_sent=false;
- $missing_number=false;
- $bad_number=false;
- $missing_file=false;
- $bad_file=false;
- $fax_not_sent=false;
Initialise tous les drapeaux d'information ou d'erreur du formulaire. NOTE : Les champs saisis ne sont volontairement pas validés pour montrer que le service doit dans tous les cas contrôler les données qui lui sont transmises.
- switch($action) {
- case 'send':
- $url=$proto.'://'.$site_host.$path;
- $args = array(
- 'to' => $to,
- );
- $response=sendpost($url, $args, $files, true);
- if (!$response or $response[0] != 200) {
- $fax_not_sent=true;
- break;
- }
Fabrique l'URL et les paramètres de l'appel du service. Envoie la requête avec la fonction sendhttp
.
sendhttp
renvoie un tableau contenant le code de retour HTTP, l'en-tête de la réponse ligne par ligne et le corps de la réponse, ou false
en cas d'erreur.
Si la réponse est false
ou si le code de retour HTTP n'est pas 200, la communication avec le serveur a échoué ou le service a rejeté la requête.
- $r=$response[2];
- $codes=explode(';', $r);
- foreach ($codes as $c) {
- switch($c) {
- case OK:
- $fax_sent=true;
- break;
- case KO_MISSINGNUMBER:
- $missing_number=true;
- break;
- case KO_BADNUMBER:
- $bad_number=true;
- break;
- case KO_MISSINGFILE:
- $missing_file=true;
- break;
- case KO_BADFILE:
- $bad_file=true;
- break;
- case KO_FAXNOTSENT:
- default:
- $fax_not_sent=true;
- break;
- }
- }
- break;
- default:
- break;
- }
- ?>
Extrait le corps de la réponse et analyse les codes de retour renvoyés par le service.
Le reste du code affiche le formulaire de saisie.
- <h6 id="faxexpress">Fax express</h6>
- <form enctype="multipart/form-data" method="post" action="#faxexpress">
- <p>À qui voulez-vous envoyer un fax ?</p>
- <p class="<?php echo ($missing_number or $bad_number) ? 'error' : 'info' ?>">Entrez une série de numéros de téléphone.</p>
- <p><textarea name="fax_to" id="fax_to" cols="50" rows="2"><?php echo $to; ?></textarea></p>
- <p>Quel document voulez-vous faxer ?</p>
- <p class="<?php echo ($missing_file or $bad_file) ? 'error' : 'info' ?>">Sélectionnez un fichier texte ou une image.</p>
- <p><input type="hidden" name="MAX_FILE_SIZE" value="200000" /><input name="fax_document" id="fax_document" type="file" size="25" /></p>
- <p><input name="fax_send" id="fax_send" type="submit" value="Faxer" /></p>
- <?php if ($fax_not_sent): ?>
- <p class="error">L'envoi du fax a échoué (<?php echo implode(' ', $codes); ?>).</p>
- <?php elseif ($fax_sent): ?>
- <p class="info">Votre fax a bien été transmis.</p>
- <?php else: ?>
- <p class="info">Remplissez le formulaire et appuyez sur Faxer.</p>
- <?php endif; ?>
- </form>
- function chkphone($s) {
- return preg_match('/^[0-9]{10,11}$|^\+[0-9]{11}$/', $s);
- }
- function normphone($s) {
- switch(strlen($s)) {
- case 10:
- return '+33'. substr($s,1);
- case 11:
- return '+'. $s;
- default:
- return $s;
- }
- }
checkphone
retourne true
si $s
est un numéro de téléphone à 10 ou 11 chiffres, false
dans le cas contraire.
normphone
ajoute le préfixe +33 à un numéro de téléphone à 10 chiffres ou juste un + devant un numéro de téléphone à 11 chiffres.
NOTE : Adaptez ces fonctions à votre numérotation locale.
- define('OK', 'OK');
- define('KO_MISSINGNUMBER', 'KO_MISSINGNUMBER');
- define('KO_BADNUMBER', 'KO_BADNUMBER');
- define('KO_MISSINGFILE', 'KO_MISSINGFILE');
- define('KO_BADFILE', 'KO_BADFILE');
- define('KO_FAXNOTSENT', 'KO_FAXNOTSENT');
- $errorlist=array();
Définit les codes de retour renvoyés par le service et initialise la liste des erreurs $errorlist
.
- $to=false;
- if (isset($_POST['to'])) {
- $to=$_POST['to'];
- preg_match_all('/(\b[\d+]+\b)/', $to, $tolist);
- $to=$tolist[0];
- }
- if (!$to) {
- $errorlist[]=KO_MISSINGNUMBER;
- }
- else {
- $tellist=array();
- foreach ($to as $tel){
- if (!chkphone($tel)) {
- $errorlist[]=KO_BADNUMBER;
- break;
- }
- $tellist[] = normphone($tel);
- }
- $to=array_unique($tellist);
- }
Extrait les groupes de chiffres consécutifs de $_POST['to']
.
Vérifie que tous les groupes de chiffres sont des numéros de téléphone, les normalise et retire les numéros dupliqués.
Ajoute l'erreur KO_MISSINGNUMBER
à $errorlist
si la liste des numéros de téléphone est vide.
Ajoute l'erreur KO_BADNUMBER
à $errorlist
si un numéro est invalide.
- $data=false;
- $maxsize = 200000;
- if (!isset($_FILES['document']) or !$_FILES['document']['tmp_name'] or $_FILES['document']['error'] != 0) {
- $errorlist[]=KO_MISSINGFILE;
- }
- else if ($_FILES['document']['size'] == 0 or $_FILES['document']['size'] > $maxsize) {
- $errorlist[]=KO_BADFILE;
- }
- if (!$errorlist) {
- $tmpdir = '/tmp';
- $filecopy = $tmpdir . '/' . basename( $_FILES['document']['name']);
- if (move_uploaded_file($_FILES['document']['tmp_name'], $filecopy)) {
- $data64=@file_get_contents($filecopy);
- $data=base64_decode($data64);
- if ($data === false) {
- $errorlist[]=KO_BADFILE;
- }
- /* fax document */
- @unlink($filecopy);
- }
- else {
- $errorlist[]=KO_BADFILE;
- }
- }
Extrait le fichier en pièce jointe de $_FILES
.
Ajoute l'erreur KO_MISSINGFILE
à $errorlist
si le fichier est manquant ou en cas d'erreur de transfert.
Ajoute l'erreur KO_BADFILE
à $errorlist
si la taille du fichier est invalide.
Si aucune erreur n'a été trouvée, copie le fichier transmis dans une zone temporaire et décode son contenu.
Envoie le fax. Ajoute KO_FAXNOTSENT
à $errorlist
en cas d'erreur.
Supprime le fichier temporaire.
NOTE : Dans cette version de démonstration, le fax n'est pas vraiment envoyé.
Initialise la liste des codes de retour à OK
si aucune erreur n'a été rencontré.
- header('Content-Type: text/plain');
- echo implode(';', $errorlist); // just one line with no newline
Renvoie un document du type text/plain
constitué d'une seule ligne de texte contenant un ou plusieurs codes de retour séparés par un ; (POINT-VIRGULE).
- function sendhttp($method, $url, $args, $files=false, $base64=false) {
sendhttp
accepte 5 arguments : un type de requête, une URL, une liste de paramètres et en option une liste de fichiers dont le contenu peut être transmis encodé en base64.
- $purl = parse_url($url);
- if ($purl === false)
- {
- return false;
- }
Décompose l'URL avec la fonction PHP parse_url
. Retourne false
si $url
est invalide.
- $scheme = isset($purl['scheme']) ? $purl['scheme'] : 'http';
- switch($scheme) {
- case 'https':
- $proto = 'ssl';
- break;
- case 'http':
- $proto = 'tcp';
- break;
- default:
- return false;
- }
- $host = isset($purl['host']) ? $purl['host'] : 'localhost';
- $portnum = isset($purl['portnum']) ? $purl['portnum'] : $scheme == 'https' ? 443 : 80;
- $path = isset($purl['path']) ? $purl['path'] : '';
Extrait les différents composants de l'URL et assigne les valeurs par défaut.
- $user_agent = 'iZend';
- $header_string = $content_string = '';
- switch ($method) {
Initialise l'en-tête et le corps du document HTTP. Teste le type de requête.
- case 'POST':
- if ($files && is_array($files)) {
- $boundary = md5(microtime());
- $content_type = 'multipart/form-data; boundary='.$boundary;
- $content_string = '';
- if ($args && is_array($args)) {
- foreach ($args as $k => $v) {
- $content_string .= '--' . $boundary . "\r\n";
- $content_string .= 'Content-Disposition: form-data; name="' . $k . '"' . "\r\n\r\n" . $v . "\r\n";
- }
- }
- foreach ($files as $k => $v ) {
- $data = file_get_contents($v['tmp_name']);
- if ($data === false) {
- break;
- }
- $content_string .= '--' . $boundary . "\r\n";
- $content_string .= 'Content-Disposition: form-data; name="' . $k . '"; filename="' . $v['name'] . '"' . "\r\n";
- $content_string .= 'Content-Type: ' . $v['type'] . "\r\n";
- if ($base64) {
- $content_string .= 'Content-Transfer-Encoding: base64' . "\r\n\r\n";
- $content_string .= chunk_split(base64_encode($data)) . "\r\n";
- }
- else {
- $content_string .= 'Content-Transfer-Encoding: binary' . "\r\n\r\n";
- $content_string .= $data . "\r\n";
- }
- }
- $content_string .= '--' . $boundary . '--'. "\r\n";
- }
- else {
- $content_type = 'application/x-www-form-urlencoded';
- if ($args && is_array($args)) {
- $content_string = http_build_args($args);
- }
- }
- $content_length = strlen($content_string);
- $header_string="POST $path HTTP/1.0\r\nHost: $host\r\nUser-Agent: $user_agent\r\nContent-Type: $content_type\r\nContent-Length: $content_length\r\nConnection: close\r\n\r\n";
- break;
Si la requête est un POST, si le document à un ou plusieurs fichiers joints, écrit un document de type multipart/form-data
, sinon écrit un document de type application/x-www-form-urlencoded
.
Dans le premier cas, fabrique un corps de document avec une première partie qui définit un séparateur unique puis une séries de parties annexes contenant chacune un des fichiers joints dont le contenu est encodé en base64 si $base64
est à true
.
Dans le second cas, fabrique un corps de document HTTP contenant les paramètres éventuels de la requêtes proprement formatés avec http_build_args
.
- case 'GET':
- if ($args && is_array($args)) {
- $path .= '?'.http_build_args($args);
- }
- $header_string="GET $path HTTP/1.0\r\nHost: $host\r\nUser-Agent: $user_agent\r\nConnection: close\r\n\r\n";
- break;
Si la requête est un GET, ajoute les paramètres éventuels proprement formatés avec http_build_args
après le chemin d'accès, puis fabrique l'en-tête du document HTTP. Le corps du document est vide.
- default:
- return false;
- }
Retourne false
si $method
n'est pas 'POST'
ou 'GET'
.
- $socket = @fsockopen($proto.'://'.$host, $portnum);
- if ($socket === false) {
- return false;
- }
Ouvre la connexion avec le serveur. Retourne false
en cas d'erreur.
- if (fwrite($socket, $header_string) === false) {
- return false;
- }
- if ($content_string) {
- $content_len = strlen($content_string);
- for ($written = 0; $written < $content_len; $written += $w) {
- $w = fwrite($socket, $written == 0 ? $content_string : substr($content_string, $written));
- if ($w === false) {
- return false;
- }
- }
- }
Écrit l'en-tête du document puis le corps du document en plusieurs paquets si nécessaire.
- $response = '';
- while (!feof($socket)) {
- $response .= fread($socket, 8192);
- }
Lit la réponse du serveur.
- fclose($socket);
Ferme la connexion avec le serveur.
- list($response_headers, $response_body) = explode("\r\n\r\n", $response, 2);
- $response_header_lines = explode("\r\n", $response_headers);
- $http_response_line = array_shift($response_header_lines);
- if (preg_match('@^HTTP/[0-9]\.[0-9] ([0-9]{3})@', $http_response_line, $r)) {
- $response_code = $r[1];
- }
- else {
- $response_code = 0;
- }
Divise l'en-tête et le corps de la réponse. Sépare l'en-tête ligne par ligne. Extrait la première ligne de l'en-tête pour en retirer le code de retour.
- $response_header_array = array();
- foreach ($response_header_lines as $header_line) {
- list($header, $value) = explode(': ', $header_line, 2);
- $response_header_array[$header] = $value;
- }
Sauve l'en-tête de la réponse dans un tableau associatif.
- return array($response_code, $response_header_array, $response_body);
- }
Retourne un tableau avec le code HTTP renvoyé par le service, l'en-tête MIME du document sous la forme d'un tableau associatif et le contenu brut du corps de la réponse.
- function sendget($url, $args) {
- return sendhttp('GET', $url, $args);
- }
sendget
retourne le résultat de l'appel de sendhttp
avec les arguments $url
et $args
et $method
à 'GET'
.
- function sendpost($url, $args, $files=false, $base64=false ) {
- return sendhttp('POST', $url, $args, $files, $base64);
- }
sendpost
retourne le résultat de l'appel de sendhttp
avec les arguments $url
, $args
, $files
et $base64
et $method
à 'POST'
.
- function http_build_args($args) {
- $args_string = '';
- foreach ($args as $name => $value) {
- $args_string .= ($args_string ? '&' : '') . urlencode($name) . '=' . urlencode($value);
- }
- return $args_string;
- }
http_build_args
retourne le tableau associatif $args
sous la forme d'une chaine de paramètres d'une URL proprement encodée.
sendhttp
SYNOPSIS
sendhttp( $method, $url, $args, $files=false, $base64=false )
sendget( $url, $args )
sendpost( $url, $args, $files=false, $base64=false )
DESCRIPTION
sendhtpp
génère un document HTTP 1.0 en GET ou en POST, le transmet à un serveur HTTP ou HTTPS et retourne le code HTTP, l'en-tête et le corps du document renvoyés par le serveur ou false
en cas d'erreur.
$method
vaut 'GET'
ou 'POST'
selon le type de requête attendu par le serveur.
$url
adresse le code PHP du serveur qui va analyser le document, effectuer un traitement et retourner un document au format HTTP.
$url
a le format [proto://]host[:portnum]/path.
Mettez proto à 'https'
pour transmettre le document en mode sécurisé.
host donne le nom ou l'adresse IP du serveur. Si nécessaire, ajoutez portnum pour spécifier un numéro de port différent de 80 ou 443 pour des connexions en HTTP ou HTTPS avec un serveur à l'écoute sur des ports particuliers.
path donne le chemin d'accès au code en PHP sur le serveur.
$args
contient la liste des paramètres du service appelé sous la forme d'un tableau associatif { 'param1' => val1, ... }
.
$args
permet de passer un ou plusieurs champs directement dans une URL pour une requête HTTP GET ou extraits d'un formulaire HTML pour une requête HTTP POST.
$files
contient la liste des fichiers ajoutés en pièces jointes sous la forme d'un tableau associatif { 'docname' => {'name' => 'filename', 'type' => 'mimetype', 'tmp_name' => 'pathname'}, ... }
. Ce paramètre est optionnel. Typiquement, il permet de passer un fichier transmis par une balise <input type="file" name="docname"... />
d'un formulaire HTML.
Si $base64
est à true
, les contenus des fichiers sont encodés en base64.
sendhttp
renvoie un tableau contenant le code de retour HTTP, l'en-tête MIME de la réponse ventilée ligne par ligne dans un tableau associatif et le corps brut de la réponse. Si un argument est invalide ou si la connexion a échoué, sendhttp
retourne false
.
sendget
et sendpost
appellent sendhttp
avec $method
respectivement à 'GET'
et 'POST'
.
EXEMPLE
$ php -a
Démarre l'interprète PHP en mode interactif.
php> $r = sendget('http://www.google.com/search', array('q' => 'frasq.org'));
Equivaut à taper http:://www.google.com/search?q=frasq.org dans la barre d'adresse d'un navigateur.
php> print_r($r[0]);
200
Affiche le code de retour HTTP.
php> print_r($r[1]);
Array
(
[Date] => ...
[Expires] => -1
[Cache-Control] => private, max-age=0
[Content-Type] => text/html; charset=ISO-8859-1
...
)
Affiche l'en-tête MIME du document.
php> echo $r[1]['Content-Type'];
text/html; charset=ISO-8859-1
Affiche le type de contenu du document.
php> print_r($r[2]);
<!doctype html><head><title>frasq.org - Google Search</title> ...
Affiche le document.
Application
Google publie une API pour dessiner des graphiques et d'autres types d'images - Google Charts API.
Une fonction permet d'obtenir une image PNG d'un code QR. Passez simplement les paramètres requis dans une <img>
:
<img src="http://chart.googleapis.com/chart?cht=qr&chf=&bg,s,ffffff&chs=63x63&chld=M|0&chl=www.frasq.org" />
Pour appeler ce service dans un programme, encapsulez sendhttp
dans une fonction spécifique :
- require_once 'sendhttp.php';
Charge la fonction sendhttp
.
- function qrencode($s, $size=100, $quality='M') {
- $url = 'http://chart.googleapis.com/chart';
- $args = array(
- 'cht' => 'qr',
- 'chf' => 'bg,s,ffffff',
- 'chs' => "${size}x${size}",
- 'chld' => "${quality}|0",
- 'chl' => $s,
- );
- $response=sendget($url, $args);
- if (!$response or $response[0] != 200) {
- return false;
- }
- return $response[2];
- }
qrencode
envoie une requête GET au service à l'adresse http://chart.googleapis.com/chart et retourne les données en binaire d'une image ou false
en cas d'erreur.
$s
contient la chaîne de caractères à encoder.
$size
est en pixels.
$quality
peut valoir L
, M
, Q
ou H
.
Voir la documentation pour plus de détails.
Décoder l'image d'un code QR est plus délicat. Supposez que vous n'ayez pas trouvé une véritable API HTTP mais juste un formulaire qui vous laisse télécharger une image et retourne le texte décodé : ZXing Decoder Online. Essayez-le. Ce formulaire retourne le texte décodé ou un autre document HTML en cas d'erreur.
Extrayez le code source du formulaire :
<form enctype="multipart/form-data" method="post" action="decode">
<p><input name="f" size="50" type="file"/> <input type="submit"/>
<input value="true" name="full" type="hidden"/></p></form>
Écrivez une fonction qui passe ces paramètres dans une requête HTTP du type POST :
- function qrdecode($file, $filetype='image/png') {
- $url = 'http://zxing.org/w/decode';
- $args = array(
- 'full' => 'true',
- );
- $files=array('f' => array('name' => basename($file), 'tmp_name' => $file, 'type' => $filetype));
- $response=sendpost($url, $args, $files, false); // DON'T encode data in base64
- if (!$response or $response[0] != 200) {
- return false;
- }
- if (preg_match('#<html>.*</html>#', $response[2])) {
- return false;
- }
- return strip_tags($response[2]);
- }
qrdecode
envoie une requête POST à l'adresse http://zxing.org/w/decode avec un fichier en pièce jointe.
Si le service retourne un autre document HTML, qrdecode
retourne false
.
IMPORTANT : Soyez très prudent lorsque vous insérez des données retournées par un autre programme. Si possible, retirez toutes les balises avec strip_tags
et ajoutez votre propre formatage.
Lisez le manuel Écrire un CMS en PHP pour apprendre comment structurer le développement d'un site web.
Commentaires