Comienza a usar la biblioteca cliente de PHP de datos de Google

Advertencia: Esta página trata sobre las API anteriores de Google, las API de datos de Google, y solo es relevante para las API que aparecen en el directorio de las API de datos de Google, muchas de las cuales se reemplazaron con API más nuevas. Para obtener información sobre una API nueva específica, consulta la documentación de la API nueva. Para obtener información sobre cómo autorizar solicitudes con una API más reciente, consulta Autenticación y autorización de cuentas de Google.

Video: Mira a Trevor Johns pasar por la instalación de la biblioteca cliente, la arquitectura de la biblioteca y una explicación en código.

Jochen Hartmann, equipo de API de datos de Google
Actualizado en octubre de 2008 (Escrito originalmente por Daniel Holevoet)

Introducción

La biblioteca cliente de PHP de datos de Google es un potente conjunto de clases que le permiten interactuar con las API de datos de Google. A diferencia de nuestras otras bibliotecas cliente, se empaquetan como parte del popular Zend Framework, pero también se pueden descargar por separado. Al igual que nuestras otras bibliotecas cliente, también es de código abierto y está diseñado para ser sencillo y eficiente, lo que te permite comenzar a trabajar en tus proyectos con rapidez.

Preinstalación

Ya puede estar instalado PHP en su máquina de desarrollo o servidor web, por lo que el primer paso es verificar ese hecho y asegurarse de que la versión de PHP sea lo suficientemente reciente para usarla en la biblioteca cliente. La manera más sencilla de comprobarlo es colocar un nuevo archivo en un directorio de acceso web en tu servidor. Escribe la siguiente información en el archivo:

<?php phpinfo(); ?>

Luego, establece los permisos correspondientes y navega hasta su ubicación desde el navegador para asegurarte de que se pueda acceder a ella desde la Web. Si PHP está instalado y tu servidor puede procesar las páginas de PHP, deberías ver algo similar a lo que se muestra en la siguiente captura de pantalla:

captura de pantalla de php info

La captura de pantalla muestra la página de información de PHP. En esta página, se muestra la versión de PHP que se instaló (en este caso, 5.2.6), junto con las extensiones que se habilitaron (en la sección "Configurar comando") y la ubicación del archivo de configuración interna de PHP (en la sección "Archivo de configuración cargada"). Si la página no se muestra o si su versión de PHP es anterior a 5.1.4, deberá instalar o actualizar su versión de PHP. De lo contrario, puedes omitir la siguiente sección y continuar con la instalación de la biblioteca cliente de PHP.

Nota: Si tienes acceso a la línea de comandos y planeas usar PHP para ejecutar las secuencias de comandos, consulta la sección de PHP de la línea de comandos de este artículo.

Instala PHP

La instalación varía según la plataforma, por lo que es importante que sigas las instrucciones de tu plataforma específica durante la instalación. Antes de comenzar, vale la pena mencionar que los paquetes preinstalados que también incluyen el servidor web Apache y la base de datos MySQL junto con PHP han ganado popularidad. Para Windows, Mac OS X y Linux, existe el proyecto XAMPP. Los usuarios de Mac OS X también pueden usar el proyecto MAMP. Ambos paquetes admiten OpenSSL en PHP, que es necesario para interactuar con los feeds autenticados.

Si instalas PHP con los pasos que se indican a continuación, asegúrate de instalar y habilitar OpenSSL. Puedes encontrar más información sobre este tema en la sección de OpenSSL en el sitio de PHP. Las siguientes secciones se enfocan en cómo instalar PHP por su cuenta.

En Windows

La manera más fácil de instalar o actualizar PHP en Windows es con el instalador de PHP disponible en la página de descargas de PHP.

  1. Elija la opción de instalación de PHP (en la sección Objetos binarios de Windows) que corresponda a la versión más reciente de PHP y permita que se descargue.
  2. Abre el instalador y sigue las instrucciones del asistente de instalación.
  3. Cuando el asistente te lo solicite, elige el servidor web que está instalado en tu sistema para que configure el servidor para que funcione con PHP.
  4. Para verificar la instalación, sigue los pasos que se describen en la sección anterior.

En Mac OS X

PHP se incluye en OS X, pero antes de usarlo, debes actualizar a la versión más reciente de PHP. Para realizar la actualización, puedes instalar cualquiera de varios paquetes binarios gratuitos o compilarlo tú mismo. Para obtener más información, consulta la página de documentación de PHP sobre la instalación en Mac OS X.

Después de instalar o configurar OS X, verifica tu instalación mediante los pasos que se describen en la sección previa a la instalación de este documento.

En Linux

Según la distribución de Linux, puede haber una opción de instalación integrada o fácil de usar para PHP. Por ejemplo, en Ubuntu, puedes usar un administrador de paquetes o simplemente escribir lo siguiente en una terminal:

sudo apt-get install php5

Si no hay una instalación empaquetada disponible con tu distribución de Linux, debes realizar la instalación desde el código fuente. Hay instrucciones detalladas a fin de compilar PHP para Apache 1.3 y Compilar PHP para Apache 2. PHP.net también tiene instrucciones para otros servidores.

Instala la biblioteca cliente de PHP de datos de Google

Ahora que tiene instalada una versión de PHP en funcionamiento, es momento de instalar la biblioteca cliente. La biblioteca cliente es parte del marco de trabajo de código abierto de Zend, pero también se puede descargar como una versión independiente. Si ya tienes instalada una versión de Zend Framework (versión 1.6 o posterior), puedes omitir la instalación porque se incluye la biblioteca cliente de datos de Google. Sin embargo, te recomendamos que uses la versión más reciente del marco de trabajo para asegurarte de que tienes acceso a todas las funciones y correcciones de errores más recientes.

Si descargas el marco de trabajo completo, no solo podrás acceder a la biblioteca cliente de datos de Google, sino también al resto. La biblioteca cliente usa otras clases que forman parte de Zend Framework completo, pero no es necesario descargar el framework completo, ya que lo incluimos en la descarga independiente.

  1. Descarga los archivos de la biblioteca cliente de datos de Google. (en esa página, busque "Google Data APIs").
  2. Descomprime los archivos descargados. Se deben crear cuatro subdirectorios:
    • demos: Aplicaciones de muestra
    • documentation: Documentación de los archivos de la biblioteca cliente
    • library: los archivos de origen de la biblioteca cliente reales.
    • tests: Archivos de prueba de unidades para pruebas automatizadas.
  3. Agrega la ubicación de la carpeta library a la ruta de acceso de PHP (consulta la sección siguiente).

Verifica que puedes acceder a los archivos de la biblioteca cliente

El último paso es asegurarse de que puedas hacer referencia a los archivos de la biblioteca cliente PHP del directorio que estás compilando, y de incluirlos. Esto se logra mediante la configuración de la variable include_path en el archivo de configuración de PHP (php.ini). La variable include_path contiene una cantidad de ubicaciones de directorio que PHP analiza cuando emites una declaración require o include que extrae clases, bibliotecas o archivos externos a tu secuencia de comandos actual, similar a la sentencia import en Java. Debes agregar la ubicación de los archivos de la biblioteca cliente a lo que ya se configuró en tu include_path. Esto se puede lograr de dos maneras (ambas se explican en detalle a continuación):

  • Establece la directiva include_path de forma permanente en el archivo de configuración php.ini desde la línea de comandos: requiere acceso de shell y permisos de escritura.
  • Configura la variable de ruta include_path en un nivel "por directorio". Esto requiere el servidor web Apache y la capacidad de crear archivos .htaccess.
  • Usa la función set_include_path() para establecer de forma dinámica la ruta de inclusión en tus secuencias de comandos; puedes establecerla dinámicamente en cada uno de tus archivos .php.

Si tienes acceso de shell y permisos de escritura en el archivo php.ini (o si escribes código en tu máquina local), solo sigue las instrucciones del apéndice A. Si usas el servidor web Apache y puedes crear archivos .htaccess, puedes configurar la variable include_path en el nivel "por directorio", lo que significa que todos los archivos del directorio en el que estás trabajando pueden hacer referencia automáticamente al directorio de la biblioteca cliente.

Puedes especificar las opciones de configuración de PHP como se muestra en el siguiente fragmento:

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

Nota: Consulta el Manual de PHP para obtener más información sobre cómo cambiar la configuración.

Si no tienes acceso de shell a tu servidor y no puedes modificar ni crear archivos .htaccess, siempre puedes usar la función set_include_path. Ten en cuenta que es posible que ya tengas establecido algún valor para tu include_path. Por lo tanto, te recomendamos seguir el modelo a continuación para agregar los valores nuevos, en lugar de reemplazar toda la ruta:

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

Nota: Consulta las páginas manuales de PHP para obtener más detalles sobre la función set_include_path.

Ejecuta el verificador de instalación de PHP

Para verificar que la ruta de inclusión se haya establecido correctamente, puedes ejecutar la secuencia de comandos Installation Checker de PHP. Simplemente copie y pegue el contenido de ese archivo en un nuevo archivo en un directorio accesible en la Web en su servidor y navegue hasta él desde su navegador. Si ve un resultado similar al siguiente, significa que todo se configuró correctamente y está listo para usar la biblioteca cliente de PHP:

captura de pantalla de salida del verificador de instalación de php

Si ves errores (como se muestra en la siguiente captura de pantalla), asegúrate de seguir las instrucciones. Es posible que falten extensiones o que la ruta no esté configurada correctamente. Recuerda que es posible que tengas que reiniciar el servidor para que se apliquen los cambios. Esto solo se aplica si realmente estás modificando el archivo php.ini. En la siguiente captura de pantalla, se muestra que include_path está configurado en /path/to/nowhere:

captura de pantalla de salida del verificador de instalación de php

Nota: Ten en cuenta que el verificador de instalación de PHP verifica lo siguiente: (1) son las extensiones de PHP necesarias instaladas, (2) el punto include_path apunta al directorio de la biblioteca cliente de PHP, (3) se pueden realizar conexiones SSL y, por último, se puede realizar una conexión a la API de datos de YouTube. Si una prueba en particular falla, las demás pruebas no se ejecutarán.

Ahora que la biblioteca cliente está instalada, es momento de intentar ejecutar las muestras.

Ejecuta las muestras

En la raíz del directorio Zend/Gdata, hay una carpeta de demostraciones (muestras para ayudarte a comenzar). Algunas de estas muestras están diseñadas para ejecutarse desde la línea de comandos, como demos/Zend/Gdata/Blogger.php y demos/Zend/Gdata/Spreadsheet-ClientLogin.php, y puedes ejecutarlas con php /path/to/example. Las muestras restantes se pueden ejecutar desde la línea de comandos y desde un navegador web. Si deseas verlas en un navegador, debes colocarlas en el directorio en el que las uses para publicar páginas web. Estas muestras deben brindar una idea básica sobre cómo escribir y ejecutar una aplicación de datos de Google, pero cuando estés listo para más, hay otros recursos para el programador de la curiosidad.

Nota: Si te interesa ver las demostraciones basadas en la Web en línea, visita googlecodesamples.com y busca las aplicaciones de PHP.

Dónde obtener más información

Los mejores lugares para buscar información sobre las clases que forman parte de la biblioteca cliente es la guía de referencia de la API en el sitio de Zend Framework. Asegúrate de seleccionar el paquete Zend_Gdata en el menú desplegable.

En este punto, ya estás listo para comenzar a codificar. Ahora, escriban algunas aplicaciones excelentes. ¡Esperamos ver tus resultados!

Puede encontrar guías para desarrolladores de PHP sobre los siguientes servicios:

Dado que la biblioteca cliente de PHP es un proyecto de código abierto, se agrega compatibilidad con más API de forma continua. Cada servicio tiene su propio grupo de asistencia; consulta nuestra entrada de Preguntas frecuentes para ver una lista de los grupos de asistencia disponibles.

Si necesita ayuda para solucionar problemas relacionados con llamadas a la API, encontrará artículos disponibles acerca de cómo depurar solicitudes a la API con las herramientas de captura de tráfico de red y sobre cómo usar servidores proxy con las API de datos de Google. También hay algunos artículos externos disponibles sobre cómo instalar XAMPP en Linux y sobre cómo instalar XAMPP en Windows. Además de todos estos artículos, asegúrese de consultar las publicaciones sobre la biblioteca cliente de PHP en el blog de sugerencias de la API de datos de Google.

Apéndice A: Edita tu ruta de acceso de PHP en el archivo de configuración php.ini

La ruta de acceso de PHP es una variable que contiene una lista de ubicaciones que PHP busca cuando busca bibliotecas adicionales durante la carga. Para que PHP pueda cargar y acceder a los archivos de la biblioteca cliente de PHP de datos de Google en su máquina o servidor, estos deberán colocarse en una ubicación que PHP conozca. Como alternativa, la ubicación de los archivos debe agregarse a la ruta de acceso de PHP. Ten en cuenta que, para aplicar cambios en el archivo php.ini, debes reiniciar el servidor. Puedes verificar el valor actual de la variable include_path en cualquier momento. Para ello, navega a la página Información de PHP que analizamos antes. Busque la celda Loaded Configuration File en la primera tabla y busque la ruta en la columna a la derecha.

Nota: Si usas php desde la línea de comandos, es posible que debas modificar una variable de ruta adicional. Asegúrese de revisar el Apéndice B: Cómo usar PHP desde la línea de comandos.

Una vez que hayas encontrado el archivo php.ini, sigue estos pasos para agregarlo a la ruta.

  1. Abre el archivo php.ini en tu editor de texto favorito.
  2. Ubica la línea que hace referencia a la ruta de acceso de PHP, debe comenzar con include_path.
  3. Agrega la ruta de acceso que almacenaste en Zend Framework a la lista de ubicaciones que ya tienes, anteponiendo la nueva ruta con el separador designado para tu SO (: en sistemas similares a Unix, ; en Windows). Una ruta correcta en sistemas similares a Unix sería similar a lo siguiente: 
    /path1:/path2:/usr/local/lib/php/library
    En Windows, sería similar a lo siguiente: 
    \path1;\path2;\php\library
  4. Guarda el archivo y ciérralo.

Nota: En Mac OS X, Finder no permite el acceso a archivos que se encuentren en ubicaciones del sistema, como el directorio /etc. Por lo tanto, tal vez sea más fácil editarlos con un editor de línea de comandos, como vi o pico. Para hacerlo, usa un comando como pico /path/to/php.ini.

Apéndice B: Cómo usar PHP desde la línea de comandos

A partir de la versión 5 de PHP, existe una utilidad de línea de comandos disponible en PHP. Esto se conoce como CLI para “intérprete de línea de comandos”. El uso de esta utilidad permite que las secuencias de comandos php se ejecuten desde la línea de comandos. Esto puede resultar útil si ejecuta PHP de forma local en su máquina y busca formas rápidas de probar algunas secuencias de comandos. Por supuesto, en tu servidor, se requiere acceso de shell. Algo importante que debes tener en cuenta es que, por lo general, PHP usa dos archivos php.ini separados: uno contiene las opciones de configuración para PHP que se ejecutan en el servidor y otro para las configuraciones que PHP usa cuando se ejecuta desde la línea de comandos. Si te interesa ejecutar las aplicaciones de demostración de línea de comandos desde la biblioteca cliente, también deberás modificar el archivo php.ini de la línea de comandos.

Para ubicarlo, escriba los siguientes comandos en sistemas similares a Unix (Mac OS X, Linux y otros):

php -i | grep php.ini

Ese comando debería mostrar la siguiente información en la terminal:

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

Nota: Por supuesto, las ubicaciones reales de la ruta de acceso (/etc/php...) pueden variar en tu sistema.

Apéndice C: Sugerencias y soluciones

Esta sección contiene un breve resumen de algunos de los problemas que los desarrolladores han descubierto al trabajar con PHP y las soluciones adecuadas.

Problema con la extensión dom-xml en XAMPP

La biblioteca cliente de PHP usa las clases de DOMDocument para transformar las solicitudes y respuestas XML en objetos PHP. La extensión dom-xml puede causar problemas con el manejo de XML y dar como resultado transformaciones incorrectas. Algunos de nuestros desarrolladores descubrieron que, cuando usan XAMPP, se anula el constructor de DOMDocument con una llamada de función anterior, como se explica en el sitio de PHP. Para solucionar este problema, asegúrate de que el control de XML no se reemplace en el archivo php.ini. Asegúrate de quitar las referencias a php_domxml.dll del archivo de configuración.

Se agota el tiempo de espera de las solicitudes cuando se usa la biblioteca cliente

Si usas la biblioteca cliente para realizar solicitudes bastante grandes, como subir videos a la API de datos de YouTube, es posible que debas cambiar el parámetro timeout en tu clase Zend_Http_Client. Esto se puede realizar con facilidad si se pasa un parámetro $config durante la creación de la instancia, que establece el valor timeout en un valor distinto del predeterminado de 10 segundos:

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

Algunos proveedores de hosting no permiten conexiones HTTPS desde sus servidores

Sabemos que algunos proveedores de hosting no te permiten establecer conexiones de https desde sus servidores predeterminados. Si recibes un mensaje de error similar al siguiente, es posible que debas realizar las conexiones HTTPS mediante un proxy seguro:

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

Tu proveedor de hosting debe proporcionar información sobre la dirección real del servidor proxy para usar. En el siguiente fragmento, se muestra cómo se puede usar una configuración de proxy personalizada con la biblioteca cliente de 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");

}

Historial de revisión

1 de octubre de 2008

Actualizado por Jochen Hartmann. Esta actualización incluye los siguientes cambios:

  • Trasladar las secciones que hacen referencia a PHP de la línea de comandos a un apéndice, ahora hace que la configuración de PHP para los servidores web sea más clara.
  • Se agregó una nota sobre varios archivos de configuración php.ini.
  • Se agregaron secciones sobre cómo configurar dinámicamente include_path.
  • Se agregó la sección en la secuencia de comandos del verificador de la instalación.
  • Se agregó el vínculo a las muestras en línea.
  • Se agregaron vínculos para XAMPP y MAMP.
  • Se agregó un apéndice de "Sugerencias y soluciones".