存取 PHP 適用的舊版套裝組合服務

本頁說明如何安裝及使用 App Engine 標準環境的 PHP 執行階段隨附的服務。您的應用程式可以透過 PHP 適用的 App Engine 服務 SDK 存取套裝組合服務。

事前準備

1. 請參閱可透過 PHP 執行階段呼叫的舊版服務套裝組合 API 清單。

2. 更新 app.yaml 檔案，加入下列程式碼：

   app_engine_apis: true
   

3. 如要測試 PHP 應用程式，必須使用 gcloud app deploy 部署應用程式。

安裝 PHP App Engine SDK

您可以在 GitHub 的 appengine-php-sdk 中找到 PHP App Engine SDK。如要使用 PHP 8.1 以上版本，必須使用 2.1 以上版本；如要使用 PHP 7.x，則必須使用 2.0.1 以上版本。

將 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 中，App Engine API 需要明確指定依附元件。如要瞭解如何加入 autoload.php，請參閱這份文件。

匯入程式庫

使用 use 運算子，從「Available APIs」(可用 API) 清單匯入所需類別。舉例來說，您可以使用下列陳述式匯入 Google\AppEngine\Api\AppIdentity\ClassName：

use Google\AppEngine\Api\AppIdentity\ClassName;

遷移注意事項

應用程式身分

升級至 PHP 時，您不需要變更應用程式的設定。應用程式 ID API 的行為、功能和設定說明維持不變。詳情請參閱 API Identity 總覽和 App Identity API 參考指南。

郵件

PHP Mail API 與 PHP 5 Mail API 大致相同，只有啟用和停用 Mail 服務的方式略有不同。以下各節將說明這兩種執行階段的差異。

訊息類別

在 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() 函式會遭到 App Engine 的 Mail 函式多載。

在 PHP 中，App Engine Mail 函式預設不再過度負載，必須明確啟用。這項新功能可讓您重新調整郵件函式用途，以更符合自身需求。這項變更也讓您能夠瞭解目前所有郵件函式呼叫使用的實作方式。

如果您偏好使用原生 PHP mail() 函式，透過 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 函式實作。啟用這項功能後，所有對 mail() 的呼叫都會與 PHP 5.5 中的呼叫完全相同。

詳情請參閱「傳送郵件」和「接收郵件」指南，以及 Mail API 參考指南。

Memcache

如要使用 PHP 適用的 Memcache，您需要明確宣告 Memcache 程式庫。先前，PHP 5.5 的 Memcache 不需要明確宣告。這項明確宣告可讓您彈性切換原生 PHP Memcache 和 App Engine Memcache。

PHP Memcache 類別的行為與 PHP 5 Memcache 類別相同，但明確宣告除外。詳情請參閱 Memcache 總覽。

PHP 5.5

PHP 5.5 適用的 Memcache 範例：

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

PHP 5.5 的 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(),
]);

PHP 7/8

PHP 的 Memcache API 範例：

use Google\AppEngine\Api\Memcache\Memcache;

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

PHP 適用的 Memcached API 範例：

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(),
]);

如果您偏好在 PHP 中使用 PHP 5 的原始 Memcache 行為，可以繼續在 composer.json 檔案中加入幾行程式碼，隱含呼叫 Memcache。從 Composer 匯入 appengine-php-sdk 套件後，請在 autoload 部分的 files 元素中新增下列選擇加入檔案路徑：

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 的行為、功能和設定說明維持不變。詳情請參閱「模組總覽」和「模組 API 參考指南」。

工作階段

PHP 工作階段的運作方式與 PHP 5.5 工作階段相同。不過，由於 PHP 5.5 工作階段預設使用 MemcacheSessionHandler 類別，因此設定說明有所不同。

如要使用 PHP 工作階段，您必須向 session_set_save_handler() 註冊 MemcacheSessionHandler 類別，並將 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);

詳情請參閱工作階段 API 參考指南。

工作佇列

升級至 PHP 時，您不需要變更應用程式的設定。工作佇列的行為、功能和設定說明維持不變。詳情請參閱「Task Queue 總覽」指南和「Task Queue API 參考指南」的「工作階段」一節。

網址擷取

如要使用 PHP 的網址擷取功能，必須明確宣告網址擷取程式庫。先前，PHP 5 的網址擷取服務不需要明確聲明，而是隱含使用。

在 PHP 5 中，App Engine 的網址擷取服務是 PHP 5.5 中擷取網際網路內容的唯一方法，因此大多數存取網際網路的 PHP 5.5 函式都已修補，可自動使用 UrlFetch。

在 PHP 中，原生 PHP 網路可以存取網際網路，因此不會進行這項自動修補作業。在某些情況下，您可以使用原始的 UrlFetch 機制，特別是提供 X-Appengine-Inbound-Appid 要求標頭的機制，用於識別向您的 App Engine 應用程式發出要求的 App Engine 應用程式。

如要為 PHP 啟用網址擷取功能，您可以在串流包裝函式中明確宣告，也可以直接使用 UrlFetch 類別，詳情請參閱下列章節。

選項 1a：串流處理常式

您可以啟用 App Engine 的網址擷取服務，向 http:// 和 https:// PHP 串流處理常式發出 HTTP 要求。現在說明一下操作方式：

1. 使用 stream_wrapper_unregister() 取消註冊 HTTP(S) 的原生 PHP 串流處理常式。
2. 使用 stream_wrapper_register() 將 HTTP(S) 註冊至 UrlFetchStream 類別。
3. 使用要用於串流包裝函式的設定呼叫 file_get_contents()。
   • 如要從 URL 擷取服務切換回原生 PHP 串流處理常式，請使用 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.

選項 1b：含有串流處理常式的 HTTP 回應標頭

使用 HTTP(S) 回應標頭搭配串流處理常式的操作說明，與使用串流處理常式的操作說明類似：

1. 使用 stream_wrapper_unregister() 取消註冊 HTTP(S) 的原生 PHP 串流處理常式。
2. 使用 stream_wrapper_register() 將 HTTP(S) 註冊至 UrlFetchStream 類別。
3. 請使用 fopen()，而非 file_get_contents()，並搭配所需設定。
4. 呼叫 stream_get_meta_data()，然後為 'wrapper_data 建立中繼資料索引，藉此擷取回應標頭資訊。回應標頭會以陣列形式傳回，類似於 PHP 5.5 中的 $http_response_header。

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) 要求。與串流處理常式選項不同，UrlFetch 類別不會覆寫所有來自串流包裝函式相容函式的 HTTP(S) 要求，改為使用網址擷取服務。相較於串流處理常式選項，UrlFetch 類別設定也較簡單，因為不需要使用各種 PHP API，例如：

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

下列 UrlFetch 類別範例等同於串流處理常式範例：

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 參考指南。

社群提供的程式庫

升級至 PHP 時，您可以使用社群貢獻的 API 進行 datastore。

其他注意事項

• 如要在 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 使用舊版套裝服務的範例，請下載程式碼範例。