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

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

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

אפשר לעיין ברשימת ממשקי ה-API של שירותים חבילה מדור קודם שאפשר להפעיל בסביבת זמן הריצה של PHP.
צריך לעדכן את הקובץ app.yaml ולהוסיף לו את השורה הבאה:
```
app_engine_apis: true
```
כדי לבדוק את אפליקציית ה-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 בפרויקט:

מריצים את הפקודה Packagist כדי להוסיף את ה-SDK לקובץ composer.json:
```
composer require google/appengine-php-sdk
```

יוצרים ידנית קובץ 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.

שליחת אימייל

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

סיווג ההודעה

ב-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 runtime configuration להטמעה של פונקציית הדואר של 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 השתמשו בכיתה 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.

אחזור כתובת URL

כדי להשתמש ב-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א'. רכיבי handler של סטרימינג

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

מבטלים את הרישום של handler הסטרימינג המקורי של PHP עבור HTTP(S) באמצעות stream_wrapper_unregister().
רושמים HTTP(S) למחלקה UrlFetchStream באמצעות stream_wrapper_register().
מתקשרים אל file_get_contents() עם ההגדרה שרוצים להשתמש בה ב-stream wrapper.
- אם רוצים לחזור לטיפול המקורי בזרם PHP משירות URL Fetch, משתמשים ב-stream_wrapper_unregister() ואז נרשמים באמצעות stream_wrapper_restore().

לצורך השוואה, הנה דוגמאות מקבילות ל-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) עם רכיבי טיפול בסטרימינג דומות להוראות לשימוש ברכיבי טיפול בסטרימינג:

מבטלים את הרישום של handler הסטרימינג המקורי של PHP עבור HTTP(S) באמצעות stream_wrapper_unregister().
רושמים HTTP(S) למחלקה UrlFetchStream באמצעות stream_wrapper_register().
משתמשים ב-fopen() במקום ב-file_get_contents() עם ההגדרה הרצויה.
מתקשרים אל 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 היא מחלקה מותאמת אישית שמספקת דרך ממוקדת יותר להשתמש בשירות אחזור של כתובות אתרים לבקשת HTTP(S) בהיקף קטן יותר. בניגוד לאפשרות של stream handler, המחלקה UrlFetch לא מבטלת את כל בקשות ה-HTTP(S) שמוגשות מפונקציות שתואמות ל-stream wrapper כדי להשתמש בשירות אחזור של כתובות אתרים. בהשוואה לאפשרות של 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, אפשר להוריד את דוגמאות הקוד.

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

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

התקנה של PHP App Engine SDK

PHP 7/8

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

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

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

שליחת אימייל

סיווג ההודעה

PHP 5.5

PHP 7/8

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

Memcache

PHP 5.5

PHP 7/8

PHP 7/8

מודולים

אירוע

PHP 7/8

תור משימות

אחזור כתובת URL

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

PHP 5.5

PHP 7/8

אפשרות 1ב. כותרות של תגובת HTTP עם רכיבי handler של זרם

PHP 5.5

PHP 7/8

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

PHP 7/8

משתמשים

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

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

דוגמאות

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