Les derniers articles

API Google, SOAP et PHP 5

2004-03-28

Introduction
La license Google
Description de l'API Google
- Format de la recherche
- Format de la réponse
Les variables membres
Les méthodes
Source complète de la classe
Utilisation
Conclusion
Liens

Introduction

Dans cet article nous allons voir comment construire une classe permettant d'insérer les résultats du moteur de recherche Google sur son site.
Pour ce faire, nous allons utiliser l'API que Google fournit. Cette API est basée sur les protocoles SOAP et WSDL (tout deux basés sur XML).
Vous devrez disposer d'une version de PHP >= PHP 5.0.0 RC1, afin de bénéficier de l'extension SOAP.
L'article montrera également un exemple de gestion des exceptions (arrivées en PHP 5).

La license Google

Pour utiliser l'API de Google, vous devez disposer d'un numéro de license. Cette license est gratuite. Vous devez néanmoins respecter quelques regles comme notamment ne pas l'utiliser dans un but commercial. Je vous invite à lire les termes de la license pour de plus amples détails. ( Obtenir un numéro de license )

Description de l'API Google

Format de la recherche

Voici la description des paramètres à envoyer pour effectuer une recherche.
Il faut penser à bien respecter la casse de ces paramêtres, ainsi que leur type.

Recherche
Paramètre	Type	Description
key	String	Votre numéro de license Google
q	String	Votre recherche. Vous pouvez utiliser toutes les options qu'offre votre Google préféré , comme le regroupage, la recherche sur un site spécifique, la recherche booléene, etc etc. ( Plus d'informations ). Votre recherche doit impérativement être encodée au format UTF-8.
Start	Integer	Index du début de votre recherche. Ce paramètre vous permet, notamment, de réaliser un affichage par page des résultats.
maxResults	Integer	Nombre de résultats renvoyés par la requète. Google limite ce nombre à 10.
filter	Boolean	Ce paramètre permet de filtrer les résultats renvoyés en supprimant les contenus très similaires et/ou venant du même site. Google préconise de laisser ce paramètre à false.
restricts	String	Ce paramètre permet de restreindre la recherche selon certains critères précis. Vous pourrez notemment restreindre la recherche aux pages venant d'un certain pays, par exemple countryFR pour la France, ou encore à certains topics. Google propose 4 topics : Gouvernement Américain (unclesam), Linux (linux), Macintosh (mac) et FreeBSD (bsd). Il est possible de combiner les deux modes de restriction grâce à des opérateurs booléens : NOT (-), OR (\|), AND (.) et de faire des regroupements : parenthèses (). ( Plus d'informations ).
safeSearch	Boolean	Ce paramètre permet de filtrer les contenus pour adultes.
lr	String	Ce paramètre permet de restreindre la recherche à certains pays. A mon sens, il est redondant avec le paramètre restricts.
ie	String	Ce paramètre n'est plus pris en compte par le serveur.
oe	String	Ce paramètre n'est plus pris en compte par le serveur.

Plus d'informations sur le format de recherche

Format de la réponse

Réponse
Paramètre	Description
documentFiltering	Booléen indiquant si les résultats de la recherche ont été filtrés.
searchComments	Commentaire renvoyé par Google, pouvant contenir notamment les mots clés non pris en compte.
estimatedTotalResultsCount	Estimation du nombre de résultats renvoyés par la requète.
estimateIsExact	Booléen indiquant si l'estimation précedente est juste.
resultElements	Tableau contenant les résultats de la recherche. C'est donc se qui nous intéresse tout particuliérement.
searchQuery	La requète que Google a reçu (Paramètre q de la recherche).
startIndex	Index (-1) du premier résultat. Ce paramètre sert à réaliser un affichage par page des résultats.
endIndex	Index (-1) du dernier résultats.
searchTips	Aide renvoyée par Google contenat notamment des conseils pour la recherche.
directoryCategories	Liens vers les catégories de Google.
searchTime	Nombre à virgule flottante ( Float ) indiquant le temps que Google a mis pour effectuer la recherche.
resultsElements [ summary ]	Résumé de la page.
resultsElements [ URL ]	L'URL du lien renvoyé.
resultsElements [ snippet ]	Un extrait siginificatif de la page contenant les mots clés en gras.
resultsElements [ title ]	Titre du résultat renvoyé
resultsElements [ cachedSize ]	Poids de la page dans le cache de Google + "k".
resultsElements [ relatedInformationPresent ]	Booléen indiquant si le terme "related" (permettant d'obtenir des pages similaires) est supporté par cette URL.

Plus d'informations sur le format de la réponse

Les variables membres

La classe utilisera une unique variable membre contenant l'URL vers le fichier WSDL qui décrit l'API de Google.
Elle sera declarée comme "public". Fichier WSDL de l'API Google
code :

<?php
class GoogleApi {
// URL vers le fichier WSDL de l'API Google
public $WsdlUri = 'http://api.google.com/GoogleSearch.wsdl';

}
?>

Les methodes

Description des méthodes

Grâce à la nouvelle extension SOAP la classe sera très succinte, et comportera uniquement trois méthodes membres : le constructeur, la fonction de recherche et une méthode pour afficher des erreurs éventuelles.

Méthodes
Nom	Description
GoogleApi::__construct()	Constructeur de la classe. On utilisera le constructeur unifié de PHP5. Cette méthode vérifiera que l'extension SOAP est bien chargée. Si ce n'est pas le cas, elle tentera de la charger à la volée. En cas d'impossibilité, l'exécution du script se terminera.
GoogleApi::Search()	La méthode qui enverra la requête à l'APi de Google. On lui passera en paramètre toutes les options de recherche. Cette méthode nécessitera le numéro de license Google, on definiera donc une constante à cet effet.
GoogleApi::DisplayError()	Affichage des erreurs renvoyées par le serveur SOAP. Cette méthode prend un objet SoapFault comme unique paramètre.

Schéma :

Le constructeur de la classe

On va donc vérifier que l'extension SOAP est bien chargée, et le cas échéant, tenter de la charger à la volée.
Le constructeur sera declaré en "public", ce qui permettra de pouvoir instancier un objet GoogleApi.
Le code

La méthode de recherche

On passera toutes les possibilités de recherche en tant que paramètres de la méthode.
seul, le premier paramètre search est obligatoire, les autres sont optionnels.

Le code :

Gestion des erreurs ( Source complète de la classe )

Il se peut que pour une raison x ou y une erreur se produise lorsque on communique avec un serveur SOAP.
L'extension SOAP de PHP fournit une classe ( SoapFault ) qui permet de gérer ces erreurs.
On va donc réecrire la méthode Search() en gérant des exceptions grâce à la classe SoapFault.
On céera également une méthode GoogleApi::DisplayError() afin d'afficher le résultat de l'exception.

Le code :

<?php
define('LICENSE_KEY', 'votre numéro de licence');

class GoogleApi {
    // URL vers le fichier WSDL de l'API Google
    public $WsdlUri = 'http://api.google.com/GoogleSearch.wsdl';

    public function __construct() {

        // On vérifie que l'extension est bien chargée
        if(!extension_loaded('soap')) {
            // Elle n'est pas chargée. On tente de la charger à la volée.
            if(!@dl('soap')) {
                // c`est impossible, on met fin à l'exécution du script.
                die('Impossible d\'utiliser l\'extension SOAP');
            }
        }
        // L'extension est bien chargée.
        return true;
    }

    public function Search($search , $start=0, $maxresults=5, $filter=false, $restrict='', $safesearch=false , $lang='') {

        // Création du tableau contenant les paramètres à envoyer à Google.
        $params = array(
        'key' => LICENSE_KEY,
        'q' => utf8_encode($search),
        'start' => (int)$start,
        'maxResults' => (int)$maxresults,
        'filter' => (boolean)$filter,
        'restrict' => $restrict,
        'safeSearch' => (boolean)$safesearch,
        'lr' => $lang,
        'ie' => '',
        'oe' => ''
        );

        // on tente d'instancier le client SOAP
        try {
            $Client = new SoapClient($this->WsdlUri);
        }
        // Erreur : on gére une exception grâce à la classe SoapFault.
        // On retourne l'objet.
        catch (SoapFault $fault) {
            return $fault;
        }

        // On tente d'interroger le service web.
        try {
            $O =  $Client -> __call('DoGoogleSearch', $params);
        }
        // Erreur : on gére une exception grâce à la classe SoapFault.
        // On retourne l'objet.
        catch (SoapFault $fault) {
            return $fault;
        }

        // tout s'est bien déroulé, on retourne le résultat.
        return $O;
    }

    // DisplayError() prend un objet SoapFault comme parametre.
    // Cette méthode sera uniquement apellée de manière statique.
    public static function DisplayError(SoapFault $fault) {

        echo 'SOAP Fault :<br/> <strong>FaultCode</strong> : ',
        $fault -> faultcode,
        '<br/><strong>FaultString</strong> : ',
        $fault -> faultstring;
    }
}
?>

Utilisation

Nous allons construire un formulaire simple permettant d'interroger l'API de Google et d'en afficher les résultats.
On verifiera le résultat renvoyé par la classe grâce à la fonction is_soap_fault().

le code :

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="fr" xml:lang="fr">
<head>
    <title>Google Search</title>
    <style type="text/css">
        div {margin-top:1em; }
        label {display:block;}
        p{margin:0;}
        fieldset{width:15%;}
    </style>
</head>
<body>

<div>

<form method="post" action="<?php echo $_SERVER['PHP_SELF']; ?>">
    <fieldset>
        <legend> Votre recherche avec Google </legend>
        <div>
            <input type="text" name="search" tabindex="1" accesskey="s"/>
        </div>
        <div>
            <input type="submit" value="et hop" tabindex="2" accesskey="g"/>
        </div>
    </fieldset>
</form>
</div>

<hr/>

<?php

// Le formulaire a été soumis.
if(isset($_REQUEST['search'])) {
    // Inclusion de la source de la classe.
    include 'googleapi.php';
    // Nouvelle instance.
    $G = new GoogleApi;
    // Envoi de la requète au serveur SOAP.
    $O =  $G->Search($_REQUEST['search']);

    // Vérification du résultat renvoyé.
    if(is_soap_fault($O)) {
        // Affichage des erreurs
        // a apeller de manière statique
        GoogleApi::DisplayError($O);
        die();
    }

    // Tout s'est bien passé , on affiche sommairement le résultat.
    echo '<div>';
    echo '<div>NB results ::: ', $O->estimatedTotalResultsCount, '</div>';

    foreach($O->resultElements as $key => $val) {
        echo '<div>\/ ';
        echo '<a href="', $val->URL, '">', utf8_decode($val->title), '</a>';
        echo '</div>';
        echo '<p>';
        echo utf8_decode($val->snippet);
        echo '</p>';
        echo '<div>';
        echo '<a href="', $val->URL, '">', utf8_decode($val->URL), '</a> ---- ';
        echo 'en cache : ', $val->cachedSize;
        echo '</div>';
    }
    echo '</div>';
}
?>
</body>
</html>

Conclusion

La nouvelle extension SOAP arrivée en PHP 5 RC1 facilite énormément l'utilisation ou la création de services web. Sans cette extension il aurait fallu créer un client SOAP, ce qui nécessite quelques centaines de lignes de code , voir d'utiliser une classe comme nuSoap (qui fait elle quelques milliers de lignes).

Liens

Quelques liens utiles :

Fabrice Lezoray < fabrice AT scriptsphp.org >
Merci à microtom pour la relecture et les tests.

Trackback

Il n'y a pas de trackback recensé pour cet article.

Faire un trackback sur cet article http://classes.scriptsphp.org/Trackbackserver.Api-Google-et-SOAP, récupérer les trackback sur cet article