Premiers pas avec la bibliothèque cliente PHP de données Google

Avertissement: Cette page concerne les anciennes API Google, les API Google Data. Elle ne concerne que les API répertoriées dans l'annuaire des API Google Data, dont la plupart ont été remplacées par de nouvelles API. Pour en savoir plus sur une nouvelle API spécifique, consultez sa documentation. Pour en savoir plus sur l'autorisation des requêtes avec une API plus récente, consultez Authentification et autorisation des comptes Google.

Vidéo : suivez les étapes de l'installation de la bibliothèque cliente, de l'architecture de la bibliothèque et du tutoriel de code que Trevor Johns propose.

Jochen Hartmann, équipe Google Data APIs
Mise à jour d'octobre 2008 (à l'origine par Daniel Holevoet)

Introduction

La bibliothèque cliente PHP de données Google est un ensemble puissant de classes vous permettant d'interagir avec les API Google Data. Contrairement à nos autres bibliothèques clientes, elle est intégrée au framework de Zend, bien qu'elle puisse également être téléchargée séparément. À l'instar des autres bibliothèques clientes, cette solution Open Source est conçue pour être simple et efficace, pour vous permettre de démarrer rapidement vos projets.

Préinstallation

PHP est peut-être déjà installé sur votre ordinateur ou serveur de développement. La première étape consiste donc à vérifier cette information et à vérifier que la version de PHP est suffisamment récente pour être utilisée pour la bibliothèque cliente. La méthode la plus simple consiste à placer un nouveau fichier dans un répertoire accessible sur le Web sur votre serveur. Saisissez les informations suivantes dans le fichier:

<?php phpinfo(); ?>

Assurez-vous ensuite qu'elle est accessible sur le Web en définissant les autorisations appropriées et en accédant à son emplacement depuis votre navigateur. Si PHP est installé et que votre serveur parvient à afficher les pages PHP, vous devriez voir une capture d'écran semblable à la capture d'écran ci-dessous:

Capture d&#39;écran de la page d&#39;informations PHP

La capture d'écran montre la page d'informations PHP. Cette page vous indique la version de PHP installée (5.2.6 dans cet exemple), ainsi que les extensions qui ont été activées (dans la section "Configurer la commande") et l'emplacement du fichier de configuration interne de PHP (dans la section "Fichier de configuration chargé"). Si la page ne s'affiche pas ou si votre version de PHP est antérieure à 5.1.4, vous devez installer ou mettre à jour votre version de PHP. Sinon, vous pouvez ignorer la section suivante et continuer à installer la bibliothèque cliente PHP.

Remarque : Si vous avez accès à la ligne de commande et que vous prévoyez d'utiliser PHP pour exécuter des scripts de ligne de commande, consultez la section PHP correspondante.

Installer PHP

L'installation varie légèrement d'une plate-forme à l'autre. Il est donc important de suivre les instructions spécifiques à votre plate-forme lors de l'installation. Avant de nous lancer, il est intéressant de souligner que les packages préinstallés qui incluent également le serveur Web Apache, la base de données MySQL et PHP ont gagné en popularité. Pour Windows, Mac OS X et Linux, il existe le projet XAMPP. Les utilisateurs de Mac OS X peuvent également utiliser le projet MAMP. Ces deux packages sont compatibles avec OpenSSL en PHP (qui est requis pour interagir avec les flux authentifiés).

Si vous installez PHP en suivant les étapes ci-dessous, veillez également à installer et à activer OpenSSL. Pour en savoir plus, consultez la section OpenSSL du site PHP. Les sections suivantes décrivent comment installer PHP seul.

Sous Windows

Le moyen le plus simple d'installer ou de mettre à niveau PHP sous Windows est d'utiliser le programme d'installation PHP disponible sur la page des téléchargements PHP.

  1. Dans la section "Windows binaires", sélectionnez le programme d'installation de PHP correspondant à la dernière version de PHP, puis autorisez son téléchargement.
  2. Ouvrez le programme d'installation et suivez les instructions de l'assistant d'installation.
  3. Lorsque l'assistant vous y invite, choisissez le serveur Web qui est installé sur votre système, pour le configurer afin qu'il fonctionne avec PHP.
  4. Vérifiez votre installation en suivant la procédure décrite dans la section ci-dessus.

Sous Mac OS X

PHP est inclus dans OS X, mais avant de l'utiliser, vous devez passer à la dernière version de PHP. Pour la mise à niveau, vous pouvez installer l'un des packages binaires sans frais ou le compiler vous-même. Pour en savoir plus, consultez la page de documentation PHP sur l'installation sur Mac OS X.

Une fois que vous avez installé ou configuré OS X, vérifiez votre installation en suivant la procédure décrite dans la section Préinstallation de ce document.

Sous Linux

Selon la distribution Linux, il peut y avoir une option intégrée ou facile à utiliser pour l'installation de PHP. Par exemple, sur Ubuntu, vous pouvez utiliser un gestionnaire de packages ou simplement saisir le code suivant dans un terminal:

sudo apt-get install php5

Si aucune installation empaquetée n'est disponible avec votre distribution Linux, vous devez effectuer l'installation à partir du code source. Vous trouverez des instructions détaillées sur la compilation de PHP pour Apache 1.3 et la compilation de PHP pour Apache 2. PHP.net contient également des instructions pour les autres serveurs.

Installer la bibliothèque cliente PHP de données Google

Maintenant que vous avez installé une version de PHP, il est temps d'installer la bibliothèque cliente. La bibliothèque cliente fait partie du framework Open Source Zend, mais peut également être téléchargée en tant que version autonome. Si une version de Zend Framework est déjà installée (version 1.6 ou ultérieure), vous pouvez ignorer l'installation, car la bibliothèque cliente Google Data est incluse. Toutefois, nous vous recommandons de vous assurer que vous utilisez la dernière version du framework. C'est pourquoi nous vous recommandons d'utiliser la dernière version.

En téléchargeant le framework complet, vous aurez accès non seulement à la bibliothèque cliente Google Data, mais aussi au reste du framework. La bibliothèque cliente elle-même utilise d'autres classes qui font partie du framework Zend complet, mais il n'est pas nécessaire de télécharger l'intégralité du framework, car nous les avons regroupées dans le téléchargement autonome.

  1. Téléchargez les fichiers de la bibliothèque cliente Google Data. Sur cette page, recherchez "Google Data APIs".
  2. Décompressez les fichiers téléchargés. Vous devez créer quatre sous-répertoires :
    • demos : exemples d'applications
    • documentation : documentation sur les fichiers de la bibliothèque cliente
    • library : fichiers sources réels de la bibliothèque cliente.
    • tests : fichiers de tests unitaires pour les tests automatisés.
  3. Ajoutez l'emplacement du dossier library à votre chemin PHP (consultez la section suivante).

Vérification de l'accès aux fichiers de la bibliothèque cliente

La dernière étape consiste à vérifier que vous pouvez référencer et inclure les fichiers de la bibliothèque cliente PHP à partir du répertoire dans lequel vous créez le projet. Pour ce faire, vous devez définir la variable include_path dans le fichier de configuration de PHP (php.ini). La variable include_path contient un certain nombre d'emplacements de répertoire que PHP examine lorsque vous émettez une instruction require ou include qui extrait des classes, des bibliothèques ou des fichiers externes dans votre script actuel, semblable à l'instruction import en Java. Vous devez ajouter l'emplacement des fichiers de la bibliothèque cliente à ceux qui ont déjà été définis dans include_path. Pour cela, vous avez le choix entre deux méthodes :

  • Définissez de manière permanente l'instruction include_path dans votre fichier de configuration php.ini à partir de la ligne de commande. Elle nécessite un accès à l'interface système et des autorisations d'écriture.
  • Définissez la variable de chemin d'accès include_path au niveau "par répertoire". Elle nécessite le serveur Web Apache et la possibilité de créer des fichiers .htaccess.
  • Utilisez la fonction set_include_path() pour définir de manière dynamique le chemin d'inclusion dans vos scripts (vous pouvez le faire de façon dynamique dans chacun de vos fichiers .php).

Si vous disposez d'un accès shell et d'autorisations d'écriture sur le fichier php.ini (ou si vous écrivez du code sur votre ordinateur local), suivez simplement les instructions de l'annexe A. Si vous utilisez le serveur Web Apache et avez la possibilité de créer des fichiers .htaccess, vous pouvez définir la variable include_path au niveau "par répertoire", ce qui signifie que tous les fichiers du répertoire sur lequel vous travaillez peuvent automatiquement référencer le répertoire de la bibliothèque cliente.

Vous pouvez spécifier des options de configuration PHP comme indiqué dans l'extrait ci-dessous:

# This works for PHP5 in both Apache versions 1 and 2
<IfModule mod_php5.c>
  php_value include_path        ".:/usr/local/lib/php:/path/to/ZendGdata/library"
</IfModule>

Remarque:Consultez le manuel PHP pour en savoir plus sur la modification des paramètres de configuration.

Si vous n'avez pas accès à l'interface système de votre serveur et que vous ne pouvez pas modifier ni créer des fichiers .htaccess, vous pouvez toujours utiliser la fonction set_include_path. Notez que vous avez peut-être déjà défini des valeurs pour votre include_path. Il peut donc être judicieux de suivre le modèle ci-dessous pour ajouter les nouvelles valeurs plutôt que d'écraser le chemin complet:

$clientLibraryPath = '/path/to/ZendGdata/library';
$oldPath = set_include_path(get_include_path() . PATH_SEPARATOR . $clientLibraryPath);

Remarque:Veuillez consulter les pages manuelles PHP pour en savoir plus sur la fonction set_include_path.

Exécuter le vérificateur d'installation PHP

Pour vérifier que votre chemin d'inclusion a été défini correctement, vous pouvez exécuter le script PHP Installation Checker. Il vous suffit de copier et coller le contenu de ce fichier dans un nouveau fichier d'un répertoire accessible sur le Web sur votre serveur, puis d'y accéder depuis votre navigateur. Si un résultat semblable au suivant s'affiche, cela signifie que tout a été configuré correctement et que vous êtes prêt à utiliser la bibliothèque cliente PHP:

Capture d&#39;écran de la sortie du vérificateur d&#39;installation PHP

Si vous rencontrez des erreurs (comme dans la capture d'écran ci-dessous), assurez-vous de suivre les instructions. Il est possible que des extensions soient manquantes ou que votre chemin d'accès ne soit toujours pas correctement défini. N'oubliez pas que vous devrez peut-être redémarrer votre serveur pour que les modifications soient prises en compte. Cela ne s'applique que si vous modifiez réellement le fichier php.ini. La capture d'écran ci-dessous montre que include_path est défini sur /path/to/nowhere :

Capture d&#39;écran de la sortie du vérificateur d&#39;installation PHP

Remarque:Le vérificateur d'installation PHP vérifie les points suivants: (1) les extensions PHP requises sont-elles installées ? (2) le point d'accès include_path pointe-t-il vers le répertoire de la bibliothèque cliente PHP ? (3) les connexions SSL peuvent-elles être effectuées ? Enfin, une connexion peut-elle être établie vers l'API YouTube Data ? Si un test spécifique échoue, les autres tests ne seront pas exécutés.

Maintenant que la bibliothèque cliente est installée, il est temps d'essayer d'exécuter les exemples.

Exécuter les exemples

À la racine du répertoire Zend/Gdata se trouve un dossier de démonstrations, des exemples pour vous aider à démarrer. Certains de ces exemples sont conçus pour être exécutés à partir de la ligne de commande, comme demos/Zend/Gdata/Blogger.php et demos/Zend/Gdata/Spreadsheet-ClientLogin.php. Vous pouvez les exécuter avec php /path/to/example. Les exemples restants peuvent être exécutés à partir de la ligne de commande et d'un navigateur Web. Si vous souhaitez les afficher dans un navigateur, ceux-ci doivent être placés dans le répertoire que vous utiliserez pour diffuser les pages Web. Ces exemples devraient vous donner une idée de base de l'écriture et de l'exécution d'une application Google Data, mais lorsque vous êtes prêt à aller plus loin, d'autres ressources sont à votre disposition pour le programmeur curieux.

Remarque : Si vous souhaitez voir les démonstrations en ligne sur Googlecodesamples.com, recherchez les applications PHP.

Pour en savoir plus

Pour trouver des informations sur les classes qui font partie de la bibliothèque cliente, consultez le guide de référence de l'API sur le site Zend Framework. Veillez à sélectionner le package Zend_Gdata dans le menu déroulant.

À ce stade, vous devriez commencer à coder. Continuez à écrire des applications de qualité. Nous attendons vos résultats avec impatience !

Des guides du développeur PHP sont disponibles pour les services suivants:

La bibliothèque cliente PHP étant un projet Open Source, la compatibilité avec d'autres API est en constante évolution. Chaque service dispose de son propre groupe d'assistance. Pour consulter la liste des groupes d'assistance disponibles, consultez notre FAQ.

Si vous avez besoin d'aide pour résoudre les problèmes liés aux appels d'API, vous trouverez des articles sur le débogage des requêtes d'API à l'aide des outils de capture du trafic réseau et sur l'utilisation de serveurs proxy avec les API Google Data. Vous trouverez également des articles externes sur l'installation de XAMPP sous Linux et l'installation de XAMPP sous Windows. En plus de tous ces articles, consultez les posts sur la bibliothèque cliente PHP dans le blog sur les API Google Data.

Annexe A: Modifier le chemin d'accès PHP dans le fichier de configuration php.ini

Le chemin PHP est une variable qui contient la liste des emplacements recherchés par PHP lorsqu'il recherche des bibliothèques supplémentaires lors du chargement. Pour que PHP puisse charger et accéder aux fichiers de la bibliothèque cliente PHP des données Google sur votre ordinateur ou votre machine, vous devez les placer dans un emplacement connu de PHP. Vous pouvez également ajouter l'emplacement des fichiers à votre chemin PHP. Notez que les modifications apportées au fichier php.ini nécessitent généralement un redémarrage de votre serveur. Vous pouvez toujours vérifier la valeur actuelle de la variable include_path en accédant à la page d'informations PHP décrite précédemment. Recherchez la cellule Loaded Configuration File dans le premier tableau et recherchez le chemin d'accès dans la colonne de droite.

Remarque:Si vous utilisez php à partir de la ligne de commande, vous devrez peut-être modifier une variable de chemin supplémentaire. Veillez à consulter l'annexe B: Utiliser PHP à partir de la ligne de commande.

Une fois que vous avez trouvé le fichier php.ini, procédez comme suit pour l'ajouter au chemin d'accès.

  1. Ouvrez le fichier php.ini dans votre éditeur de texte préféré.
  2. Recherchez la ligne qui fait référence au chemin PHP. Elle doit commencer par include_path.
  3. Ajoutez le chemin d'accès que vous avez stocké dans le framework Zend à la liste des emplacements déjà présents, en précédant votre nouveau chemin d'accès avec le séparateur désigné pour votre système d'exploitation (: sur les systèmes de type Unix, ; sous Windows). Sur les systèmes de type Unix, un chemin d'accès correct devrait se présenter comme suit : 
    /path1:/path2:/usr/local/lib/php/library
    Sous Windows, il devrait se présenter comme suit : 
    \path1;\path2;\php\library
  4. Enregistrez et fermez le fichier.

Remarque : Sur Mac OS X, le Finder ne permet pas d'accéder aux fichiers situés dans des emplacements système tels que le répertoire /etc. Il est donc plus facile de les modifier à l'aide d'un éditeur de ligne de commande tel que vi ou pico. Pour ce faire, utilisez une commande telle que pico /path/to/php.ini.

Annexe B: Utiliser PHP à partir de la ligne de commande

À partir de la version 5 de PHP, un utilitaire de ligne de commande, appelé CLI, est un utilitaire de ligne de commande appelé "interpréteur de ligne de commande". Cet utilitaire permet d'exécuter des scripts PHP depuis la ligne de commande. Cela peut être utile si vous exécutez PHP localement sur votre machine et que vous cherchez des moyens de tester rapidement certains scripts. Bien sûr, cela nécessitera un accès à l'interface système sur votre serveur. Il est important de noter que PHP utilise généralement deux fichiers php.ini distincts : l'un contient les options de configuration de PHP s'exécutant sur votre serveur et l'autre, celles qui s'exécutent sur PHP à partir de la ligne de commande. Si vous souhaitez exécuter les applications de démonstration en ligne de commande à partir de la bibliothèque cliente, vous devez également modifier le fichier php.ini de la ligne de commande.

Pour le trouver, saisissez les commandes suivantes sur des systèmes de type Unix (Mac OS X, Linux, etc.):

php -i | grep php.ini

Cette commande devrait entraîner l'affichage des informations suivantes dans votre terminal:

Configuration File (php.ini) Path => /etc/php5/cli
Loaded Configuration File => /etc/php5/cli/php.ini

Remarque:Bien évidemment, les emplacements du chemin (/etc/php...) peuvent être différents sur votre système.

Annexe C: Conseils et solutions

Cette section contient une brève description du problème que les développeurs ont découvert lors de l'utilisation de PHP, ainsi que les solutions appropriées.

Problème lié à l'extension dom-xml dans XAMPP

La bibliothèque cliente PHP utilise les classes DOMDocument pour transformer les requêtes et les réponses XML en objets PHP. L'extension dom-xml peut poser des problèmes avec la gestion XML et entraîner des transformations incorrectes. Certains de nos développeurs ont constaté que, lors de l'utilisation de XAMPP, le constructeur DOMDocument est remplacé par un appel de fonction plus ancien, comme expliqué sur le site PHP. Pour résoudre ce problème, assurez-vous que le traitement XML n'est pas écrasé dans votre fichier php.ini. Veillez à supprimer les références à php_domxml.dll de votre fichier de configuration.

Les requêtes expirent au moment de l'utilisation de la bibliothèque cliente

Si vous utilisez la bibliothèque cliente pour effectuer des requêtes assez volumineuses, par exemple pour importer des vidéos dans l'API YouTube Data, vous devrez peut-être modifier le paramètre timeout dans votre classe Zend_Http_Client. Pour ce faire, il suffit de transmettre un paramètre $config lors de l'instanciation et de définir une valeur timeout autre que la valeur par défaut de 10 secondes:

// assuming your Zend_Http_Client already exists as $httpClient
// and that you want to change the timeout from the 10 second default to 30 seconds

$config = array('timeout' => 30);
$httpClient->setConfig($config);

Certains fournisseurs d'hébergement n'autorisent pas les connexions HTTPS à partir de leurs serveurs

Certains fournisseurs d'hébergement ne vous autorisent pas à établir de connexions https depuis leurs serveurs par défaut. Si un message d'erreur semblable à celui présenté ci-dessous s'affiche, vous devrez peut-être établir vos connexions HTTPS via un proxy sécurisé:

Unable to Connect to sslv2://www.google.com:443. Error #110: Connection timed out

Votre fournisseur d'hébergement doit disposer d'informations sur l'adresse réelle du serveur proxy à utiliser. L'extrait ci-dessous montre comment utiliser une configuration de proxy personnalisée avec la bibliothèque cliente PHP:

// Load the proxy adapter class in addition to the other required classes
Zend_Loader::loadClass('Zend_Http_Client_Adapter_Proxy');

// Configure the proxy connection with your hostname and portnumber
$config = array(
    'adapter'    => 'Zend_Http_Client_Adapter_Proxy',
    'proxy_host' => 'your.proxy.server.net',
    'proxy_port' => 3128
);

// A simple https request would be an attempt to authenticate via ClientLogin
$proxiedHttpClient = new Zend_Http_Client('http://www.google.com:443', $config);

$username = 'foo@example.com';
$password = 'barbaz';

// The service name would depend on what API you are interacting with, here
// we are using the Google DocumentsList Data API
$service = Zend_Gdata_Docs::AUTH_SERVICE_NAME;

// Try to perform the ClientLogin authentication using our proxy client.
// If there is an error, we exit since it doesn't make sense to go on.
try {

  // Note that we are creating another Zend_Http_Client
  // by passing our proxied client into the constructor.

  $httpClient = Zend_Gdata_ClientLogin::getHttpClient(
      $username, $password, $service, $proxiedHttpClient);

} catch (Zend_Gdata_App_HttpException $httpException) {

  // You may want to handle this differently in your application
  exit("An error occurred trying to connect to the proxy server\n" .
      $httpException->getMessage() . "\n");

}

Historique des révisions

1er octobre 2008

Mis à jour par Jochen Hartmann. Cette mise à jour inclut les changements suivants :

  • Clarification de la configuration PHP pour les serveurs Web en déplaçant les sections qui font référence à la ligne de commande PHP dans une annexe.
  • Ajout d'une remarque sur plusieurs fichiers de configuration php.ini.
  • Ajout de sections sur la définition dynamique du chemin inclus_path.
  • Ajout d'une section sur le script du vérificateur d'installation.
  • Ajout d'un lien vers des exemples en ligne.
  • Ajout de liens pour XAMPP et MAMP.
  • Ajout d'une annexe intitulée "Conseils et solutions".