PHP 런타임

PHP 런타임은 애플리케이션 코드 및 종속 항목을 설치한 후 가변형 환경에서 해당 애플리케이션을 실행하는 소프트웨어 스택입니다.

PHP 버전

PHP 8.4는 빌드팩을 사용합니다. 지원되는 PHP 버전의 전체 목록과 해당 Ubuntu 버전은 런타임 지원 일정을 참조하세요.

지원되는 PHP 버전을 사용하려면 다음을 수행해야 합니다.

gcloud CLI 버전 420.0.0 이상을 설치합니다. gcloud components update 명령어를 실행하여 CLI 도구를 업데이트할 수 있습니다. 설치된 버전을 보려면 gcloud version 명령어를 실행하면 됩니다.
app.yaml 파일에 runtime_config 및 operating_system 설정을 포함하여 운영체제를 지정합니다.
app.yaml 파일에서 애플리케이션의 문서 루트를 선언합니다.
```
  runtime: php
  env: flex

  runtime_config:
      operating_system: "ubuntu22"
      document_root: "web"
```
프로젝트 루트(.) 디렉터리를 문서 루트로 지정할 수 있지만 document_root 설정에 하위 디렉터리를 사용하는 것이 좋습니다.

소스 코드는 루트 디렉터리(/) 대신 /workspace 디렉터리에 있습니다. 구성을 재정의하면 NGINX 또는 supervisor 프로세스가 이 디렉터리의 구성 파일을 참조합니다. 해당 참조를 업데이트하려면 다음을 수행해야 합니다.
- NGINX 구성의 모든 include 문을 /etc/nginx가 아닌 /workspace를 기준으로 업데이트하세요.
- gzip_params와 같은 일부 파일은 포함되지 않습니다. 이러한 파일을 참조하려면 자체 파일 또는 GitHub의 사본을 포함합니다. mime.types 및 fastcgi_params와 같은 파일은 /etc/nginx 디렉터리에서 사용할 수 있습니다.
- nginx-plus-module-ndk와 같은 일부 NGINX 모듈이 설치되지 않았습니다. $docroot 값을 설정하거나 NGINX 구성 파일에 수동으로 값을 추가합니다.
선택사항으로 런타임 버전을 지정할 수 있는 방법은 다음과 같습니다.
- app.yaml에 runtime_version 설정을 포함합니다. runtime_version 설정이 지정되지 않으면 기본적으로 최신 PHP 버전이 사용됩니다.
  - Ubuntu 22에서 PHP 8.4를 지정하려면 다음 안내를 따르세요.
```
runtime: php
env: flex

runtime_config:
    operating_system: "ubuntu22"
    runtime_version: "8.4"
    document_root: .
```
  - Ubuntu 22에서 지원되는 최신 PHP 버전을 지정하려면 다음을 실행합니다.
```
  runtime: php
  env: flex

  runtime_config:
      operating_system: "ubuntu22"
      document_root: .
```
- composer.json 파일에 PHP 버전을 포함합니다.
```
{
    "require": {
        "php": "8.4.*"
    }
}
```
  MAJOR, MINOR, PATCH를 사용하여 PHP 버전을 지정하는 경우 PATCH를 *로 바꿉니다. MAJOR.MINOR.* 형식을 사용합니다. PHP 런타임은 정기적으로 최신 출시 버전으로 업데이트되며 한 번에 하나의 출시 버전만 지원하므로 출시 버전을 지정하면 오류가 발생할 수 있습니다.
자세한 내용은 app.yaml 참조를 확인하세요.

이전 런타임 버전

PHP 버전 7.3 이하를 사용하려면 다음을 수행해야 합니다.

애플리케이션의 문서 루트를 선언합니다. app.yaml 파일에서 다음을 실행하면 됩니다.
```
runtime: php
env: flex
api_version: 1

runtime_config:
  document_root: .
```
프로젝트 루트(.) 디렉토리를 문서 루트로 지정할 수 있지만 document_root 설정에 하위 디렉터리를 사용하는 것이 좋습니다.
새 버전의 PHP를 사용할 수 있게 되면 애플리케이션이 자동으로 업그레이드되지 않도록 composer.json 파일에 PHP 버전을 지정합니다.
```
{
    "require": {
        "php": "7.3.*"
    }
}
```
MAJOR, MINOR, PATCH를 사용하여 PHP 버전을 지정하는 경우 PATCH를 `*`로 바꿉니다. MAJOR.MINOR.* 형식을 사용합니다. PHP 런타임은 정기적으로 최신 출시 버전으로 업데이트되며 한 번에 하나의 출시 버전만 지원하므로 출시 버전을 지정하면 오류가 발생할 수 있습니다.

기타 PHP 런타임 지원

지원되지 않는 PHP 버전을 사용해야 하는 경우에는 커스텀 런타임을 만들고 필요한 PHP 버전의 유효한 기본 이미지를 선택하면 됩니다.

Google에서 제공하는 기본 이미지나 Docker PHP 기본 이미지는 커스텀 런타임 빌드를 참조하세요.

NGINX 맞춤설정

커스텀 구성 파일을 정의하려면 프로젝트의 루트 디렉터리에 nginx-app.conf 파일을 포함합니다.

기본적으로 프레임워크 프런트 컨트롤러는 index.php 파일을 사용합니다. 프로젝트에 맞춰 이 값을 다른 값으로 변경해야 할 수도 있습니다. 예를 들어 Symfony 프레임워크는 index.php 대신 app.php를 사용합니다. app.yaml 파일의 runtime_config 섹션에서 파일 이름을 변경할 수 있습니다.

runtime: php
env: flex

runtime_config:
  operating_system: "ubuntu22"
  document_root: .
  front_controller_file: app.php

버전 7.3 이하의 경우 nginx-app.conf 구성 파일이 기본 NGINX 구성 파일의 서버 섹션에 포함됩니다. 예를 들어 기본 구성 php-app.conf 파일에는 다음이 포함됩니다.

location / {
# try to serve files directly, fallback to the front controller
try_files $uri /$front_controller_file$is_args$args;
}

커스텀 구성 파일을 정의하려면 프로젝트의 루트 디렉터리에 nginx-app.conf 파일을 만듭니다. 런타임은 사용자가 제공한 파일로 기본 파일을 대체합니다.

runtime: php
env: flex

runtime_config:
  document_root: .
  front_controller_file: app.php

OPcache

php.ini 파일에서 OPcache를 사용 설정합니다. OPcache를 구성하는 방법은 공식 문서를 참조하세요.

OPcache를 중지하려면 php.ini 파일을 만들거나 다음 줄을 사용하여 수정합니다.

opcache.enable=0

종속 항목

런타임에서는 애플리케이션 소스 디렉터리에서 composer.json 파일을 찾아 composer를 사용해 애플리케이션을 시작하기 전에 종속 항목을 설치합니다. 패키지 선언 및 관리에 대한 자세한 내용은 PHP 라이브러리 사용을 참조하세요.

PHP 확장 프로그램 사용

다음 PHP 확장 프로그램은 시스템에 사전 설치 및 사용 설정되어 있습니다.

지원되는 PHP 버전

php.ini 파일을 사용하여 다음 확장 프로그램을 사용 설정할 수 있습니다.

v7.3 이하

다음 PHP 확장 프로그램은 기본적으로 사용 중지됩니다. php.ini 파일을 사용하여 다음 확장 프로그램을 사용 설정할 수 있습니다.

amqp
APM(7.0 이상)
BCMath
Bitset
Calendar
Cassandra
couchbase (7.0+)
ds (7.0+)
eio
ev
event
Exif
FTP
GD(PNG, JPEG, FreeType 지원 포함)
gettext
gRPC
hprose
igbinary
intl
ImageMagick
jsond
krb5
lua (7.0+)
LZF
memprof
mongodb
MySQL (5.6)
oauth
OpenCensus
PCNTL
Phalcon (5.6, 7.0)
pq
protobuf
rdkafka
Redis
SeasLog
Shmop
SOAP
SQLite3
SQLite(PDO)
stomp
swoole
sync
tcpwrap
timezonedb
v8js (7.0+)
vips (7.0+)
XMLRPC
XSL
yaconf (7.0+)
yaf
yaml

확장 프로그램을 사용 설정하려면 extension 지시어로 애플리케이션의 루트에 php.ini 파일을 추가합니다.

; Enable the Redis extension
extension=redis.so

; Enable the OpenTelemetry extension (must be in an opentelemetry section)
[opentelemetry]
extension=opentelemetry.so

또는 composer.json에 require를 추가하여 확장명을 사용 설정할 수도 있습니다.

{
    "require": {
        "ext-redis": "*"
    }
}

이 패키지를 사용하면 가장 널리 사용되는 PHP 확장을 설치할 수 있습니다. 운영체제 수준의 종속 항목이 추가로 필요한 애플리케이션인 경우 PHP 런타임을 확장하거나 커스텀 런타임을 사용하여 적절한 패키지를 설치합니다.

HTTPS 및 전달 프록시

App Engine은 부하 분산기에서 HTTPS 연결을 종료하고 요청을 애플리케이션에 전달합니다. NGINX 서버는 HTTPS를 통해 요청할 때 HTTPS 환경 변수($_SERVER["HTTPS"])를 on으로 설정하도록 구성됩니다.

일부 애플리케이션은 사용자 IP 주소도 확인해야 합니다. 사용자 IP 주소는 표준 X-Forwarded-For 헤더에서 제공됩니다.

사용 중지된 함수

다음 함수는 php.ini의 disable_functions 지시문으로 중지됩니다.

exec
passthru
proc_open
proc_close
shell_exec
show_source
symlink
system

위 함수 중 하나가 필요한 경우 애플리케이션 루트에 php.ini 파일을 추가하고 disable_functions 지시문을 변경합니다. 또는 app.yaml의 runtime_config 섹션에 있는 whitelist_functions를 쉼표로 구분된 함수 목록이 허용되도록 설정합니다.

PHP 버전 7.3 이하에서는 시뮬레이션 모드로 실행되도록 기본적으로 Suhosin Security 확장 프로그램이 설치 및 구성됩니다. 시뮬레이션 모드는 위험할 가능성이 있는 함수의 사용을 로깅하며 Cloud Logging UI에 표시됩니다. 시뮬레이션 모드를 사용 중지하면 잠재적으로 위험한 함수를 사용할 때 애플리케이션이 종료됩니다. 이 추가 보안 기능을 사용하려면 다음 옵션을 사용하여 프로젝트 루트에 php.ini를 추가합니다.

; Prevent the use of potentially dangerous functions rather than logging them
suhosin.simulation = Off

패치가 적용된 함수

parse_str 함수는 패치되고 두 번째 파라미터는 필수입니다. 파라미터 하나만 사용하여 parse_str을 호출할 경우 경고가 발생하고 함수가 호출되지 않습니다.

사용 가능한 구성

runtime_config 섹션에 다음 구성을 포함할 수 있습니다.

이름	설명	기본값
`document_root`	nginx와 PHP에 `DOCUMENT_ROOT`을 지정합니다. 프로젝트 루트 디렉토리의 상대 경로를 사용해야 합니다.	필수 입력란
`composer_flags`	이 키를 사용하여 일부 작성기 플래그를 재정의할 수 있습니다.	`--no-dev --prefer-dist`
`enable_stackdriver_integration`	버전 7.3 이하에서만 지원됩니다. true로 설정하면 런타임에 Google Cloud Observability 통합이 자동으로 사용 설정됩니다. 이 구성에는 `google/cloud` 패키지 v0.33 이상이 필요합니다.	거짓
`skip_lockdown_document_root`	버전 7.3 이하에서만 지원됩니다. 기본적으로 런타임은 `document_root` 디렉토리 아래의 모든 파일과 디렉토리에 엄격한 읽기 전용 권한을 설정합니다. `true`로 설정하면 런타임에서 권한 변경을 건너뜁니다.	거짓
`whitelist_functions`	버전 7.3 이하에서만 지원됩니다. 허용 목록에 추가할 쉼표로 구분된 함수 이름 목록입니다.	빈 문자열
`front_controller_file`	디렉터리 액세스를 위한 기본 PHP 파일 이름입니다.	`index.php`
`nginx_conf_http_include`	기본 nginx 구성 파일의 `http` 섹션에 포함될 부분 nginx 구성 파일의 파일 이름입니다.	`nginx-http.conf`
`nginx_conf_include`	기본 nginx 구성 파일의 `server` 섹션에 포함될 부분 nginx 구성 파일의 파일 이름입니다.	`nginx-app.conf`
`nginx_conf_override`	사용자가 제공한 nginx 구성 파일의 파일 이름이며, nginx 기본 구성 파일로 사용됩니다.	`nginx.conf`
`php_fpm_conf_override`	사용자가 제공한 php-fpm 구성 파일의 파일 이름이며, `[app]` 섹션의 하단에 포함되어 기존 구성을 덮어씁니다.	`php-fpm.conf`
`php_ini_override`	사용자가 제공한 PHP 구성 파일의 파일 이름입니다.	`php.ini`
`supervisord_conf_addition`	사용자가 제공한 supervisord 구성 파일의 파일 이름이며, 기본 supervisord 구성 파일에 포함됩니다.	`additional-supervisord.conf`
`supervisord_conf_override`	사용자가 제공한 supervisord 구성 파일의 파일 이름이며, 기본 supervisord 구성 파일을 재정의합니다.	`supervisord.conf`

app.yaml 파일의 build_env_variables 섹션에서 NGINX_SERVES_STATIC_FILES 환경 변수를 설정하여 Nginx가 일치하는 URI의 정적 파일을 제공할지 여부를 제어할 수 있습니다.

runtime: php
env: flex

runtime_config:
  document_root: "web"
  operating_system: "ubuntu22"

build_env_variables:
  NGINX_SERVES_STATIC_FILES: true

PHP 런타임에서 supervisord 구성

App Engine 가변형 환경에서는 supervisord를 사용하여 프로세스를 관리합니다. 기본적으로 supervisord는 nginx 및 php-fpm을 실행하여 PHP 웹 애플리케이션을 실행합니다. 그러나 일부 애플리케이션은 외부 프로세스를 실행해야 합니다. 또한 이러한 응용 프로그램은 때로는 nginx 나 php-fpm을 필요로 하지 않습니다.

supervisord에서 관리하는 프로세스를 추가하려면 additional-supervisord.conf라는 파일을 프로젝트 루트 디렉터리에 추가합니다. 다음은 이러한 구성 파일 콘텐츠의 예시입니다.

[program:quote-updater]
command = php %(ENV_APP_DIR)s/worker.php
stdout_logfile = /dev/stdout
stdout_logfile_maxbytes=0
stderr_logfile = /dev/stderr
stderr_logfile_maxbytes=0
user = www-data
autostart = true
autorestart = true
priority = 5
stopwaitsecs = 20

nginx 및 php-fpm을 프로세스로 바꾸려면 supervisord.conf라는 파일을 프로젝트 루트 디렉터리에 추가합니다. 다음은 이러한 구성 파일 콘텐츠의 예시입니다.

[supervisord]
nodaemon = true
logfile = /dev/null
logfile_maxbytes = 0
pidfile = /var/run/supervisord.pid

[program:react-server]
command = php %(ENV_APP_DIR)s/index.php
stdout_logfile = /dev/stdout
stdout_logfile_maxbytes=0
stderr_logfile = /dev/stderr
stderr_logfile_maxbytes=0
user = www-data
autostart = true
autorestart = true
priority = 5
stopwaitsecs = 20

런타임 확장

App Engine 가변형 환경 PHP 런타임을 사용하여 커스텀 런타임을 만들 수 있습니다. 자세한 내용은 PHP 런타임 맞춤설정을 참조하세요.

환경 변수

런타임 환경에서 설정되는 환경 변수는 다음과 같습니다.

환경 변수	설명
`GAE_INSTANCE`	현재 인스턴스의 이름입니다.
`GAE_MEMORY_MB`	애플리케이션 프로세스에서 사용할 수 있는 메모리 양입니다.
`GAE_SERVICE`	애플리케이션의 `app.yaml` 파일에 지정된 서비스 이름이거나 서비스 이름이 지정되지 않은 경우 `default`로 설정됩니다.
`GAE_VERSION`	현재 애플리케이션의 버전 라벨입니다.
`GOOGLE_CLOUD_PROJECT`	애플리케이션과 연결된 프로젝트 ID로, Google Cloud 콘솔에 표시됩니다.
`PORT`	HTTP 요청을 수신할 포트입니다.

app.yaml로 추가 환경 변수를 설정할 수 있습니다.

메타데이터 서버

애플리케이션의 각 인스턴스에서 Compute Engine 메타데이터 서버를 사용해 호스트 이름, 외부 IP 주소, 인스턴스 ID, 커스텀 메타데이터, 서비스 계정 정보 등의 인스턴스 관련 정보를 쿼리할 수 있습니다. App Engine에서는 인스턴스마다 커스텀 메타데이터를 설정할 수 없지만 프로젝트 전체의 커스텀 메타데이터를 설정한 후 App Engine 및 Compute Engine 인스턴스에서 읽을 수 있습니다.

이 예시 함수는 메타데이터 서버를 사용해 인스턴스의 외부 IP 주소를 가져옵니다.

function get_external_ip_using_google_cloud()
{
    $metadata = new Google\Cloud\Core\Compute\Metadata();
    $externalIp = $metadata->get(
        'instance/network-interfaces/0/access-configs/0/external-ip');

    return $externalIp;
}

function get_external_ip_using_curl()
{
    $url = 'http://metadata.google.internal/computeMetadata/v1/' .
        'instance/network-interfaces/0/access-configs/0/external-ip';

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Metadata-Flavor: Google'));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    return curl_exec($ch);
}