이 페이지에서는 PHP 런타임을 1세대에서 2세대로 마이그레이션하는 방법을 안내합니다. 지원되는 최신 PHP 버전을 사용하도록 2세대 앱을 업그레이드하는 방법은 기존 애플리케이션 업그레이드를 참조하세요.
PHP 5는 2024년 1월 30일에 지원 종료되었습니다. 기존 PHP 5 애플리케이션을 계속 실행하고 트래픽을 받을 수 있습니다. 그러나 App Engine에서 지원 종료 날짜 이후에 런타임을 사용하는 애플리케이션의 재배포를 차단할 수 있습니다.
이 페이지의 안내에 따라 PHP 런타임을 지원되는 최신 런타임으로 마이그레이션하는 것이 좋습니다.
지원되는 2세대 PHP 런타임으로 마이그레이션하면 최신 언어 기능을 사용하고 관용적인 코드로 이동성이 향상된 앱을 빌드할 수 있습니다.
다음은 App Engine 표준 환경에서 PHP 5.5와 2세대 PHP 런타임 간의 차이점을 요약한 내용입니다.
메모리 사용량 차이
2세대 런타임은 1세대 런타임에 비해 메모리 사용량 기준이 더 높습니다. 이는 여러 다른 기본 이미지 버전, 두 세대 간의 메모리 사용량 계산 방법의 차이와 같은 여러 요인 때문에 발생합니다.
2세대 런타임은 애플리케이션 프로세스가 사용하는 항목의 합계 및 메모리에 동적으로 캐시된 애플리케이션 파일 수에 따라 인스턴스 메모리 사용량을 계산합니다. 메모리 사용량이 높은 애플리케이션에서 메모리 한도 초과로 인한 인스턴스 종료가 발생하지 않도록 방지하려면 메모리가 많은 더 큰 인스턴스 클래스로 업그레이드하세요.
CPU 사용량 차이
2세대 런타임은 인스턴스 콜드 스타트 시 CPU 사용량 기준이 더 높을 수 있습니다. 그 결과 애플리케이션의 확장 구성에 따라 애플리케이션이 CPU 사용률을 기준으로 확장되도록 구성된 경우 예상한 것보다 높은 인스턴스 수와 같은 의도치 않은 부작용이 발생할 수 있습니다. 이러한 문제를 방지하기 위해서는 애플리케이션 확장 구성을 검토 및 테스트해서 인스턴스 수를 적정 수준으로 유지해야 합니다.
요청 헤더 차이
1세대 런타임에서는 밑줄이 사용된 요청 헤더(예: X-Test-Foo_bar)를 애플리케이션에 전달할 수 있습니다. 2세대 런타임에는 호스트 아키텍처에 Nginx가 도입되었습니다. 이러한 변경사항으로 인해 2세대 런타임은 밑줄(_)이 있는 헤더를 자동으로 삭제하도록 구성됩니다. 애플리케이션 문제를 방지하기 위해서는 애플리케이션 요청 헤더에 밑줄을 사용하지 않아야 합니다.
런타임을 보다 쉽고 간단하게 마이그레이션할 수 있도록 App Engine 표준 환경에서 Memcache와 같은 2세대 PHP 런타임의 다양한 기존 번들 서비스와 API에 액세스할 수 있습니다.
2세대 PHP 앱은 App Engine SDK를 통해 번들 서비스 API를 호출하고 PHP 5 런타임과 동일한 기능 대부분에 액세스할 수 있습니다. PHP 5에서 사용할 수 있는 모든 기존 번들 서비스에 대해 2세대 PHP에 상응하는 서비스가 있지는 않습니다. 2세대 PHP 런타임에 사용할 수 있는 기존 번들 서비스 API의 전체 목록은 기존 번들 서비스 API 참조 문서를 참조하세요.
기존 번들 서비스와 비슷한 기능을 제공하는 Google Cloud 제품을 사용할 수도 있습니다. 이러한 Google Cloud제품은 관용적인 Google Cloud CLI 클라이언트 라이브러리를 제공합니다.
검색과 같이 Google Cloud에서 별도의 제품으로 제공하지 않는 기존 번들 서비스의 경우 서드 파티 제공업체나 다른 해결 방법을 사용할 수 있습니다. 번들되지 않은 서비스로 마이그레이션하는 방법에 대한 자세한 내용은 번들 서비스에서 마이그레이션을 참조하세요.
로컬에서 애플리케이션 실행
애플리케이션을 테스트하고 로컬에서 실행하려면 다음 안내를 따르세요.
App Engine 표준 환경에서 사용할 수 있는 2세대 PHP 런타임에 해당하는 PHP 버전을 로컬에 설치합니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[[["\u003cp\u003eThis guide provides instructions for migrating applications from the first-generation PHP runtime to the supported second-generation PHP runtimes on App Engine.\u003c/p\u003e\n"],["\u003cp\u003ePHP 5 reached its end of support on January 30, 2024, and while existing PHP 5 applications will continue to run, redeployment may be blocked; thus, migration to a supported runtime is strongly recommended.\u003c/p\u003e\n"],["\u003cp\u003eSecond-generation PHP runtimes offer benefits like up-to-date language features, improved portability, and reduced restrictions compared to the first generation.\u003c/p\u003e\n"],["\u003cp\u003eThere are key differences in memory and CPU usage, as well as request header handling between the first and second-generation PHP runtimes, which require adjustments to scaling configurations and application architecture.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eapp.yaml\u003c/code\u003e file structure has changed, with certain elements like \u003ccode\u003ethreadsafe\u003c/code\u003e and \u003ccode\u003eapi_version\u003c/code\u003e being deprecated, while \u003ccode\u003eentrypoint\u003c/code\u003e is a new addition, all non-static URL handlers must include \u003ccode\u003escript: auto\u003c/code\u003e to deploy successfully.\u003c/p\u003e\n"]]],[],null,["# Migrate from PHP 5.5 to the latest PHP runtime\n\nThis page covers instructions for migrating from the\n[first-generation to the second-generation](/appengine/docs/standard/runtimes)\nPHP runtimes. To upgrade your second-generation app to use the latest supported\nversion of PHP, see [Upgrade an existing application](/appengine/docs/standard/php-gen2/upgrade-php-runtime).\n\nPHP 5 has reached [end of support](/appengine/docs/standard/lifecycle/runtime-lifecycle#end_of_support)\non January 30, 2024. Your existing PHP 5 applications will continue\nto run and receive traffic. However, App Engine might block re-deployment of applications\nthat use runtimes [after their end of support date](/appengine/docs/standard/lifecycle/support-schedule#php).\nWe recommend that you migrate to the [latest supported runtime](/appengine/docs/standard/lifecycle/support-schedule#php)\nPHP runtime by using the guidelines in this page.\n\nMigrating to a supported second-generation PHP runtime lets you\nuse up-to-date language features and build apps that are more portable, with\nidiomatic code.\n\nCompatibility issues between PHP 5.5 and the second-generation PHP runtimes\n---------------------------------------------------------------------------\n\nThe official PHP documentation provides information on migrating from different\nPHP versions:\n\n- [Migrating from PHP 5.5.x to PHP 5.6.x](https://php.net/manual/en/migration56.incompatible.php)\n- [Migrating from PHP 5.6.x to PHP 7.0.x](https://php.net/manual/en/migration70.incompatible.php)\n- [Migrating from PHP 7.0.x to PHP 7.1.x](https://php.net/manual/en/migration71.incompatible.php)\n- [Migrating from PHP 7.1.x to PHP 7.2.x](https://php.net/manual/en/migration72.incompatible.php)\n- [Migrating from PHP 7.2.x to PHP 7.3.x](https://php.net/manual/en/migration73.incompatible.php)\n- [Migrating from PHP 7.3.x to PHP 7.4.x](https://php.net/manual/en/migration74.incompatible.php)\n- [Migrating from PHP 7.4.x to PHP 8.0.x](https://php.net/manual/en/migration80.incompatible.php)\n- [Migrating from PHP 8.0.x to PHP 8.1.x](https://php.net/manual/en/migration81.incompatible.php)\n\nKey differences between PHP 5.5 and the second-generation PHP runtimes\n----------------------------------------------------------------------\n\nThe following is a summary of the differences between the PHP 5.5 and the second-generation\nPHP runtimes in the App Engine standard environment:\n\n### Memory usage differences\n\nSecond-generation runtimes see a higher baseline of memory usage compared\nto first-generation runtimes. This is due to multiple factors, such as different\nbase image versions, and differences in how the two generations calculate memory\nusage.\n\nSecond-generation runtimes calculate instance memory usage as the sum of what an\napplication process uses, and the number of application files dynamically cached\nin memory. To avoid memory-intensive applications from experiencing instance\nshutdowns due to exceeding memory limits, upgrade to a larger\n[instance class](/appengine/docs/standard#instance_classes) with more memory.\n\n### CPU usage differences\n\nSecond-generation runtimes can see a higher baseline of CPU usage upon instance\ncold-start. Depending on an application's scaling configuration, this might have\nunintended side effects, such as, a higher instance count than anticipated if an\napplication is configured to scale based on CPU utilization. To avoid this\nissue, review and test application scaling configurations to ensure the number\nof instances are acceptable.\n\n### Request header differences\n\nFirst-generation runtimes allow request headers with underscores\n(e.g. `X-Test-Foo_bar`) to be forwarded to the application. Second-generation\nruntimes introduces Nginx into the host architecture. As a result of this\nchange, second-generation runtimes are configured to automatically remove\nheaders with underscores (`_`). To prevent application issues, avoid using\nunderscores in application request headers.\n\nMigrating your `app.yaml` file\n------------------------------\n\nYou must place a\n[front controller](https://wikipedia.org/wiki/Front_controller)\nto handle all routing in your application. For more information, see\n[Application startup](/appengine/docs/standard/php-gen2/runtime#app_startup).\n\nThe second-generation PHP runtimes don't allow the `script` handler element to be\ncustomized. The only valid value is `auto`, because all traffic is served using\nthe entrypoint command. All non-static URL handlers must include `script: auto`\nto deploy successfully.\n\nThe behavior of some elements in the `app.yaml` configuration file has been\nmodified:\n\nIf you use of any of the deprecated fields, there will be an error on app\ndeployment.\n\nFor more information, see the [`app.yaml` reference](/appengine/docs/standard/reference/app-yaml).\n\nReduced runtime restrictions\n----------------------------\n\nThe second-generation PHP runtimes have fewer restrictions compared to the PHP 5.5 runtime.\n\n- [Install third-party dependencies](/appengine/docs/standard/php-gen2/specifying-dependencies).\n- The runtime includes a [full filesystem](/appengine/docs/standard/php-gen2/runtime#filesystem_2).\n- Create background threads or processes that live beyond the scope of the request while the instance runs.\n- Use the [Google Cloud Client Library for PHP](https://googleapis.github.io/google-cloud-php/#/docs/google-cloud/v0.68.0/servicebuilder) to integrate apps with other Google Cloud services. For more information, see the [Installing the Google Cloud Client Library](/appengine/docs/standard/php-gen2/using-php-libraries) page.\n\nFor more information, see the [PHP runtime environment](/appengine/docs/standard/php-gen2/runtime).\n\nMigrate from the App Engine PHP SDK\n-----------------------------------\n\nTo reduce runtime migration effort and complexity, the App Engine standard environment lets you\n[access many of legacy bundled services and APIs in the second-generation PHP\nruntime](/appengine/docs/standard/php-gen2/services/access), such as Memcache.\nYour second-generation PHP app can call the bundled services APIs through the\nApp Engine SDK, and access most of the same capabilities as on the\nPHP 5 runtime. Not all the legacy bundled services available for PHP 5 have a\ncorresponding service in the second-generation PHP runtimes. For the full list of\nlegacy bundled services APIs available for the second-generation PHP runtimes, see the\n[legacy bundled services API references documentation](https://googlecloudplatform.github.io/appengine-php-sdk/2.1.0/index.html).\n\nYou also have the option to use Google Cloud products that offer\nsimilar capabilities as the legacy bundled services. These Google Cloud\nproducts provide idiomatic [Google Cloud CLI client library](https://github.com/googlecloudplatform/google-cloud-php).\nFor the legacy bundled services that are not available as separate products\nin Google Cloud, such as search, you can use third-party providers or\nother workarounds. To learn more about migrating to unbundled services, see\n[Migrating from bundled services](/appengine/migration-center/standard/services/migrating-services).\n\nRunning your application locally\n--------------------------------\n\nTo test your application and run it locally:\n\n1. Locally install a [version of PHP](/appengine/docs/standard/php-gen2/runtime#runtime_version)\n that corresponds to a second-generation PHP runtime\n available in the App Engine standard environment.\n\n2. Install a web server and use this to serve your app locally.\n\nFor example, start the HTTP server by running the following command: \n\n php -S localhost:8080\n\nThen, view your application in your web browser at \u003chttp://localhost:8080\u003e."]]
