Comienza a usar la biblioteca cliente de PHP de Google Data

Advertencia: Esta página trata sobre las APIs anteriores de Google, las APIs de Google Data, y solo es pertinente para las APIs que se enumeran en el directorio de las APIs de Google Data, muchas de las cuales se reemplazaron por APIs más nuevas. Para obtener información sobre una API nueva específica, consulta su documentación. 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 explicar la instalación de la biblioteca cliente, la arquitectura de la biblioteca y un recorrido por el código.

Jochen Hartmann, equipo de las APIs de datos de Google
Actualizado en octubre de 2008 (escrito originalmente por Daniel Holevoet)

Introducción

La biblioteca cliente de Google Data para PHP es una potente colección de clases que te permiten interactuar con las APIs de Google Data. A diferencia de nuestras otras bibliotecas cliente, se incluye como parte del popular Zend Framework, pero también se puede descargar por separado. Al igual que nuestras otras bibliotecas cliente, también es de código abierto y está diseñada para ser simple y eficiente, lo que te permite comenzar tus proyectos rápidamente.

Antes de la instalación

Es posible que PHP ya esté instalado en tu máquina de desarrollo o servidor web, por lo que el primer paso es verificar ese hecho y asegurarte de que la versión de PHP sea lo suficientemente reciente como para usarla con la biblioteca cliente. La forma más sencilla de verificarlo es colocar un archivo nuevo en un directorio accesible desde la Web en tu servidor. Escribe la siguiente información en el archivo:

<?php phpinfo(); ?>

Luego, asegúrate de que se pueda acceder a él desde la Web configurando los permisos adecuados y navegando a su ubicación desde tu navegador. Si PHP está instalado y tu servidor puede renderizar páginas PHP, deberías ver algo similar a la siguiente captura de pantalla:

Captura de pantalla de la página de información de PHP

En la captura de pantalla, se muestra la página de información de PHP. En esta página, se muestra la versión de PHP que se instaló (5.2.6 en este caso), junto con las extensiones que se habilitaron (en la sección "Configure Command") y la ubicación del archivo de configuración interno de PHP (en la sección "Loaded Configuration File"). Si no se muestra la página o si tu versión de PHP es anterior a la 5.1.4, deberás instalar o actualizar tu 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 secuencias de comandos de línea de comandos, consulta la sección de PHP de línea de comandos de este artículo.

Cómo instalar PHP

La instalación varía un poco según la plataforma, por lo que es importante que sigas las instrucciones para tu plataforma específica durante la instalación. Antes de comenzar, vale la pena señalar 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 feeds autenticados).

Si instalas PHP siguiendo los pasos que se indican a continuación, asegúrate de instalar y habilitar la compatibilidad con OpenSSL. Puedes encontrar más detalles en la sección de OpenSSL del sitio de PHP. En las siguientes secciones, se explica cómo instalar PHP por sí solo.

En Windows

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

  1. Elige la opción del instalador de PHP (en la sección de archivos binarios de Windows) que corresponda a la versión más reciente de PHP y permite 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 actualizarlo a la versión más reciente. Para actualizar, puedes instalar cualquiera de los paquetes binarios gratuitos o compilarlo tú mismo. Para obtener más detalles, 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 la instalación siguiendo 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, es posible que haya una opción de configuración integrada o fácil de usar para la instalación de 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 instalarla desde el código fuente. Existen instrucciones detalladas para 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 Google Data

Ahora que tienes instalada una versión de PHP que funciona, es momento de instalar la biblioteca cliente. La biblioteca cliente forma parte del Zend Framework de código abierto, 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, ya que se incluye la biblioteca cliente de Google Data. Sin embargo, asegurarte de que usas la versión más reciente del framework te garantizará que tengas todas las funciones y correcciones de errores más recientes disponibles, por lo que suele ser recomendable.

Si descargas el framework completo, tendrás acceso no solo a la biblioteca cliente de Google Data, sino también al resto del framework. La biblioteca cliente en sí usa algunas otras clases que forman parte del Zend Framework completo, pero no es necesario descargar todo el framework, ya que las incluimos en la descarga independiente.

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

Verifica que puedas acceder a los archivos de la biblioteca cliente

El último paso es asegurarte de que puedes hacer referencia a los archivos de la biblioteca cliente de PHP e incluirlos desde el directorio en el que compilas tu proyecto. Esto se logra configurando la variable include_path en el archivo de configuración de PHP (php.ini). La variable include_path contiene una cantidad de ubicaciones de directorios que PHP busca cuando emites una instrucción require o include que extrae clases, bibliotecas o archivos externos en tu secuencia de comandos actual, de manera similar a la instrucción 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 de forma permanente la directiva include_path en tu archivo de configuración php.ini desde la línea de comandos. Esto requiere acceso a la shell y permisos de escritura.
  • Establece la variable de ruta de acceso include_path a nivel de "cada directorio", lo que 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. Se puede establecer de forma dinámica en cada uno de tus archivos .php.

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

Puedes especificar 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 a la shell de 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 algún valor establecido para tu include_path, por lo que puede ser una buena idea seguir el siguiente modelo para agregar los valores nuevos, en lugar de sobrescribir toda la ruta de acceso:

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

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

Cómo ejecutar el verificador de instalación de PHP

Para verificar que la ruta de inclusión se haya configurado correctamente, puedes ejecutar la secuencia de comandos del Verificador de instalación de PHP. Simplemente copia y pega el contenido de ese archivo en un archivo nuevo en un directorio accesible desde la Web en tu servidor y navega a él desde tu navegador. Si ves un resultado similar al siguiente, significa que todo se configuró correctamente y que puedes usar la biblioteca cliente de PHP:

Captura de pantalla del resultado del verificador de instalación de PHP

Si ves errores (como en la captura de pantalla que se muestra a continuación), asegúrate de seguir la dirección. Es posible que falten extensiones o que la ruta aún no esté configurada correctamente. Recuerda que es posible que debas reiniciar el servidor para que se apliquen los cambios. Esto solo se aplica si realmente modificas el archivo php.ini. En la siguiente captura de pantalla, se muestra que el parámetro include_path está establecido en /path/to/nowhere:

Captura de pantalla del resultado del verificador de instalación de PHP

Nota: Ten en cuenta que el verificador de instalación de PHP comprueba los siguientes elementos en sucesión: (1) ¿Están instaladas las extensiones de PHP requeridas?, (2) ¿include_path apunta al directorio de la biblioteca cliente de PHP?, (3) ¿Se pueden realizar conexiones SSL? y, por último, ¿Se puede establecer una conexión con la API de YouTube Data? Si falla una prueba específica, no se ejecutarán las pruebas restantes.

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, es decir, muestras para ayudarte a comenzar. Algunos de estos ejemplos están diseñados para ejecutarse desde la línea de comandos, como demos/Zend/Gdata/Blogger.php y demos/Zend/Gdata/Spreadsheet-ClientLogin.php, y puedes ejecutarlos con php /path/to/example. Los ejemplos restantes se pueden ejecutar desde la línea de comandos y un navegador web. Si deseas verlos en un navegador, debes colocarlos en el directorio que usarías para publicar páginas web. Estos ejemplos deberían darte una idea básica de cómo escribir y ejecutar una aplicación de Google Data, pero, cuando estés listo para más, hay otros recursos para el programador curioso.

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 son 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 deberías tener todo listo para comenzar a programar. Así que adelante, escribe algunas aplicaciones excelentes. ¡Esperamos ver tus resultados!

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

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

Si necesitas ayuda para solucionar problemas con tus llamadas a la API, hay artículos disponibles sobre la depuración de solicitudes a la API con herramientas de captura de tráfico de red y sobre el uso de servidores proxy con las APIs de datos de Google. También hay algunos artículos externos disponibles sobre la instalación de XAMPP en Linux y la instalación de XAMPP en Windows. Además de todos estos artículos, asegúrate de consultar las publicaciones sobre la biblioteca cliente de PHP en el blog de sugerencias de las APIs de datos de Google.

Apéndice A: Edita tu ruta 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 Google Data en tu 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 tu ruta de acceso de PHP. Ten en cuenta que los cambios en el archivo php.ini suelen requerir que reinicies el servidor. Siempre puedes verificar el valor actual de la variable include_path navegando a la página PHP Info que se mencionó anteriormente. Busca la celda Loaded Configuration File en la primera tabla y encuentra la ruta de acceso en la columna de la derecha.

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

Una vez que encuentres el archivo php.ini, sigue estos pasos para agregar la ruta de acceso.

  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 en la que almacenaste Zend Framework a la lista de ubicaciones ya presentes, anteponiendo tu nueva ruta de acceso con el separador designado para tu SO (: en sistemas similares a Unix, ; en Windows). Una ruta correcta en sistemas similares a Unix se vería de la siguiente manera: 
    /path1:/path2:/usr/local/lib/php/library
     En Windows, se vería de la siguiente manera: 
    \path1;\path2;\php\library
  4. Guarda el archivo y ciérralo.

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

Apéndice B: Uso de PHP desde la línea de comandos

A partir de la versión 5 de PHP, hay una utilidad de línea de comandos disponible en PHP que se conoce como CLI para "intérprete de línea de comandos". El uso de esta utilidad permite ejecutar secuencias de comandos php desde la línea de comandos. Esto puede ser útil si ejecutas PHP de forma local en tu máquina y buscas formas de probar rápidamente algunos secuencias de comandos. Por supuesto, en tu servidor, esto requerirá acceso a la shell. Una cuestión importante que debes tener en cuenta es que PHP suele usar dos archivos php.ini separados: uno contiene las opciones de configuración para PHP que se ejecuta en tu 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 línea de comandos.

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

php -i | grep php.ini

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

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

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

Apéndice C: Sugerencias y soluciones

En esta sección, se incluye un breve resumen de algunos de los problemas que los desarrolladores descubrieron cuando trabajaban con PHP y las soluciones adecuadas.

Problema con la extensión dom-xml en XAMPP

La biblioteca cliente de PHP usa las clases DOMDocument para transformar las solicitudes y respuestas XML en objetos PHP. La extensión dom-xml puede causar problemas con el procesamiento de XML y generar transformaciones incorrectas. Algunos de nuestros desarrolladores descubrieron que, cuando se usa XAMPP, el constructor de DOMDocument se anula con una llamada a una 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 sobrescriba en tu archivo php.ini. Asegúrate de quitar las referencias a php_domxml.dll de tu 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 YouTube Data, es posible que debas cambiar el parámetro timeout en tu clase Zend_Http_Client. Esto se puede hacer fácilmente pasando un parámetro $config durante la creación de instancias, lo que establece el valor de timeout en algo distinto del valor 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 que se realicen conexiones HTTPS desde sus servidores.

Sabemos que algunos proveedores de hosting no permiten realizar conexiones https desde sus servidores predeterminados. Si recibes un mensaje de error similar al siguiente, es posible que debas realizar tus conexiones HTTPS a través de un proxy seguro:

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

Tu proveedor de hosting debe tener información sobre la dirección real del servidor proxy que se debe 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:

  • Se aclaró la configuración de PHP para servidores web trasladando a un apéndice las secciones que hacen referencia a PHP de línea de comandos.
  • Se agregó una nota sobre varios archivos de configuración php.ini.
  • Se agregaron secciones sobre cómo establecer de forma dinámica el include_path.
  • Se agregó una sección sobre la secuencia de comandos del verificador de instalación.
  • Se agregó un vínculo a las muestras en línea.
  • Se agregaron vínculos para XAMPP y MAMP.
  • Se agregó un apéndice de "Pistas y soluciones".