גישה לחבילות שירותים מדור קודם ל-PHP

בדף הזה מוסבר איך להתקין ולהשתמש בשירותים בחבילה עם זמן הריצה של PHP בסביבה הרגילה של App Engine. האפליקציה יכולה לגשת לשירותים בחבילה באמצעות App Engine services SDK for PHP.

לפני שמתחילים

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

  2. מעדכנים את קובץ app.yaml כדי לציין שירות אחד או יותר מהדור הקודם. לדוגמה:

    app_engine_bundled_services:
- memcache
- urlfetch

  3. כדי לבדוק את אפליקציית ה-PHP, צריך לפרוס אותה באמצעות gcloud app deploy.

התקנה של PHP App Engine SDK

אפשר למצוא את ה-SDK של PHP App Engine ב-GitHub בכתובת appengine-php-sdk. חייבים להשתמש בגרסה 2.1 ואילך עבור PHP 8.1 ומעלה, ובגרסה 2.0.1 ואילך עבור PHP 7.x.

יש שתי דרכים לשלב את ה-SDK בפרויקט:

  1. מריצים את הפקודה Packagist כדי להוסיף את ה-SDK לקובץ composer.json:

    composer require google/appengine-php-sdk

  2. יוצרים ידנית קובץ composer.json עם הפרטים הבאים:

    PHP 7/8

    {
    "require": {
        "google/appengine-php-sdk": "^2.1" // Or any later version
    }
}

ב-PHP, ממשקי ה-API של App Engine דורשים ציון תלות מפורש. במסמך הזה מוסבר איך לכלול את autoload.php.

ייבוא הספריות

משתמשים באופרטור use כדי לייבא את המחלקה שרוצים מרשימת ממשקי ה-API הזמינים. לדוגמה, אפשר לייבא את Google\AppEngine\Api\AppIdentity\ClassName באמצעות ההצהרה:

use Google\AppEngine\Api\AppIdentity\ClassName;

שיקולים לגבי מיגרציה

זהות האפליקציה

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

שליחת אימייל

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

סיווג ההודעה

ב-PHP, המחלקה Message פועלת כמו ב-PHP 5.5, למעט העדכון של הייבוא use. אלה ההבדלים:

PHP 5.5

use google\appengine\api\mail\Message;

PHP 7/8

use Google\AppEngine\Api\Mail\Message;

אם אין לכם אפשרות לשנות את הצהרות הייבוא, הצהרת הייבוא המקורית של PHP 5.5 תפעל גם ב-PHP.

פונקציית אימייל

ב-PHP 5.5, הפונקציה המקורית של PHP‏ mail() עברה עומס יתר בגלל הפונקציה Mail של App Engine.

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

אם אתם מעדיפים להשתמש בפונקציה המקורית mail() של PHP כדי לשלוח אימייל באמצעות App Engine Mail API, אתם יכולים להפעיל אותה בקובץ php.ini באופן הבא:

extension = mailparse.so
sendmail_path = "php ./vendor/google/appengine-php-sdk/src/Runtime/SendMail.php -t -i"

כפי שמוצג בדוגמה הקודמת, מוסיפים את התוסף mailparse כדי להפעיל את פונקציית הדואר המקורית של PHP, ומגדירים את ההגדרה של זמן הריצה sendmail_path להטמעה של פונקציית הדואר של App Engine. אחרי ההפעלה, כל הקריאות ל-mail() יפעלו בדיוק כמו ב-PHP 5.5.

לפרטים נוספים, אפשר לעיין במדריכים בנושא שליחת אימייל וקבלת אימייל ובמדריך בנושא Mail API.

Memcache

כדי להשתמש ב-Memcache עבור PHP, צריך להוסיף הצהרה מפורשת של ספריות Memcache. בעבר, לא הייתה דרישה להצהרה מפורשת ב-Memcache עבור PHP 5.5. ההצהרה המפורשת הזו מאפשרת גמישות במעבר בין Memcache מקורי של PHP לבין Memcache של App Engine.

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

PHP 5.5

דוגמה ל-Memcache ל-PHP 5.5:

$memcache = new Memcache();
return $memcache->get($key);

דוגמה ל-Memcached ל-PHP 5.5:

$memcache = new Memcached();
$memcache->set('who', $request->get('who'));
return $twig->render('memcache.html.twig', [
    'who' => $request->get('who'),
    'count' => $memcache->increment('count', 1, 0),
    'host' => $request->getHost(),
]);

PHP 7/8

דוגמה ל-Memcache API ל-PHP:

use Google\AppEngine\Api\Memcache\Memcache;

$memcache = new Memcache();
return $memcache->get($key);

דוגמה ל-Memcached API ל-PHP:

use Google\AppEngine\Api\Memcache\Memcached;

$memcache = new Memcached();
$memcache->set('who', $request->get('who'));
return $twig->render('memcache.html.twig', [
    'who' => $request->get('who'),
    'count' => $memcache->increment('count', 1, 0),
    'host' => $request->getHost(),
]);

אם אתם מעדיפים להשתמש בהתנהגות המקורית של Memcache עבור PHP 5 ב-PHP, אתם יכולים להמשיך לקרוא ל-Memcache באופן מרומז על ידי הוספת עוד כמה שורות לקובץ composer.json. אחרי ייבוא החבילה appengine-php-sdk מ-composer, מוסיפים את נתיב הקובץ להבעת הסכמה לרכיב files בקטע autoload:

PHP 7/8

{
  "require": {
    "google/appengine-php-sdk": "^2.1" // Or any later version
  },
  "autoload": {
    "files": [
    "./vendor/google/appengine-php-sdk/src/Api/Memcache/MemcacheOptIn.php"
    ]
  }
}

מודולים

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

אירוע

PHP Sessions פועל באותו אופן כמו PHP 5.5 Sessions. עם זאת, הוראות ההגדרה שונות כי PHP 5.5 Sessions השתמש ב-class‏ MemcacheSessionHandler כברירת מחדל.

כדי להשתמש ב-Sessions for PHP, צריך לרשום את המחלקה MemcacheSessionHandler באמצעות session_set_save_handler() ולהגדיר את session.save_path ל-Memcache. כדאי גם להביע הסכמה לשימוש ב-Memcache כשניגשים לפרטים של Memcache.

לדוגמה:

PHP 7/8

ini_set('session.save_path', 'Google\AppEngine\Api\Memcache\Memcache');
session_set_save_handler(new Google\AppEngine\Ext\Session\MemcacheSessionHandler(), true);

פרטים נוספים מופיעים במדריך ההפניה ל-Session API.

תור משימות

אין צורך לבצע שינויים בהגדרות של האפליקציה כשמשדרגים ל-PHP. ההתנהגות, התכונות והוראות ההגדרה של תור המשימות נשארים ללא שינוי. לפרטים נוספים, אפשר לעיין בקטע 'סשנים' במדריך סקירה כללית של תור המשימות ובמדריך Task Queue API reference guide.

URL Fetch

כדי להשתמש ב-URL Fetch ל-PHP, צריך להוסיף הצהרה מפורשת של ספריות URL Fetch. בעבר, שירות אחזור של כתובות אתרים ל-PHP 5 לא דרש הצהרה מפורשת והשימוש בו היה מרומז.

ב-PHP 5, שירות אחזור של כתובות אתרים של App Engine היה הדרך היחידה לאחזור תוכן מהאינטרנט ב-PHP 5.5, ולכן רוב הפונקציות של PHP 5.5 שניגשו לאינטרנט תוקנו כדי להשתמש ב-UrlFetch באופן אוטומטי.

ב-PHP, רשתות PHP מקוריות יכולות לגשת לאינטרנט, ולכן התיקון האוטומטי הזה לא מתבצע. במקרים מסוימים, אפשר להשתמש במנגנון המקורי UrlFetch ובמיוחד במנגנון שמספק את כותרת הבקשה X-Appengine-Inbound-Appid כדי לזהות את אפליקציית App Engine ששולחת בקשה לאפליקציית App Engine.

כדי להפעיל את אחזור כתובות ה-URL עבור PHP, אפשר להשתמש בהצהרה מפורשת ב-stream wrapper או להשתמש ישירות במחלקה UrlFetch, כמו שמתואר בקטעים הבאים.

אפשרות 1א. Stream handlers

אפשר להפעיל את שירות אחזור של כתובות אתרים של App Engine כדי לבצע בקשות HTTP ל-http:// ול-https:// PHP stream handlers. לשם כך:

  1. מבטלים את הרישום של handler הזרם המקורי של PHP עבור HTTP(S) באמצעות stream_wrapper_unregister().
  2. רושמים HTTP(S) למחלקה UrlFetchStream באמצעות stream_wrapper_register().
  3. מתקשרים אל file_get_contents() עם ההגדרה שרוצים להשתמש בה ב-stream wrapper.

לשם השוואה, הנה דוגמאות מקבילות ל-PHP 5 ול-PHP:

PHP 5.5

...
$context = [
    'http' => [
        'method' => 'POST',
        'header' => $headers,
        'content' => http_build_query($data),
    ]
];
$context = stream_context_create($context);

// Using Url Fetch service. No option to use the native php stream wrapper.
$result = file_get_contents('http://example.com', false, $context);
echo $result;

PHP 7/8

use google\appengine\api\urlfetch\UrlFetchStream;
...
$context = [
    'http' => [
        'method' => 'POST',
        'header' => $headers,
        'content' => http_build_query($data),
    ]
];
$context = stream_context_create($context);

// Using the native php stream wrapper.
$result = file_get_contents('http://example.com', false, $context);
echo $result;

stream_wrapper_unregister("http");
stream_wrapper_register("http", "UrlFetchStream");

// Now using the Url Fetch service.
$result = file_get_contents('http://example.com', false, $context);
echo $result;

stream_wrapper_unregister("http");
stream_wrapper_restore("http");

// Now using the native php stream wrapper again.

אפשרות 1ב. כותרות של תגובת HTTP עם רכיבי handler של סטרימינג

ההוראות לשימוש בכותרות תגובה של HTTP(S) עם רכיבי טיפול בסטרימינג דומות להוראות לשימוש ברכיבי טיפול בסטרימינג:

  1. מבטלים את הרישום של handler הסטרימינג המקורי של PHP עבור HTTP(S) באמצעות stream_wrapper_unregister().
  2. רושמים HTTP(S) למחלקה UrlFetchStream באמצעות stream_wrapper_register().
  3. משתמשים ב-fopen() במקום ב-file_get_contents() עם ההגדרה הרצויה.
  4. מתקשרים אל stream_get_meta_data() ומחלצים את פרטי כותרת התגובה על ידי יצירת אינדקס של מטא-נתונים עבור 'wrapper_data. כותרות התגובה מוחזרות במערך שדומה לזה של $http_response_header ב-PHP 5.5.

PHP 5.5

...
$context = [
    'http' => [
        'method' => 'POST',
        'header' => $headers,
        'content' => http_build_query($data),
    ]
];
$context = stream_context_create($context);

// Using file_get_contents and the Url Fetch service.
$result = file_get_contents('http://example.com', false, $context);

// Print Http Response Headers
print_r($http_response_header);

PHP 7/8

use google\appengine\api\urlfetch\UrlFetchStream;
...
$context = [
    'http' => [
        'method' => 'POST',
        'header' => $headers,
        'content' => http_build_query($data),
    ]
];
$context = stream_context_create($context);

stream_wrapper_unregister("http");
stream_wrapper_register("http", "UrlFetchStream");

// Now using fopen and the Url Fetch service.
$result = fopen('http://example.com', 'r', false, $context);

// Print Http Response Headers
$meta_data = stream_get_meta_data($result);
$headers = $meta_data['wrapper_data'];
print_r($headers);

stream_wrapper_unregister("http");
stream_wrapper_restore("http");

אפשרות 2. מחלקת URLFetch

המחלקות UrlFetch הן מחלקות בהתאמה אישית שמספקות דרך ממוקדת יותר להשתמש בשירות URL Fetch לבקשת HTTP(S) בהיקף קטן יותר. בניגוד לאפשרות של stream handler, המחלקות UrlFetch לא מבטלות את כל בקשות ה-HTTP(S) שמתבצעות מפונקציות שתואמות ל-stream wrapper כדי להשתמש בשירות URL Fetch. בהשוואה לאפשרות של stream handler, ההגדרה של המחלקות UrlFetch גם פשוטה יותר, כי היא לא דורשת שימוש בממשקי API שונים של PHP, כמו:

  • stream_context_create()
  • stream_wrapper_unregister()
  • stream_wrapper_register()
  • file_get_contents()

הדוגמה הבאה של מחלקה UrlFetch שקולה לדוגמה של רכיב handler של הזרם:

PHP 7/8

use google\appengine\api\urlfetch\UrlFetch;
...
$urlfetch = new UrlFetch();
$result = $urlfetch->fetch($url, 'POST', $headers, http_build_query($data));
echo $result->getContent();

משתמשים

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

ספריות שנוצרו על ידי הקהילה

אפשר להשתמש ב-API שנוצר על ידי הקהילה עבור datastore כשמשדרגים ל-PHP.

שיקולים נוספים

  • כדי לבדוק את הפונקציונליות של שירותים בחבילה מדור קודם באפליקציית PHP, אפשר להשתמש בשרת פיתוח מקומי. כשמריצים את הפקודה dev_appserver.py, מגדירים את הארגומנט --php_executable_path לקובץ הפעלה של PHP. שימו לב: זה שונה מ-PHP 5, שנדרש בה קובץ הפעלה php-cgi.

    אם בפרויקט יש קובץ composer.json, מגדירים את --php-composer-path לנתיב של קובץ composer.phar.

  • כדי לפרוס את האפליקציה, משתמשים בפקודה gcloud app deploy.

  • רישום ביומן בזמן הריצה של PHP מתבצע לפי תקן רישום ביומן ב-Cloud Logging. בזמן הריצה של PHP, יומני האפליקציה כבר לא נכללים עם יומני הבקשות, אלא מופרדים לרשומות שונות. מידע נוסף על קריאה וכתיבה של יומנים מופיע במדריך לכתיבה ולצפייה ביומנים.

דוגמאות

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