Introduzione alla libreria client PHP di Google Data

Avviso: questa pagina riguarda le API di Google più vecchie, le API di dati di Google; è pertinente solo per le API elencate nella directory delle API di dati di Google, molte delle quali sono state sostituite con API più recenti. Per informazioni su una nuova API specifica, consulta la documentazione della nuova API. Per informazioni sulle autorizzazioni per le richieste con un'API più recente, vedi Autenticazione e autorizzazione degli Account Google.

Video: guarda Trevor Johns mentre esegue l'installazione della libreria client, l'architettura della libreria e una procedura dettagliata del codice.

Jochen Hartmann, team delle API di dati di Google
Ultimo aggiornamento: ottobre 2008 (scritto originariamente da Daniel Holevoet)

• Introduzione
• Preinstallazione
• Installazione di PHP
  • Su Windows
  • Su Mac OS X
  • In Linux
• Installare la libreria client PHP dei dati di Google
• Verificare che tu possa accedere ai file della libreria client
  • Eseguire il programma di verifica delle installazioni di PHP
  • Esecuzione degli esempi
• Dove trovare ulteriori informazioni
• Appendice A: modifica del percorso PHP nel file di configurazione php.ini
• Appendice B: Utilizzo di PHP dalla riga di comando
• Appendice C: suggerimenti e soluzioni
• Cronologia delle revisioni

Introduzione

La libreria client PHP di Google Data è una raccolta efficace di corsi che ti consente di interagire con le API di dati di Google. A differenza delle nostre altre librerie client, è pacchettizzato come parte del popolare Zend Framework, ma può anche essere scaricato separatamente. Analogamente alle altre librerie client, è open source e progettata per essere semplice ed efficiente, consentendoti di iniziare rapidamente a lavorare i progetti.

Preinstallazione

PHP potrebbe essere già installato sulla tua macchina di sviluppo o sul tuo server web, quindi il primo passaggio consiste nel verificare tale fatto e assicurarti che la versione di PHP sia abbastanza recente da poter essere utilizzata per la libreria client. Il modo più semplice per verificarlo è inserire un nuovo file in una directory accessibile dal Web sul proprio server. Digita le seguenti informazioni nel file:

<?php phpinfo(); ?>

Quindi, assicurati che sia accessibile dal Web impostando le autorizzazioni appropriate e accedi alla sua posizione dal browser. Se PHP è installato e il tuo server è in grado di eseguire il rendering delle pagine PHP, dovresti vedere qualcosa di simile allo screenshot di seguito:

Lo screenshot mostra la pagina delle informazioni PHP. Questa pagina mostra la versione di PHP installata (in questo caso 5.2.6), insieme alle estensioni attivate (nella sezione 'Configure Command') e alla posizione del file di configurazione interna di PHP (nella sezione 'Loaded Configuration File'). Se la pagina non viene visualizzata o se la versione di PHP è precedente alla 5.1.4, dovrai installare o eseguire l'upgrade della versione di PHP. In caso contrario, puoi saltare la sezione successiva e continuare a installare la libreria client PHP.

Nota: se hai accesso alla riga di comando e prevedi di utilizzare PHP per eseguire gli script a riga di comando, consulta la sezione PHP della riga di comando di questo articolo.

Installazione di PHP

L'installazione varia leggermente in base alla piattaforma, quindi è importante seguire le istruzioni specifiche per la piattaforma in fase di installazione. Prima di approfondire l'argomento, vale la pena sottolineare che i pacchetti preinstallati che includono anche il server web Apache e il database MySQL insieme a PHP hanno acquisito popolarità. Per Windows, Mac OS X e Linux, è disponibile il progetto XAMPP. Gli utenti di Mac OS X possono anche scegliere di utilizzare il progetto MAMP. Entrambi i pacchetti supportano OpenSSL in PHP (obbligatorio per interagire con i feed autenticati).

Se installi PHP con i passaggi seguenti, assicurati di installare e abilitare anche il supporto per OpenSSL. Ulteriori dettagli in merito sono disponibili nella sezione OpenSSL del sito PHP. Le sezioni seguenti spiegano come installare PHP da solo.

Su Windows

Il modo più semplice per installare o eseguire l'upgrade di PHP su Windows è utilizzando il programma di installazione di PHP disponibile nella pagina relativa ai download di PHP.

1. Scegli il programma di installazione PHP (nella sezione Programmi binari di Windows) corrispondente alla versione più recente di PHP e consenti il download.
2. Apri il programma di installazione e segui le istruzioni della procedura guidata di installazione.
3. Quando la procedura guidata ti chiede, scegli il server web installato sul sistema in modo da configurarlo affinché funzioni con PHP.
4. Per verificare l'installazione, segui i passaggi descritti nella sezione precedente.

Su macOS X

PHP è incluso in OS X, ma prima di utilizzarlo devi eseguire l'upgrade all'ultima versione di PHP. Per eseguire l'upgrade, puoi installare uno qualsiasi dei numerosi pacchetti binari senza costi oppure compilarlo personalmente. Per maggiori dettagli, consulta la pagina della documentazione su PHP relativa all'installazione su Mac OS X.

Dopo aver installato o installato OS X, controlla l'installazione seguendo la procedura descritta nella sezione Preinstallazione di questo documento.

In Linux

A seconda della distribuzione di Linux, potrebbe essere disponibile un'opzione di configurazione integrata o facile da usare per l'installazione di PHP. Ad esempio, su Ubuntu puoi usare un gestore di pacchetti o digitare quanto segue in un terminale:

sudo apt-get install php5

Se non è disponibile un'installazione in pacchetto con la tua distribuzione Linux, devi eseguire l'installazione dal codice sorgente. Sono disponibili istruzioni dettagliate per la compilazione di PHP per Apache 1.3 e la compilazione di PHP per Apache 2. PHP.net contiene inoltre le istruzioni per altri server.

Installare la libreria client PHP dei dati di Google

Ora che hai installato una versione funzionante di PHP, è il momento di installare la libreria client. La libreria client fa parte del framework open source di Zend, ma può anche essere scaricata come versione autonoma. Se hai già installato una versione di Zend Framework (versione 1.6 o successiva), puoi saltare l'installazione perché la libreria dati di Google Data è inclusa. Tuttavia, se utilizzi la versione più recente del framework, avrai la certezza di disporre di tutte le ultime funzionalità e correzioni di bug disponibili, quindi è solitamente consigliato.

Il download del framework completo ti consentirà di accedere non solo alla libreria client di dati di Google, ma anche al resto del framework. La libreria client utilizza alcune altre classi che fanno parte del framework Zend completo, ma non è necessario scaricare l'intero framework perché è incluso nel download autonomo.

1. Scarica i file della libreria client di dati di Google. (cerca "API di dati di Google" nella pagina).
2. Decomprimi i file scaricati. È necessario creare quattro sottodirectory:
   • demos: applicazioni di esempio
   • documentation: documentazione sui file della libreria client
   • library: i file di origine della libreria client effettivi.
   • tests: file per il test delle unità per i test automatici.
3. Aggiungi il percorso della cartella library al tuo percorso PHP (vedi la sezione successiva)

Verifica di poter accedere ai file della libreria client

Nell'ultimo passaggio devi assicurarti di poter fare riferimento e includere i file della libreria client PHP dalla directory in cui stai creando il progetto. Ciò si ottiene impostando la variabile include_path nel file di configurazione di PHP (php.ini). La variabile include_path contiene un numero di posizioni di directory che PHP esamina quando emetti un'istruzione require o include che estrae classi, librerie o file esterni dallo script corrente, in modo simile all'istruzione import in Java. Devi aggiungere la posizione dei file della libreria client a ciò che è già stato impostato in include_path. Puoi farlo in due modi (illustrati dettagliatamente di seguito):

• Imposta in modo permanente l'istruzione include_path nel file di configurazione php.ini dalla riga di comando. Richiede l'accesso alla shell e le autorizzazioni di scrittura.
• Imposta la variabile di percorso include_path a livello di "per directory": richiede il server web Apache e la possibilità di creare file .htaccess.
• Utilizza la funzione set_include_path() per impostare in modo dinamico il percorso di inclusione negli script e puoi impostarla in modo dinamico in ogni file .php.

Se disponi dell'accesso alla shell e delle autorizzazioni di scrittura per il file php.ini (o se stai scrivendo codice sulla tua macchina locale), segui semplicemente le istruzioni riportate nell'Appendice A. Se utilizzi il server web Apache e hai la possibilità di creare file .htaccess, puoi impostare la variabile include_path a livello di "per directory", in modo che tutti i file nella directory su cui lavori possano fare riferimento automaticamente alla directory della libreria client.

Puoi specificare le opzioni di configurazione PHP come mostrato nello snippet di seguito:

# 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 il manuale PHP per ulteriori informazioni sulla modifica delle impostazioni di configurazione.

Se non hai accesso alla shell al tuo server e non puoi modificare o creare file .htaccess, puoi sempre utilizzare la funzione set_include_path. Tieni presente che potresti avere già impostato un valore per il tuo include_path, quindi è consigliabile seguire il modello riportato di seguito per aggiungere i nuovi valori, anziché sovrascrivere l'intero percorso:

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

Nota: consulta le pagine manuali PHP per ulteriori dettagli sulla funzione set_include_path.

Esecuzione del programma di verifica delle installazioni di PHP

Per verificare che il percorso di inclusione sia stato impostato correttamente, puoi eseguire lo script Controllo installazione di PHP. Copia e incolla il contenuto di quel file in un nuovo file in una directory accessibile dal Web sul tuo server e aprilo dal browser. Se visualizzi un output simile al seguente, tutto è stato configurato correttamente e ora puoi utilizzare la libreria client PHP:

Se visualizzi errori (come nello screenshot di seguito), assicurati di seguire le istruzioni. È possibile che manchino delle estensioni oppure che il percorso non sia stato impostato correttamente. Ricorda che potrebbe essere necessario riavviare il server affinché le modifiche vengano applicate. Questo vale solo se stai effettivamente modificando il file php.ini. Il seguente screenshot mostra che include_path è impostato su /path/to/nowhere:

Nota: tieni presente che lo strumento di controllo dell'installazione di PHP controlla quanto segue di seguito: (1) le estensioni PHP richieste sono installate, (2) il punto include_path rimanda alla directory della libreria client PHP, (3) è possibile effettuare connessioni SSL e, infine, puoi stabilire una connessione all'API di dati di YouTube. Se un test specifico non va a buon fine, i test rimanenti non vengono eseguiti.

Ora che la libreria client è installata, è il momento di provare a eseguire gli esempi.

Esecuzione degli esempi

Nella directory principale di Zend/Gdata c'è una cartella di demo, degli esempi che ti aiuteranno a iniziare. Alcuni di questi esempi sono progettati per essere eseguiti dalla riga di comando come demos/Zend/Gdata/Blogger.php e demos/Zend/Gdata/Spreadsheet-ClientLogin.php e puoi eseguirli con php /path/to/example. Gli esempi rimanenti possono essere eseguiti sia dalla riga di comando che da un browser web. Se vuoi visualizzarle in un browser, queste devono essere inserite in qualsiasi directory che useresti per pubblicare pagine web. Questi esempi dovrebbero dare un'idea di base di come scrivere ed eseguire un'applicazione di dati di Google, ma quando vuoi saperne di più, ci sono altre risorse per il programmatore curioso.

Nota: se ti interessa vedere le demo basate sul Web online, visita googlecodesamples.com e cerca le applicazioni PHP.

Dove approfondire

Il posto migliore per cercare informazioni sui corsi che fanno parte della libreria client è la guida di riferimento API sul sito Zend Framework. Assicurati di selezionare il pacchetto Zend_Gdata dal menu a discesa.

A questo punto, è tutto pronto per iniziare la programmazione. Quindi, continua a scrivere alcune fantastiche applicazioni. Non vediamo l'ora di vedere i tuoi risultati.

Puoi trovare le guide per gli sviluppatori PHP per i seguenti servizi:

• Blogger
• Google Calendar
• Elenco di documenti Google
• API di dati di YouTube

Poiché la libreria client PHP è un progetto open source, viene aggiunto il supporto per altre API. Per ogni servizio è associato un gruppo di assistenza specifico. Per visualizzare l'elenco dei gruppi di assistenza disponibili, consulta le Domande frequenti (FAQ) disponibili.

Se hai bisogno di aiuto per risolvere i problemi delle chiamate API, consulta gli articoli sul debug delle richieste API utilizzando gli strumenti di acquisizione del traffico di rete e sull'utilizzo dei server proxy con le API di dati di Google. Sono inoltre disponibili alcuni articoli esterni sull'installazione di XAMPP su Linux e sull'installazione di XAMPP su Windows. Oltre a tutti questi articoli, assicurati di consultare i post relativi alla libreria client PHP nel blog di suggerimenti sull'API di dati di Google.

Appendice A: modifica del percorso PHP nel file di configurazione php.ini

Il percorso PHP è una variabile che contiene un elenco di località che PHP cerca quando cerca altre librerie durante il caricamento. Per poter caricare e accedere ai file della libreria client PHP di Google Data sul tuo computer o server, PHP dovrà essere collocato in una posizione nota a PHP. In alternativa, la posizione dei file deve essere aggiunta al percorso PHP. Tieni presente che le modifiche al file php.ini richiedono in genere un riavvio del server. Puoi sempre verificare il valore corrente della variabile include_path accedendo alla pagina delle informazioni PHP esaminata in precedenza. Cerca la cella Loaded Configuration File (File di configurazione caricato) nella prima tabella e trova il percorso nella colonna a destra.

Nota: se noti che stai utilizzando php dalla riga di comando, potresti dover modificare una variabile di percorso aggiuntiva. Assicurati di consultare Appendice B: utilizzo di PHP dalla riga di comando.

Una volta individuato il file php.ini, segui questi passaggi per aggiungerlo al percorso.

1. Apri il file php.ini nell'editor di testo che preferisci.
2. Individua la riga che fa riferimento al percorso PHP, deve iniziare con include_path.
3. Aggiungi il percorso in cui hai archiviato Zend Framework all'elenco di località già presenti, prima di creare il nuovo percorso con il separatore designato per il sistema operativo (: su sistemi Unix, ; su Windows). Il percorso corretto sui sistemi Unix sarà simile a questo:

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

   Su Windows, avrebbe un aspetto simile a questo:

   \path1;\path2;\php\library

4. Salva e chiudi il file.

Nota: su Mac OS X, il Finder non consente l'accesso ai file che si trovano in posizioni di sistema, come la directory /etc. Pertanto, potrebbe essere più semplice modificarle utilizzando un editor a riga di comando come vi o pico. Per farlo, utilizza un comando come: pico /path/to/php.ini.

Appendice B: utilizzo di PHP dalla riga di comando

A partire dalla versione 5 di PHP, è disponibile un'utilità a riga di comando in PHP che è nota come interfaccia a riga di comando per "Interprete di riga di comando". L'utilizzo di questa utilità consente di eseguire gli script php dalla riga di comando. La situazione può essere utile se stai eseguendo PHP in locale sulla tua macchina e stai cercando un modo per testare rapidamente alcuni script. Sul server, ovviamente, sarà necessario l'accesso alla shell. Una cosa importante da notare è che PHP utilizza in genere due file php.ini separati, uno contiene le opzioni di configurazione per PHP in esecuzione sul tuo server e un altro per le configurazioni che PHP utilizza durante l'esecuzione dalla riga di comando. Se ti interessa eseguire le applicazioni demo della riga di comando dalla libreria client, dovrai modificare anche il file php.ini della riga di comando.

Per individuare il codice, digita i seguenti comandi sui sistemi Unix (Mac OS X, Linux e altri):

php -i | grep php.ini

Il comando in questione dovrebbe restituire le seguenti informazioni nel terminale:

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

Nota: ovviamente le posizioni effettive del percorso (/etc/php...) possono variare nel tuo sistema.

Appendice C: suggerimenti e soluzioni

Questa sezione contiene una breve panoramica di alcuni problemi rilevati dagli sviluppatori durante l'utilizzo di PHP e delle soluzioni appropriate.

Problema con l'estensione dom-xml in XAMPP

La libreria client PHP utilizza le classi DOMDocument per trasformare le richieste e le risposte XML in oggetti PHP. L'estensione dom-xml può causare problemi di gestione di XML e comportare trasformazioni non corrette. Alcuni dei nostri sviluppatori hanno scoperto che quando si utilizza XAMPP, il costruttore DOMDocument viene sostituito con una chiamata funzione precedente, come spiegato sul sito PHP. Per risolvere questo problema, assicurati che la gestione XML non sia sovrascritta nel file php.ini. Assicurati di rimuovere i riferimenti a php_domxml.dll dal file di configurazione.

Le richieste sono in timeout quando si utilizza la libreria client

Se utilizzi la libreria client per eseguire richieste abbastanza grandi, ad esempio per caricare video nell'API di dati di YouTube, potresti dover modificare il parametro timeout nella classe Zend_Http_Client. Puoi farlo facilmente trasmettendo un parametro $config durante l'istanza, che imposta il valore timeout su un valore diverso da quello predefinito di 10 secondi:

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

Alcuni provider host non consentono di effettuare connessioni https dai propri server

Alcuni provider host non consentono di stabilire connessioni https dai propri server predefiniti. Se viene visualizzato un messaggio di errore simile al seguente, potresti dover effettuare le connessioni https tramite un proxy sicuro:

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

Il tuo provider host deve avere informazioni sull'indirizzo effettivo del server proxy da utilizzare. Lo snippet di seguito illustra come utilizzare una configurazione proxy personalizzata con la libreria client 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 = '[e-mail]';
$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");

}

Cronologia revisioni

1 ottobre 2008

Aggiornato da Jochen Hartmann. Questo aggiornamento contiene le seguenti modifiche:

• È stata resa più chiara la configurazione di PHP per i server web spostando le sezioni che fanno riferimento a PHP della riga di comando in un'appendice.
• È stata aggiunta una nota su più file di configurazione php.ini.
• Sono state aggiunte delle sezioni su come impostare dinamicamente include_path.
• È stata aggiunta una sezione sullo script di controllo dell'installazione.
• Link aggiunto a esempi online.
• Sono stati aggiunti link per XAMPP e MAMP.
• È stata aggiunta un'appendice "Suggerimenti e soluzioni".