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

本頁面說明如何為 App Engine 標準環境，搭配使用 PHP 執行階段安裝及使用內含的服務。您的應用程式可透過 PHP 專用的 App Engine 服務 SDK 存取套裝組合服務。

事前準備

  1. 請參閱舊版服務套裝組合 API 清單，瞭解您可以在 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」清單中匯入所需的類別。例如，您可以使用以下陳述式匯入 Google\AppEngine\Api\AppIdentity\ClassName：

use Google\AppEngine\Api\AppIdentity\ClassName;

遷移注意事項

應用程式識別

升級至 PHP 時，您不需要變更應用程式的設定。App Identity API 的行為、功能和設定說明皆維持不變。詳情請參閱「API 身分總覽」和 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 函式不再預設為超載，必須明確啟用。這項新行為可讓您重新利用 Mail 函式，以便更符合需求。這項變更還可讓您瞭解目前為所有 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() 的呼叫都會與 PHP 5.5 中的呼叫完全相同。

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

Memcache

如要使用 Memcache for PHP，您必須明確宣告 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 中使用 Memcache for PHP 5 的原始行為，可以在 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 的行為、功能和設定說明皆維持不變。詳情請參閱「模組總覽」和 Modules 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);

詳情請參閱 Session 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()。

如需比較，請參閱 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 時，您可以使用社群貢獻的 datastore API。

其他注意事項

  • 如要測試 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 的範例，請下載程式碼範例。