Aviso: esta página é sobre as APIs mais antigas do Google, as APIs de dados do Google. Relevante apenas para as APIs listadas no diretório das APIs de dados do Google, muitas delas foram substituídas por APIs mais recentes. Para mais informações sobre uma nova API específica, consulte a documentação da nova API. Para informações sobre autorização de solicitações com uma API mais recente, consulte Autenticação e autorização de Contas do Google.

Jochen Hartmann, equipe de APIs de dados do Google
Atualizado em outubro de 2008 (originalmente escrito por Daniel Holevoet)

• Introdução
• Pré-instalação
• Como instalar o PHP
  • No Windows
  • No Mac OS X
  • No Linux
• Como instalar a biblioteca de cliente PHP de dados do Google
• Como verificar se você pode acessar os arquivos da biblioteca de cliente
  • Como executar o verificador de instalação PHP
  • Como executar as amostras
• Saiba mais
• Apêndice A: como editar o caminho do PHP no arquivo de configuração php.ini
• Apêndice B: Como usar PHP na linha de comando
• Apêndice C: dicas e soluções
• Histórico de revisões

Introdução

A biblioteca de cliente PHP de dados do Google é uma coleção eficiente de classes que permitem interagir com as APIs de dados do Google. Ao contrário das nossas outras bibliotecas de cliente, ele é empacotado como parte do conhecido Zend Framework, mas também pode ser baixado separadamente. Assim como nossas outras bibliotecas de cliente, ele também é de código aberto e foi projetado para ser simples e eficiente, permitindo que você comece seus projetos rapidamente.

Pré-instalação

O PHP pode já estar instalado na máquina de desenvolvimento ou no servidor da Web. Portanto, a primeira etapa é verificar esse fato e garantir que a versão do PHP seja recente o suficiente para ser usada na biblioteca de cliente. A maneira mais fácil de verificar isso é colocar um novo arquivo em um diretório acessível pela Web no seu servidor. Digite as seguintes informações no arquivo:

<?php phpinfo(); ?>

Depois, verifique se ele pode ser acessado na Web. Para isso, defina as permissões apropriadas e navegue até o local correspondente no navegador. Se o PHP estiver instalado e o servidor puder renderizar páginas PHP, você verá algo semelhante à captura de tela abaixo:

A captura de tela mostra a página de informações do PHP. Esta página mostra a versão do PHP que foi instalada (neste caso, 5.2.6), quais extensões foram ativadas (na seção "Configurar comando") e a localização do arquivo de configuração interna do PHP (na seção "Arquivo de configuração carregado"). Se a página não for exibida ou se a sua versão do PHP for anterior à 5.1.4, será necessário instalar ou atualizar a sua versão do PHP. Caso contrário, pule a próxima seção e continue a instalação da biblioteca de cliente PHP.

Observação: se você tem acesso à linha de comando e planeja usar o PHP para executar scripts de linha de comando, consulte a seção de linha de comando PHP deste artigo.

Como instalar o PHP

A instalação varia um pouco de acordo com a plataforma, portanto, é importante seguir as instruções da sua plataforma durante a instalação. Antes de começar, vale ressaltar que pacotes pré-instalados que também incluem o servidor da Web Apache e o banco de dados MySQL, além do PHP, estão em alta. No Windows, Mac OS X e Linux, há o projeto XAMPP. Os usuários do Mac OS X também têm a opção de usar o projeto MAMP. Ambos os pacotes são compatíveis com o OpenSSL no PHP (necessário para interagir com feeds autenticados).

Se você instalar o PHP seguindo as etapas abaixo, instale e ative o suporte para o OpenSSL. Veja mais detalhes na seção OpenSSL do site PHP. As seções a seguir se concentram em como instalar o PHP por conta própria.

No Windows

A maneira mais fácil de instalar ou fazer upgrade do PHP no Windows é com o instalador do PHP disponível na página downloads do PHP.

1. Escolha a opção do instalador do PHP (na seção de binários do Windows) correspondente à versão mais recente do PHP e permita o download.
2. Abra o instalador e siga as instruções do assistente de instalação.
3. Quando o assistente solicitar, escolha o servidor da Web instalado no seu sistema para que ele configure para funcionar com PHP.
4. Verifique sua instalação seguindo as etapas descritas na seção acima.

No Mac OS X

O PHP está incluído no OS X, mas, antes de usá-lo, faça upgrade para a versão mais recente do PHP. Para fazer upgrade, você pode instalar qualquer um dos vários pacotes binários sem custo financeiro ou compilá-lo. Veja mais detalhes na página da documentação do PHP sobre a instalação no Mac OS X.

Após instalar ou configurar o OS X, siga as etapas descritas na seção de pré-instalação deste documento para verificar a instalação.

No Linux

Dependendo da distribuição do Linux, pode haver uma opção de configuração integrada ou fácil de usar para instalação em PHP. Por exemplo, no Ubuntu, é possível usar um gerenciador de pacotes ou simplesmente digitar o seguinte em um terminal:

sudo apt-get install php5

Se não houver uma instalação em pacote disponível na sua distribuição do Linux, instale a partir do código-fonte. Há instruções detalhadas sobre como compilar o PHP para o Apache 1.3 e compilar o PHP para o Apache 2 (links em inglês). O PHP.net também tem instruções para outros servidores.

Como instalar a biblioteca de cliente PHP de dados do Google

Agora que você tem uma versão em funcionamento do PHP instalada, é hora de instalar a biblioteca de cliente. A biblioteca de cliente faz parte do Zend Framework de código aberto, mas também é possível fazer o download dele como uma versão independente. Se você já tem uma versão do Zend Framework instalada (versão 1.6 ou mais recente), pode pular a instalação, porque a biblioteca de cliente de dados do Google está incluída. No entanto, recomendamos que você use a versão mais recente do framework para garantir que tenha os recursos e correções de bugs mais recentes disponíveis.

Fazer o download do framework completo dará a você acesso não apenas à biblioteca de cliente de dados do Google, mas também ao restante do framework. A própria biblioteca de cliente usa algumas outras classes que fazem parte da estrutura completa do Zend, mas não é necessário fazer o download de toda a estrutura porque as agrupamos no download autônomo.

1. Faça o download dos arquivos da biblioteca de cliente de dados do Google. Pesquise "APIs de dados do Google" nessa página.
2. Descompacte os arquivos transferidos por download. É necessário criar quatro subdiretórios:
   • demos: aplicativos de amostra
   • documentation: documentação dos arquivos da biblioteca de cliente
   • library: os arquivos de origem da biblioteca de cliente.
   • tests: arquivos de teste de unidade para testes automatizados.
3. Adicione o local da pasta library ao seu caminho PHP (consulte a próxima seção)

Verificar se você pode acessar os arquivos da biblioteca de cliente

A última etapa é verificar se você pode referenciar e incluir os arquivos da biblioteca de cliente do PHP no diretório em que está criando o projeto. Para isso, defina a variável include_path no arquivo de configuração do PHP (php.ini). A variável include_path contém vários locais do diretório que o PHP analisa ao emitir uma instrução require ou include que extrai classes, arquivos ou bibliotecas externas para o script atual, semelhante à instrução import no Java. É necessário anexar o local dos arquivos da biblioteca de cliente ao que já foi definido no include_path. Isso pode ser feito de duas maneiras (explicadas em detalhes abaixo):

• Defina permanentemente a diretiva include_path no arquivo de configuração php.ini na linha de comando. Exige acesso ao shell e permissões de gravação.
• Defina a variável de caminho include_path no nível "por diretório". Isso requer o servidor da Web Apache e a capacidade de criar arquivos .htaccess.
• Use a função set_include_path() para definir dinamicamente o caminho de inclusão nos seus scripts. Isso pode ser feito dinamicamente em cada um dos seus arquivos .php.

Se você tiver acesso ao shell e permissões de gravação no arquivo php.ini (ou se estiver escrevendo código em sua máquina local), basta seguir as instruções no apêndice A. Se você estiver usando o servidor da Web Apache e puder criar arquivos .htaccess, defina a variável include_path no nível "por diretório", o que significa que todos os arquivos no diretório em que você está trabalhando são automaticamente capazes de referenciar o diretório da biblioteca de cliente.

Você pode especificar opções de configuração de PHP conforme mostrado no snippet abaixo:

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

Observação:consulte o manual do PHP para ver mais informações sobre como mudar essas definições.

Se você não tiver acesso ao shell para seu servidor e não puder modificar ou criar arquivos .htaccess, use a função set_include_path. Talvez você já tenha um valor definido para o include_path. Portanto, é recomendável seguir o modelo abaixo para anexar os novos valores, em vez de substituir todo o caminho:

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

Observação:consulte as páginas do manual do PHP para mais detalhes sobre a função set_include_path.

Como executar o verificador de instalação PHP

Para verificar se o caminho de inclusão foi definido corretamente, execute o script Verificador de instalação do PHP. Basta copiar e colar o conteúdo desse arquivo em um novo arquivo em um diretório acessível na Web no seu servidor e navegar até ele no navegador. Se o resultado for semelhante ao exemplo abaixo, tudo está configurado corretamente e é possível usar a biblioteca de cliente PHP:

Se houver erros, como na captura de tela abaixo, siga a direção. Talvez você não tenha extensões ou o caminho ainda não esteja definido corretamente. Lembre-se de que talvez seja necessário reiniciar o servidor para que as alterações entrem em vigor. Isso só se aplica se você estiver realmente modificando o arquivo php.ini. A captura de tela abaixo mostra que o include_path está definido como /path/to/nowhere:

Observação:o verificador de instalação PHP verifica o seguinte: (1) as extensões PHP necessárias estão instaladas, (2) o ponto include_path está no diretório da biblioteca de cliente PHP, (3) pode fazer conexões SSL e, por último, pode fazer uma conexão com a API YouTube Data. Se um teste específico falhar, os demais não serão executados.

Agora que a biblioteca de cliente está instalada, tente executar as amostras.

Como executar as amostras

A raiz do diretório Zend/Gdata é uma pasta de demonstrações (exemplos para ajudar você a começar). Alguns desses exemplos foram projetados para serem executados na linha de comando, como demos/Zend/Gdata/Blogger.php e demos/Zend/Gdata/Spreadsheet-ClientLogin.php, e você pode executá-los com php /path/to/example. As amostras restantes podem ser executadas na linha de comando e em um navegador da Web. Se quiser visualizá-las em um navegador, coloque-as no diretório que usaria para exibir páginas da Web. Esses exemplos devem dar uma ideia básica de como criar e executar um aplicativo de dados do Google, mas quando você estiver pronto para mais, há outros recursos para o programador questionador.

Observação: se você quiser ver as demonstrações on-line na Web, acesse googlecodesamples.com e procure os aplicativos PHP.

Saiba mais

O melhor lugar para procurar informações sobre as classes que fazem parte da biblioteca de cliente é no Guia de referência de API (em inglês) no site do Zend Framework. Selecione o pacote Zend_Gdata no menu suspenso.

Você já deve estar pronto para começar a programar. Vamos criar ótimos aplicativos. Estamos ansiosos para ver seus resultados!

Você pode encontrar guias para desenvolvedores PHP para os seguintes serviços:

• Blogger
• Google Agenda
• Lista de documentos do Google
• API YouTube Data

Como a biblioteca de cliente PHP é um projeto de código aberto, a compatibilidade com mais APIs está sendo adicionada continuamente. Cada serviço tem o próprio grupo de suporte. Consulte nossa entrada de perguntas frequentes para ver uma lista dos grupos de suporte disponíveis.

Se você precisar de ajuda para resolver problemas nas suas chamadas de API, acesse os artigos sobre como depurar solicitações de API usando ferramentas de captura de tráfego de rede e como usar servidores proxy com as APIs de dados do Google. Veja também alguns artigos externos disponíveis sobre como instalar o XAMPP no Linux e como instalar o XAMPP no Windows. Além de todos esses artigos, confira as postagens sobre a biblioteca de cliente PHP no blog Dicas de API do Google Data.

Apêndice A: como editar o caminho do PHP no arquivo de configuração php.ini

O caminho do PHP é uma variável que contém uma lista de locais que o PHP pesquisa quando procura bibliotecas adicionais durante o carregamento. Para que o PHP possa carregar e acessar os arquivos da biblioteca de cliente PHP de dados do Google na sua máquina ou no servidor, eles precisam ser colocados em um local conhecido pelo PHP. Outra opção é anexar o local dos arquivos ao caminho do PHP. Normalmente, as mudanças no arquivo php.ini exigem uma reinicialização do servidor. É possível verificar o valor atual da variável include_path navegando até a página de informações do PHP discutida anteriormente. Procure a célula Arquivo de configuração carregado na primeira tabela e encontre o caminho na coluna à direita.

Observação:se você acha que está usando o php na linha de comando, talvez seja necessário modificar outra variável de caminho. Consulte o Apêndice B: como usar o PHP na linha de comando.

Depois de encontrar o arquivo php.ini, siga estas etapas para anexar ao caminho.

1. Abra o arquivo php.ini no seu editor de texto favorito.
2. Localize a linha que faz referência ao caminho PHP. Ela precisa começar com include_path.
3. Anexe o caminho que você armazenou ao Zend Framework à lista de locais já presentes, pré-pendente do novo caminho com o separador designado para seu SO (: em sistemas semelhantes a Unix, ; no Windows). Um caminho correto em sistemas semelhantes a Unix seria semelhante a este:

   /path1:/path2:/usr/local/lib/php/library

   No Windows, ele ficaria assim:

   \path1;\path2;\php\library

4. Salve e feche o arquivo.

Observação: no Mac OS X, o Finder não permite o acesso a arquivos que estão em locais do sistema, como o diretório /etc. Portanto, pode ser mais fácil fazer a edição usando um editor de linha de comando, como vi ou pico. Para isso, use um comando como: pico /path/to/php.ini.

Apêndice B: como usar PHP na linha de comando

A partir da versão 5 do PHP, há um utilitário de linha de comando disponível no PHP conhecido como CLI para "intérprete de linha de comando". O uso desse utilitário permite que scripts php sejam executados na linha de comando. As situações em que isso pode ser útil é se você está executando PHP na sua máquina e está procurando maneiras de testar rapidamente alguns scripts. No seu servidor, é claro, isso exigirá acesso ao shell. Observe que o PHP normalmente usa dois arquivos php.ini separados: um contém as opções de configuração do PHP em execução no servidor e outra, as configurações que o PHP usa ao ser executado na linha de comando. Se você tiver interesse em executar os aplicativos de demonstração da linha de comando da biblioteca de cliente, também será necessário modificar o arquivo de linha de comando php.ini.

Para localizá-lo, digite os seguintes comandos em sistemas do tipo Unix (Mac OS X, Linux, entre outros):

php -i | grep php.ini

Esse comando precisa exibir as seguintes informações no seu terminal:

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

Observação:é claro que os locais do caminho real (/etc/php...) podem ser diferentes no sistema.

Apêndice C: dicas e soluções

Esta seção contém um breve resumo de alguns dos problemas que os desenvolvedores descobriram ao trabalhar com o PHP e as soluções apropriadas.

Problema com a extensão dom-xml no XAMPP

A biblioteca de cliente PHP usa as classes DOMDocument para transformar solicitações e respostas XML em objetos PHP. A extensão dom-xml pode causar problemas no processamento de XML e resultar em transformações incorretas. Alguns dos nossos desenvolvedores descobriram que, ao usar o XAMPP, o construtor DOMDocument é substituído por uma chamada de função mais antiga, conforme explicado no site do PHP. Para corrigir esse problema, confira se o processamento de XML não foi substituído no arquivo php.ini. Remova as referências a php_domxml.dll do arquivo de configuração.

As solicitações atingem o tempo limite ao usar a biblioteca de cliente

Se você estiver usando a biblioteca de cliente para fazer solicitações razoavelmente grandes, como fazer upload de vídeos para a API YouTube Data, talvez seja necessário mudar o parâmetro timeout na classe Zend_Http_Client. Isso pode ser feito facilmente transmitindo um parâmetro $config durante a instanciação, que define o valor timeout para algo diferente do padrão 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);

Alguns provedores de hospedagem não permitem que conexões https sejam feitas nos próprios servidores

Alguns provedores de hospedagem não permitem que você faça conexões do https com os servidores padrão. Se você receber uma mensagem de erro semelhante a esta, talvez seja necessário estabelecer suas conexões https usando um proxy seguro:

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

Seu provedor de hospedagem precisa ter informações sobre o endereço real do servidor proxy. O snippet abaixo mostra como uma configuração de proxy personalizada pode ser usada com a biblioteca de 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");

}

Histórico de revisões

1o de outubro de 2008

Atualizado por Jochen Hartmann. Esta atualização contém as seguintes alterações:

• Simplificamos a configuração do PHP para servidores da Web ao mover as seções que se referem ao PHP de linha de comando para um apêndice.
• Adicionamos uma observação sobre vários arquivos de configuração do php.ini.
• Adicionamos seções sobre como definir dinamicamente o include_path.
• Adicionamos uma seção ao script do verificador de instalação.
• Adicionamos um link para amostras on-line.
• Foram adicionados links para XAMPP e MAMP.
• O apêndice de "Dicas e soluções" foi adicionado.