תחילת העבודה עם ספריית הלקוח של Google Data PHP

אזהרה: הדף הזה עוסק בממשקי API ישנים יותר של Google, ממשקי Google Data API. הוא רלוונטי רק לממשקי ה-API שרשומים בספריית Google Data API, שרבים מהם הוחלפו בממשקי API חדשים יותר. מידע על API חדש ספציפי מופיע במסמכי התיעוד של ה-API החדש. למידע על הרשאת בקשות באמצעות API חדש יותר, אפשר לעיין במאמר אימות והרשאה של חשבונות Google.

סרטון: טרבור ג'ונס מסביר על התקנת ספריית לקוח, על ארכיטקטורת הספרייה ועל קוד.

יוכן הרטמן, צוות Google Data APIs
עודכן באוקטובר 2008 (נכתב במקור על ידי דניאל הולבוט)

מבוא

ספריית הלקוח של Google Data PHP היא אוסף רב עוצמה של מחלקות שמאפשרות לכם ליצור אינטראקציה עם Google Data APIs. בניגוד לספריות לקוח אחרות שלנו, היא נארזת כחלק מ-Zend Framework הפופולרי, אבל אפשר גם להוריד אותה בנפרד. בדומה לספריות לקוח אחרות שלנו, גם היא מבוססת על קוד פתוח ומתוכננת להיות פשוטה ויעילה, כדי שתוכלו להתחיל לעבוד על הפרויקטים שלכם במהירות.

לפני ההתקנה

יכול להיות ש-PHP כבר מותקן במחשב הפיתוח או בשרת האינטרנט שלכם, ולכן השלב הראשון הוא לוודא זאת ולוודא שגרסת ה-PHP עדכנית מספיק כדי שאפשר יהיה להשתמש בה בספריית הלקוח. הדרך הקלה ביותר לבדוק היא להציב קובץ חדש בספרייה בשרת שאפשר לגשת אליה דרך האינטרנט. מקלידים את הפרטים הבאים בקובץ:

<?php phpinfo(); ?>

לאחר מכן, מגדירים את ההרשאות המתאימות כדי לוודא שאפשר לגשת אליו מהאינטרנט, ועוברים למיקום שלו מתוך הדפדפן. אם PHP מותקן והשרת שלכם יכול לעבד דפי PHP, אתם אמורים לראות משהו דומה למה שמופיע בצילום המסך הבא:

צילום מסך של דף המידע של php

צילום מסך שבו מוצג דף המידע של PHP. בדף הזה מוצגת גרסת ה-PHP שהותקנה (5.2.6 במקרה הזה), יחד עם התוספים שהופעלו (בקטע Configure Command) והמיקום של קובץ ההגדרות הפנימי של PHP (בקטע Loaded Configuration File). אם הדף לא מוצג או אם גרסת ה-PHP שלכם ישנה יותר מ-5.1.4, תצטרכו להתקין או לשדרג את גרסת ה-PHP. אחרת, אפשר לדלג לקטע הבא ולהמשיך אל התקנת ספריית הלקוח של PHP.

הערה: אם יש לכם גישה לשורת הפקודה ואתם מתכננים להשתמש ב-PHP כדי להריץ סקריפטים של שורת פקודה, כדאי לעיין בקטע בנושא PHP של שורת פקודה במאמר הזה.

התקנת PHP

ההתקנה משתנה קצת בהתאם לפלטפורמה, ולכן חשוב לפעול לפי ההוראות שמתאימות לפלטפורמה הספציפית שלכם במהלך ההתקנה. לפני שמתחילים, חשוב לציין שחבילות שהותקנו מראש וכוללות גם את שרת האינטרנט Apache ואת מסד הנתונים MySQL יחד עם PHP, נהיות פופולריות יותר ויותר. ל-Windows, ל-Mac OS X ול-Linux, יש את פרויקט XAMPP. משתמשי Mac OS X יכולים גם להשתמש בפרויקט MAMP. שתי החבילות האלה תומכות ב-OpenSSL ב-PHP (שנדרש לאינטראקציה עם פידים מאומתים).

אם אתם מתקינים PHP באמצעות השלבים שבהמשך, הקפידו להתקין גם תמיכה ב-OpenSSL ולהפעיל אותה. פרטים נוספים על כך זמינים בקטע OpenSSL באתר PHP. בקטעים הבאים נסביר איך להתקין PHP בנפרד.

ב-Windows

הדרך הקלה ביותר להתקין את PHP ב-Windows או לשדרג את הגרסה הקיימת היא באמצעות תוכנת ההתקנה של PHP שזמינה בדף ההורדות של PHP.

  1. בוחרים באפשרות של קובץ ההתקנה של PHP (בקטע Windows binaries) שמתאימה לגרסה החדשה ביותר של PHP ומאשרים את ההורדה.
  2. פותחים את קובץ ההתקנה ופועלים לפי ההוראות באשף ההתקנה.
  3. כשמוצגת הנחיה באשף, בוחרים את שרת האינטרנט שמותקן במערכת, כדי שהשרת יוגדר לעבודה עם PHP.
  4. כדי לבדוק את ההטמעה, פועלים לפי השלבים שמפורטים בקטע שלמעלה.

ב-Mac OS X

‫PHP כלול ב-OS X, אבל לפני שמשתמשים בו, צריך לשדרג לגרסה העדכנית ביותר של PHP. כדי לשדרג, אפשר להתקין אחת מכמה חבילות בינאריות בחינם, או לקמפל את התוכנה בעצמכם. פרטים נוספים זמינים בדף התיעוד של PHP בנושא התקנה ב-Mac OS X.

אחרי שמתקינים את OS X או מבצעים הגדרה אחרת, בודקים את ההתקנה לפי השלבים שמפורטים בקטע שלפני ההתקנה במסמך הזה.

ב-Linux

בהתאם להפצת Linux, יכול להיות שיש אפשרות מובנית או קלה לשימוש להגדרת התקנה של PHP. לדוגמה, ב-Ubuntu, אפשר להשתמש במנהל חבילות או פשוט להקליד את הפקודה הבאה במסוף:

sudo apt-get install php5

אם אין חבילת התקנה זמינה בהפצת Linux שלכם, אתם צריכים להתקין מקוד המקור. יש הוראות מפורטות לקומפילציה של PHP עבור Apache 1.3 ולקומפילציה של PHP עבור Apache 2. ב-PHP.net יש גם הוראות לשרתים אחרים.

התקנה של ספריית הלקוח של Google Data PHP

עכשיו, אחרי שהתקנתם גרסה תקינה של PHP, הגיע הזמן להתקין את ספריית הלקוח. ספריית הלקוח היא חלק מ-Zend Framework בקוד פתוח, אבל אפשר גם להוריד אותה כגרסה עצמאית. אם כבר מותקנת אצלכם גרסה של Zend Framework (גרסה 1.6 ומעלה), אתם יכולים לדלג על ההתקנה כי Google Data Client Library כלולה בה. עם זאת, כדי לוודא שאתם משתמשים בכל התכונות החדשות ונהנים מתיקוני הבאגים, מומלץ בדרך כלל להשתמש בגרסה העדכנית ביותר של המסגרת.

הורדת המסגרת המלאה תיתן לכם גישה לא רק לספריית הלקוח של Google Data, אלא גם לשאר המסגרת. ספריית הלקוח עצמה משתמשת בכמה מחלקות אחרות ששייכות ל-Zend Framework המלא, אבל אין צורך להוריד את המסגרת כולה כי צרפנו אותן להורדה העצמאית.

  1. מורידים את הקבצים של ספריית הלקוח של Google Data. (מחפשים בדף את המחרוזת Google Data APIs).
  2. פורסים את הקבצים שהורדתם. צריך ליצור ארבע ספריות משנה:
    • ‫demos — אפליקציות לדוגמה
    • ‫documentation — תיעוד לקבצים של ספריית הלקוח
    • ‫library – קובצי המקור של ספריית הלקוח.
    • ‫tests — קבצים של בדיקות יחידה לבדיקות אוטומטיות.
  3. מוסיפים את המיקום של התיקייה library לנתיב ה-PHP (ראו בקטע הבא)

בדיקה כדי לוודא שיש לכם גישה לקבצים של ספריית הלקוח

השלב האחרון הוא לוודא שאפשר להפנות לקבצים של ספריית הלקוח של PHP ולכלול אותם בספרייה שבה אתם בונים את הפרויקט. כדי לעשות את זה, צריך להגדיר את המשתנה include_path בקובץ ההגדרות של PHP‏ (php.ini). המשתנה include_path מכיל מספר מיקומי ספריות ש-PHP בודק כשמנפיקים הצהרה של require או include ששולפת מחלקות, ספריות או קבצים חיצוניים לסקריפט הנוכחי, בדומה להצהרה import ב-Java. צריך לצרף את המיקום של קבצי ספריית הלקוח למה שכבר הוגדר ב-include_path. יש שתי דרכים לעשות זאת (שתיהן מוסברות בפירוט בהמשך):

  • הגדרה קבועה של ההנחיה include_path בקובץ ההגדרות php.ini משורת הפקודה – נדרשת גישה למעטפת והרשאות כתיבה.
  • הגדרת משתנה הנתיב include_path ברמה של 'לכל ספרייה' – נדרשים שרת האינטרנט Apache ויכולת ליצור קובצי .htaccess.
  • משתמשים בפונקציה set_include_path() כדי להגדיר באופן דינמי את נתיב ה-include בסקריפטים – אפשר להגדיר באופן דינמי בכל אחד מקובצי ה-‎ .php.

אם יש לכם גישה למעטפת והרשאות כתיבה לקובץ php.ini (או אם אתם כותבים קוד במחשב המקומי), פשוט פועלים לפי ההוראות בנספח א'. אם אתם משתמשים בשרת האינטרנט Apache ויש לכם אפשרות ליצור קובצי .htaccess, אתם יכולים להגדיר את המשתנה include_path ברמה של 'לכל ספרייה'. המשמעות היא שכל הקבצים בספרייה שבה אתם עובדים יכולים להפנות באופן אוטומטי לספריית ספריית הלקוח.

אפשר לציין אפשרויות הגדרה של PHP כמו בקטע הקוד הבא:

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

הערה: מידע נוסף על שינוי הגדרות זמין במדריך PHP.

אם אין לכם גישת מעטפת לשרת ואתם לא יכולים לשנות או ליצור קבצי ‎ .htaccess, אתם תמיד יכולים להשתמש בפונקציה set_include_path. שימו לב: יכול להיות שכבר הגדרתם ערך מסוים לפרמטר include_path, ולכן מומלץ לפעול לפי הדגם שבהמשך כדי להוסיף את הערכים החדשים, במקום להחליף את כל הנתיב:

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

הערה: פרטים נוספים על הפונקציה set_include_path זמינים בדפי ההוראות של PHP.

הרצת הכלי לבדיקת התקנה של PHP

כדי לוודא שהנתיב של הקובץ include הוגדר בצורה נכונה, אפשר להריץ את סקריפט Installation Checker של PHP. פשוט מעתיקים ומדביקים את התוכן של הקובץ הזה בקובץ חדש בספרייה שאפשר לגשת אליה דרך האינטרנט בשרת, ועוברים אליו מהדפדפן. אם הפלט שמוצג דומה לזה שבהמשך, סימן שהגדרתם הכול בצורה נכונה ואתם מוכנים להשתמש בספריית הלקוח של PHP:

צילום מסך של פלט בודק ההתקנה של PHP

אם מופיעות שגיאות (כמו בצילום המסך שלמטה), צריך לוודא שפועלים לפי ההוראות. יכול להיות שחסרים לך תוספים או שהנתיב עדיין לא מוגדר בצורה נכונה. חשוב לזכור שאולי תצטרכו להפעיל מחדש את השרת כדי שהשינויים ייכנסו לתוקף. האפשרות הזו רלוונטית רק אם אתם משנים את הקובץ php.ini. בצילום המסך שלמטה אפשר לראות שהערך של include_path מוגדר ל-/path/to/nowhere:

צילום מסך של פלט בודק ההתקנה של PHP

הערה: כדאי לדעת שכלי הבדיקה של התקנת PHP בודק את הדברים הבאים ברצף: (1) האם תוספי ה-PHP הנדרשים מותקנים, (2) האם include_path מצביע על הספרייה של ספריית הלקוח של PHP, (3) האם אפשר ליצור חיבורי SSL, ולבסוף, האם אפשר ליצור חיבור אל YouTube Data API. אם בדיקה ספציפית נכשלת, הבדיקות הנותרות לא יופעלו.

עכשיו, אחרי שספריית הלקוח מותקנת, הגיע הזמן לנסות להריץ את הדוגמאות.

הרצת הדוגמאות

בתיקיית השורש Zend/Gdata יש תיקייה של הדגמות – דוגמאות שיעזרו לכם להתחיל. חלק מהדוגמאות האלה מיועדות להרצה משורת הפקודה, כמו demos/Zend/Gdata/Blogger.php ו-demos/Zend/Gdata/Spreadsheet-ClientLogin.php, ואפשר להריץ אותן באמצעות php /path/to/example. אפשר להריץ את הדוגמאות שנותרו גם משורת הפקודה וגם מדפדפן אינטרנט. אם רוצים להציג אותם בדפדפן, צריך למקם אותם בספרייה שבה משתמשים כדי להציג דפי אינטרנט. הדוגמאות האלה אמורות לתת לכם מושג בסיסי לגבי כתיבה והפעלה של אפליקציית Google Data, אבל אם אתם רוצים ללמוד עוד, יש משאבים נוספים למתכנתים סקרנים.

הערה: אם אתם רוצים לראות את ההדגמות באינטרנט, אתם יכולים להיכנס לכתובת googlecodesamples.com ולחפש את אפליקציות ה-PHP.

איפה אפשר לקבל מידע נוסף

המקום הטוב ביותר לחפש בו מידע על המחלקות שכלולות בספריית הלקוח הוא מדריך ההפניה ל-API באתר Zend Framework. חשוב לבחור את חבילת Zend_Gdata מהתפריט הנפתח.

בשלב הזה, הכול מוכן ואפשר להתחיל לכתוב קוד. אז קדימה, כתבו אפליקציות מעולות. נשמח לראות את התוצאות שלך!

אפשר למצוא מדריכים למפתחי PHP לשירותים הבאים:

ספריית הלקוח של PHP היא פרויקט קוד פתוח, ולכן אנחנו מוסיפים לה תמיכה בעוד ועוד ממשקי API. לכל שירות יש קבוצת תמיכה משלו. במאמר השאלות הנפוצות שלנו מופיעה רשימה של קבוצות התמיכה הזמינות.

אם אתם צריכים עזרה בפתרון בעיות שקשורות לקריאות ל-API, תוכלו לעיין במאמרים בנושא ניפוי באגים בבקשות API באמצעות כלים ללכידת תעבורת נתונים ברשת ובנושא שימוש בשרתי proxy עם Google Data APIs. יש גם כמה מאמרים חיצוניים בנושא התקנת XAMPP ב-Linux והתקנת XAMPP ב-Windows. בנוסף לכל המאמרים האלה, מומלץ לעיין בפוסטים על ספריית הלקוח של PHP בבלוג Google Data API Tips.

נספח א': עריכת נתיב ה-PHP בקובץ ההגדרות php.ini

נתיב ה-PHP הוא משתנה שמכיל רשימה של מיקומים ש-PHP מחפש בהם כשהוא מחפש ספריות נוספות במהלך הטעינה. כדי ש-PHP יוכל לטעון את הקבצים של ספריית הלקוח של Google Data PHP ולגשת אליהם במחשב או בשרת, צריך למקם אותם במיקום ש-PHP מכיר. לחלופין, צריך לצרף את מיקום הקבצים לנתיב ה-PHP. שימו לב: בדרך כלל, כדי שהשינויים בקובץ php.ini ייכנסו לתוקף, צריך להפעיל מחדש את השרת. תמיד אפשר לבדוק את הערך הנוכחי של המשתנה include_path על ידי מעבר לדף PHP Info שמפורט בהמשך. מחפשים את התא Loaded Configuration File בטבלה הראשונה ומוצאים את הנתיב בעמודה שמשמאל.

הערה: אם אתם משתמשים ב-php משורת הפקודה, יכול להיות שתצטרכו לשנות משתנה נתיב נוסף. חשוב לעיין בנספח ב': שימוש ב-PHP משורת הפקודה.

אחרי שמאתרים את הקובץ php.ini, פועלים לפי השלבים הבאים כדי להוסיף אותו לנתיב.

  1. פותחים את הקובץ php.ini בכלי לעריכת טקסט שבו אתם משתמשים.
  2. מאתרים את השורה שמפנה לנתיב PHP, היא אמורה להתחיל ב-include_path.
  3. מוסיפים את הנתיב שבו שמרתם את Zend Framework לרשימת המיקומים הקיימת, ומוסיפים לפני הנתיב החדש את התו המפריד שמוגדר למערכת ההפעלה שלכם (: במערכות דמויות Unix, ‏ ; ב-Windows). נתיב תקין במערכות דמויות Unix ייראה בערך כך:
    ‫
    /path1:/path2:/usr/local/lib/php/library
     ב-Windows, זה ייראה בערך כך: 
    \path1;\path2;\php\library
  4. שומרים את הקובץ וסוגרים אותו.

הערה: ב-Mac OS X, אי אפשר לגשת לקבצים שנמצאים במיקומי מערכת כמו הספרייה /etc דרך Finder. לכן, יכול להיות שהכי קל לערוך אותם באמצעות עורך שורת פקודה כמו vi או pico. כדי לעשות זאת, משתמשים בפקודה כמו: pico /path/to/php.ini.

נספח ב': שימוש ב-PHP משורת הפקודה

החל מגרסה 5 של PHP, יש ב-PHP כלי שורת פקודה שנקרא CLI, קיצור של Command Line Interpreter (מפרש שורת פקודה). הכלי הזה מאפשר להריץ סקריפטים של php משורת הפקודה. השימוש הזה יכול להיות שימושי אם אתם מריצים PHP באופן מקומי במחשב ומחפשים דרכים לבדוק במהירות סקריפטים מסוימים. כדי לעשות זאת, תצטרכו גישת Shell לשרת. חשוב לדעת שבדרך כלל PHP משתמש בשני קובצי php.ini נפרדים. קובץ אחד מכיל את אפשרויות ההגדרה של PHP שפועל בשרת, וקובץ אחר מכיל את ההגדרות ש-PHP משתמש בהן כשהוא פועל משורת הפקודה. אם אתם רוצים להריץ את אפליקציות ההדגמה של שורת הפקודה מספריית הלקוח, תצטרכו לשנות גם את קובץ php.ini של שורת הפקודה.

כדי לאתר אותו, מקלידים את הפקודות הבאות במערכות דמויות Unix (Mac OS X,‏ Linux ואחרות):

php -i | grep php.ini

הפקודה הזו אמורה להציג את המידע הבא במסוף:

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

הערה: ברור שמיקומי הנתיבים בפועל (/etc/php...) עשויים להיות שונים במערכת שלכם.

נספח ג': רמזים ופתרונות

בקטע הזה מפורטות כמה מהבעיות שמפתחים גילו במהלך העבודה עם PHP, וגם הפתרונות המתאימים.

בעיה בתוסף dom-xml ב-XAMPP

ספריית הלקוח של PHP משתמשת במחלקות DOMDocument כדי להמיר בקשות ותגובות של XML לאובייקטים של PHP. התוסף dom-xml עלול לגרום לבעיות בטיפול ב-XML ולהוביל לשינויים שגויים. חלק מהמפתחים שלנו גילו שכאשר משתמשים ב-XAMPP, ה-constructor של DOMDocument מוחלף בקריאה ישנה יותר לפונקציה, כמו שמוסבר באתר PHP. כדי לפתור את הבעיה, צריך לוודא שטיפול ב-XML לא נכתב מחדש בקובץ php.ini. חשוב להסיר את ההפניות אל php_domxml.dll מקובץ ההגדרות.

בקשות נכשלות בגלל פסק זמן כשמשתמשים בספריית הלקוח

אם אתם משתמשים בספריית הלקוח כדי לבצע בקשות גדולות יחסית, כמו העלאת סרטונים ל-YouTube Data API, יכול להיות שתצטרכו לשנות את הפרמטר timeout במחלקה Zend_Http_Client. אפשר לעשות את זה בקלות על ידי העברת פרמטר $config במהלך יצירת המופע, שקובע את הערך של timeout למשהו שונה מברירת המחדל של 10 שניות:

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

חלק מספקי האירוח לא מאפשרים ליצור חיבורי HTTPS מהשרתים שלהם

הבנו שחלק מהספקי אירוח לא מאפשרים ליצור חיבורים של https מהשרתים שלהם שמוגדרים כברירת מחדל. אם מופיעה הודעת שגיאה דומה לזו שבהמשך, יכול להיות שתצטרכו ליצור את חיבורי ה-HTTPS דרך שרת proxy מאובטח:

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

ספק האירוח שלכם אמור לספק מידע על הכתובת בפועל של שרת ה-proxy שבו צריך להשתמש. קטע הקוד שלמטה מדגים איך אפשר להשתמש בהגדרת פרוקסי בהתאמה אישית עם ספריית הלקוח של 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");

}

היסטוריית גרסאות

‫1 באוקטובר 2008

עודכן על ידי Jochen Hartmann. העדכון הזה כולל את השינויים הבאים:

  • הבהרנו את ההגדרה של PHP לשרתי אינטרנט על ידי העברת קטעים שמתייחסים ל-PHP בשורת הפקודה לנספח.
  • נוספה הערה לגבי קובצי הגדרות (php.ini) מרובים.
  • הוספנו קטעים שמסבירים איך להגדיר באופן דינמי את include_path.
  • הוספנו קטע על סקריפט לבדיקת ההתקנה.
  • הוספנו קישור לדוגמאות אונליין.
  • נוספו קישורים ל-XAMPP ול-MAMP.
  • הוספנו נספח עם רמזים ופתרונות.