Pierwsze kroki z biblioteką klienta Google Data w PHP

Ostrzeżenie: ta strona dotyczy starszych interfejsów API Google, czyli interfejsów Google Data API. Jest ona istotna tylko w przypadku interfejsów API wymienionych w katalogu interfejsów Google Data API, z których wiele zostało zastąpionych nowszymi interfejsami API. Informacje o konkretnym nowym interfejsie API znajdziesz w jego dokumentacji. Informacje o autoryzowaniu żądań za pomocą nowszego interfejsu API znajdziesz w artykule Uwierzytelnianie i autoryzacja kont Google.

Film: obejrzyj film, w którym Trevor Johns omawia instalację biblioteki klienta, jej architekturę i kod.

Jochen Hartmann, zespół interfejsów Google Data API
Zaktualizowano w październiku 2008 r. (pierwotnie napisane przez Daniela Holevoeta)

Wprowadzenie

Google Data PHP Client Library to zaawansowany zbiór klas, które umożliwiają interakcję z interfejsami Google Data API. W przeciwieństwie do innych bibliotek klienta jest ona częścią popularnego Zend Framework, ale można ją też pobrać osobno. Podobnie jak inne nasze biblioteki klienta jest ona dostępna na licencji open source i została zaprojektowana tak, aby była prosta i wydajna, co pozwala szybko rozpocząć pracę nad projektami.

Przed instalacją

PHP może być już zainstalowany na komputerze deweloperskim lub serwerze WWW, więc pierwszym krokiem jest sprawdzenie tego faktu i upewnienie się, że wersja PHP jest wystarczająco nowa, aby można było jej używać w bibliotece klienta. Najprostszym sposobem sprawdzenia jest umieszczenie nowego pliku w katalogu dostępnym w internecie na serwerze. Wpisz w pliku te informacje:

<?php phpinfo(); ?>

Następnie sprawdź, czy jest dostępny w internecie, ustawiając odpowiednie uprawnienia, i przejdź do jego lokalizacji w przeglądarce. Jeśli język PHP jest zainstalowany, a serwer może renderować strony PHP, zobaczysz coś podobnego do tego, co widać na zrzucie ekranu poniżej:

Zrzut ekranu strony z informacjami o PHP

Zrzut ekranu przedstawiający stronę z informacjami o PHP. Na tej stronie zobaczysz zainstalowaną wersję PHP (w tym przypadku 5.2.6), włączone rozszerzenia (w sekcji „Configure Command”) oraz lokalizację wewnętrznego pliku konfiguracyjnego PHP (w sekcji „Loaded Configuration File”). Jeśli strona się nie wyświetla lub Twoja wersja PHP jest starsza niż 5.1.4, musisz zainstalować lub zaktualizować PHP. W przeciwnym razie możesz pominąć następną sekcję i przejść do instalowania biblioteki klienta PHP.

Uwaga: jeśli masz dostęp do wiersza poleceń i planujesz używać PHP do uruchamiania skryptów wiersza poleceń, zapoznaj się z sekcją dotyczącą PHP w wierszu poleceń w tym artykule.

Instalowanie PHP

Instalacja różni się nieco w zależności od platformy, dlatego podczas instalacji ważne jest, aby postępować zgodnie z instrukcjami dla konkretnej platformy. Zanim zaczniemy, warto zauważyć, że popularność zyskały preinstalowane pakiety, które oprócz PHP zawierają też serwer WWW Apache i bazę danych MySQL. W przypadku systemów Windows, Mac OS X i Linux dostępny jest projekt XAMPP. Użytkownicy systemu Mac OS X mogą też korzystać z projektu MAMP. Oba te pakiety obsługują OpenSSL w PHP (który jest wymagany do interakcji z uwierzytelnionymi plikami danych).

Jeśli instalujesz PHP, wykonując czynności opisane poniżej, pamiętaj, aby zainstalować i włączyć obsługę OpenSSL. Więcej informacji na ten temat znajdziesz w sekcji OpenSSL na stronie PHP. W kolejnych sekcjach opisujemy, jak zainstalować sam język PHP.

W systemie Windows

Najłatwiejszym sposobem zainstalowania lub uaktualnienia PHP w systemie Windows jest użycie instalatora PHP dostępnego na stronie pobrań PHP.

  1. Wybierz opcję instalatora PHP (w sekcji plików binarnych dla systemu Windows) odpowiadającą najnowszej wersji PHP i pozwól na pobranie.
  2. Otwórz instalator i postępuj zgodnie z instrukcjami kreatora instalacji.
  3. Gdy kreator wyświetli odpowiedni monit, wybierz serwer WWW zainstalowany w systemie, aby skonfigurować go do pracy z PHP.
  4. Sprawdź instalację, wykonując czynności opisane w sekcji powyżej.

Mac OS X

PHP jest częścią systemu OS X, ale przed użyciem należy zaktualizować go do najnowszej wersji. Aby uaktualnić oprogramowanie, możesz zainstalować jeden z kilku bezpłatnych pakietów binarnych lub skompilować go samodzielnie. Szczegółowe informacje znajdziesz na stronie dokumentacji PHP dotyczącej instalacji w systemie Mac OS X.

Po zainstalowaniu lub skonfigurowaniu systemu OS X sprawdź instalację, wykonując czynności opisane w sekcji przed instalacją tego dokumentu.

W Linuksie:

W zależności od dystrybucji systemu Linux może być dostępna wbudowana lub łatwa w użyciu opcja konfiguracji instalacji PHP. Na przykład w Ubuntu możesz użyć systemu zarządzania pakietami lub po prostu wpisać w terminalu to polecenie:

sudo apt-get install php5

Jeśli w dystrybucji systemu Linux nie ma pakietu instalacyjnego, musisz zainstalować program z kodu źródłowego. Szczegółowe instrukcje kompilowania PHP dla Apache 1.3 i kompilowania PHP dla Apache 2. Na stronie PHP.net znajdziesz też instrukcje dotyczące innych serwerów.

Instalowanie biblioteki klienta Google Data PHP

Po zainstalowaniu działającej wersji PHP możesz zainstalować bibliotekę klienta. Biblioteka klienta jest częścią platformy Zend Framework o otwartym kodzie źródłowym, ale można ją też pobrać jako samodzielną wersję. Jeśli masz już zainstalowaną wersję Zend Framework (1.6 lub nowszą), możesz pominąć instalację, ponieważ biblioteka klienta Google Data jest już w niej zawarta. Używanie najnowszej wersji platformy gwarantuje jednak dostęp do wszystkich najnowszych funkcji i poprawek błędów, dlatego jest zwykle zalecane.

Pobranie całego frameworka zapewni Ci dostęp nie tylko do biblioteki klienta danych Google, ale też do pozostałych elementów frameworka. Biblioteka klienta korzysta z kilku innych klas, które są częścią pełnej wersji Zend Framework, ale nie musisz pobierać całego frameworka, ponieważ dołączyliśmy je do samodzielnego pakietu do pobrania.

  1. Pobierz pliki biblioteki klienta danych Google. (Na tej stronie wyszukaj „Google Data APIs”).
  2. Rozpakuj pobrane pliki. Należy utworzyć 4 podkatalogi:
    • demos – przykładowe aplikacje;
    • documentation – dokumentacja plików biblioteki klienta.
    • library – rzeczywiste pliki źródłowe biblioteki klienta.
    • tests – pliki testów jednostkowych na potrzeby testowania automatycznego.
  3. Dodaj lokalizację folderu library do ścieżki PHP (zobacz następną sekcję).

Sprawdzanie, czy masz dostęp do plików biblioteki klienta

Ostatnim krokiem jest upewnienie się, że możesz odwoływać się do plików biblioteki klienta PHP i uwzględniać je w katalogu, w którym tworzysz projekt. Można to zrobić, ustawiając zmienną include_path w pliku konfiguracyjnym PHP (php.ini). Zmienna include_path zawiera liczbę lokalizacji katalogów, które PHP sprawdza, gdy wydajesz instrukcję require lub include, która pobiera zewnętrzne klasy, biblioteki lub pliki do bieżącego skryptu, podobnie jak instrukcja import w języku Java. Musisz dodać lokalizację plików biblioteki klienta do tego, co zostało już ustawione w include_path. Można to zrobić na 2 sposoby (oba są szczegółowo opisane poniżej):

  • Trwale ustaw dyrektywę include_path w pliku konfiguracyjnym php.ini z poziomu wiersza poleceń – wymaga dostępu do powłoki i uprawnień do zapisu.
  • Ustaw zmienną ścieżki include_path na poziomie „każdego katalogu” – wymaga serwera WWW Apache i możliwości tworzenia plików .htaccess.
  • Użyj funkcji set_include_path(), aby dynamicznie ustawić ścieżkę dołączania w skryptach. Możesz ją ustawiać dynamicznie w każdym pliku .php.

Jeśli masz dostęp do powłoki i uprawnienia do zapisu w pliku php.ini (lub jeśli piszesz kod na komputerze lokalnym), postępuj zgodnie z instrukcjami w dodatku A. Jeśli używasz serwera WWW Apache i możesz tworzyć pliki .htaccess, możesz ustawić zmienną include_path na poziomie „każdego katalogu”. Oznacza to, że wszystkie pliki w katalogu, w którym pracujesz, mogą automatycznie odwoływać się do katalogu biblioteki klienta.

Opcje konfiguracji PHP możesz określić tak jak w tym przykładzie:

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

Uwaga: więcej informacji o zmianie ustawień konfiguracji znajdziesz w podręczniku PHP.

Jeśli nie masz dostępu do powłoki serwera i nie możesz modyfikować ani tworzyć plików .htaccess, zawsze możesz użyć funkcji set_include_path. Pamiętaj, że w przypadku parametru include_path może być już ustawiona jakaś wartość, dlatego warto postępować zgodnie z poniższym modelem, aby dołączyć nowe wartości zamiast zastępować całą ścieżkę:

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

Uwaga: więcej informacji o funkcji set_include_path znajdziesz na stronach podręcznika PHP.

Uruchamianie narzędzia do sprawdzania instalacji PHP

Aby sprawdzić, czy ścieżka dołączania została prawidłowo skonfigurowana, możesz uruchomić skrypt Installation Checker w PHP. Po prostu skopiuj i wklej zawartość tego pliku do nowego pliku w katalogu dostępnym w internecie na serwerze i otwórz go w przeglądarce. Jeśli zobaczysz dane wyjściowe podobne do poniższych, oznacza to, że wszystko zostało prawidłowo skonfigurowane i możesz używać biblioteki klienta PHP:

zrzut ekranu z wynikami narzędzia do sprawdzania instalacji PHP

Jeśli zobaczysz błędy (jak na zrzucie ekranu poniżej), postępuj zgodnie z instrukcjami. Może brakować rozszerzeń lub ścieżka może być nadal nieprawidłowo ustawiona. Pamiętaj, że aby zmiany zaczęły obowiązywać, może być konieczne ponowne uruchomienie serwera. Ma to zastosowanie tylko wtedy, gdy faktycznie modyfikujesz plik php.ini. Na zrzucie ekranu poniżej widać, że ustawienie include_path ma wartość /path/to/nowhere:

zrzut ekranu z wynikami narzędzia do sprawdzania instalacji PHP

Uwaga: narzędzie do sprawdzania instalacji PHP sprawdza kolejno: (1) czy wymagane rozszerzenia PHP są zainstalowane, (2) czy include_path wskazuje katalog biblioteki klienta PHP, (3) czy można nawiązać połączenia SSL i (4) czy można nawiązać połączenie z interfejsem YouTube Data API. Jeśli określony test zakończy się niepowodzeniem, pozostałe testy nie zostaną uruchomione.

Po zainstalowaniu biblioteki klienta możesz uruchomić przykłady.

Uruchamianie przykładów

W katalogu głównym Zend/Gdata znajduje się folder z wersjami demonstracyjnymi – przykładami, które pomogą Ci zacząć. Niektóre z tych przykładów są przeznaczone do uruchamiania z wiersza poleceń, np. demos/Zend/Gdata/Blogger.php i demos/Zend/Gdata/Spreadsheet-ClientLogin.php, i możesz je wykonywać za pomocą polecenia php /path/to/example. Pozostałe przykłady można uruchamiać zarówno z wiersza poleceń, jak i w przeglądarce. Jeśli chcesz wyświetlać je w przeglądarce, umieść je w dowolnym katalogu, z którego korzystasz do wyświetlania stron internetowych. Te przykłady powinny dać podstawowe pojęcie o tym, jak pisać i uruchamiać aplikacje Google Data. Jeśli jednak chcesz dowiedzieć się więcej, możesz skorzystać z innych materiałów dla ciekawych programistów.

Uwaga: jeśli chcesz zobaczyć wersje demonstracyjne online, wejdź na googlecodesamples.com i poszukaj aplikacji PHP.

Więcej informacji

Najlepszym miejscem do szukania informacji o klasach wchodzących w skład biblioteki klienta jest przewodnik po interfejsie API na stronie Zend Framework. Z menu wybierz pakiet Zend_Gdata.

Możesz już zacząć kodować. Napisz więc świetne aplikacje. Nie możemy się doczekać, aby zobaczyć Twoje wyniki.

Przewodniki dla programistów PHP znajdziesz w przypadku tych usług:

Biblioteka klienta PHP jest projektem typu open source, dlatego stale dodawana jest obsługa kolejnych interfejsów API. Każda usługa ma własną grupę pomocy. Listę dostępnych grup pomocy znajdziesz w tym artykule z odpowiedziami na najczęstsze pytania.

Jeśli potrzebujesz pomocy w rozwiązywaniu problemów z wywołaniami interfejsu API, przeczytaj artykuły na temat debugowania żądań interfejsu API za pomocą narzędzi do przechwytywania ruchu w sieci i korzystania z serwerów proxy z interfejsami Google Data API. Dostępnych jest też kilka artykułów zewnętrznych na temat instalowania XAMPP w systemie Linux i instalowania XAMPP w systemie Windows. Oprócz tych wszystkich artykułów zapoznaj się z postami na temat biblioteki klienta PHP na blogu z poradami dotyczącymi interfejsu Google Data API.

Dodatek A. Edytowanie ścieżki PHP w pliku konfiguracji php.ini

Ścieżka PHP to zmienna zawierająca listę lokalizacji, w których PHP szuka dodatkowych bibliotek podczas wczytywania. Aby PHP mógł wczytywać pliki biblioteki klienta PHP Google Data i uzyskiwać do nich dostęp na Twoim komputerze lub serwerze, musisz umieścić je w lokalizacji, którą PHP rozpoznaje. Możesz też dodać lokalizację plików do ścieżki PHP. Pamiętaj, że zmiany w pliku php.ini zwykle wymagają ponownego uruchomienia serwera. Aktualną wartość zmiennej include_path możesz zawsze sprawdzić na stronie informacji o PHP, o której pisaliśmy wcześniej. W pierwszej tabeli znajdź komórkę Loaded Configuration File (Załadowany plik konfiguracji) i odszukaj ścieżkę w kolumnie po prawej stronie.

Uwaga: jeśli okaże się, że używasz PHP z wiersza poleceń, może być konieczne zmodyfikowanie dodatkowej zmiennej ścieżki. Zapoznaj się z Dodatkiem B: Używanie PHP w wierszu poleceń.

Po znalezieniu pliku php.ini wykonaj te czynności, aby dodać go do ścieżki.

  1. Otwórz plik php.ini w ulubionym edytorze tekstu.
  2. Znajdź wiersz odwołujący się do ścieżki PHP. Powinien zaczynać się od include_path.
  3. Dołącz ścieżkę, w której został zapisany Zend Framework, do listy już istniejących lokalizacji, dodając na początku nowej ścieżki wyznaczony separator dla Twojego systemu operacyjnego (: w systemach podobnych do Uniksa, ; w systemie Windows). Prawidłowa ścieżka w systemach typu Unix wyglądałaby tak: 
    /path1:/path2:/usr/local/lib/php/library
     W systemie Windows będzie to wyglądać mniej więcej tak: 
    \path1;\path2;\php\library
  4. Zapisz i zamknij plik.

Uwaga: w systemie Mac OS X Finder nie zezwala na dostęp do plików znajdujących się w lokalizacjach systemowych, takich jak katalog /etc. Dlatego najłatwiej będzie je edytować za pomocą edytora wiersza poleceń, takiego jak vi lub pico. Aby to zrobić, użyj polecenia, np. pico /path/to/php.ini.

Dodatek B. Używanie PHP w wierszu poleceń

Od wersji 5 PHP udostępnia narzędzie wiersza poleceń, które jest nazywane CLI (command line interpreter). Użycie tego narzędzia umożliwia uruchamianie skryptów PHP z poziomu wiersza poleceń. Może to być przydatne, jeśli używasz PHP lokalnie na swoim komputerze i szukasz sposobów na szybkie przetestowanie niektórych skryptów. Na serwerze wymaga to oczywiście dostępu do powłoki. Warto pamiętać, że PHP zwykle używa 2 osobnych plików php.ini. Jeden zawiera opcje konfiguracji PHP działającego na serwerze, a drugi – konfiguracje używane przez PHP podczas uruchamiania z wiersza poleceń. Jeśli chcesz uruchamiać aplikacje demonstracyjne wiersza poleceń z biblioteki klienta, musisz też zmodyfikować plik wiersza poleceń php.ini.

Aby go znaleźć, wpisz te polecenia w systemach typu Unix (Mac OS X, Linux i inne):

php -i | grep php.ini

To polecenie powinno spowodować wyświetlenie w terminalu tych informacji:

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

Uwaga: rzeczywiste lokalizacje ścieżek (/etc/php...) mogą się różnić w zależności od systemu.

Dodatek C: wskazówki i rozwiązania

W tej sekcji znajdziesz krótki opis niektórych problemów, które deweloperzy napotkali podczas pracy z PHP, oraz odpowiednie rozwiązania.

Problem z rozszerzeniem dom-xml w XAMPP

Biblioteka klienta PHP używa klas DOMDocument do przekształcania żądań i odpowiedzi XML w obiekty PHP. Rozszerzenie dom-xml może powodować problemy z obsługą XML i skutkować nieprawidłowymi przekształceniami. Niektórzy deweloperzy zauważyli, że podczas korzystania z XAMPP konstruktor DOMDocument jest zastępowany starszym wywołaniem funkcji, co zostało wyjaśnione na stronie PHP. Aby rozwiązać ten problem, upewnij się, że obsługa XML nie jest zastępowana w pliku php.ini. Pamiętaj, aby usunąć odwołania do php_domxml.dll z pliku konfiguracji.

Żądania przekraczają limit czasu podczas korzystania z biblioteki klienta

Jeśli używasz biblioteki klienta do wykonywania dość dużych żądań, np. przesyłania filmów do interfejsu YouTube Data API, może być konieczna zmiana parametru timeout w klasie Zend_Http_Client. Możesz to łatwo zrobić, przekazując parametr $config podczas tworzenia instancji, co spowoduje ustawienie wartości timeout na inną niż domyślna wartość 10 sekund:

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

Niektórzy dostawcy usług hostingowych nie zezwalają na połączenia HTTPS z ich serwerów.

Wiemy, że niektórzy dostawcy usług hostingowych nie zezwalają na połączenia https z ich domyślnych serwerów. Jeśli pojawi się komunikat o błędzie podobny do poniższego, może być konieczne nawiązywanie połączeń https przez bezpieczny serwer proxy:

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

Dostawca hostingu powinien mieć informacje o rzeczywistym adresie serwera proxy, którego należy użyć. Poniższy fragment kodu pokazuje, jak można używać niestandardowej konfiguracji serwera proxy z biblioteką klienta 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");

}

Historia zmian

1 października 2008 r.

Zaktualizowano przez Jochena Hartmana. Ta aktualizacja zawiera następujące zmiany:

  • Ulepszyliśmy konfigurację PHP dla serwerów WWW, przenosząc sekcje dotyczące PHP w wierszu poleceń do załącznika.
  • Dodano notatkę o wielu plikach konfiguracji php.ini.
  • Dodano sekcje dotyczące dynamicznego ustawiania ścieżki include_path.
  • Dodaliśmy sekcję dotyczącą skryptu sprawdzającego instalację.
  • Dodano link do próbek online.
  • Dodano linki do XAMPP i MAMP.
  • Dodano dodatek „Wskazówki i rozwiązania”.