最終更新日 2024年05月30日(木)

このドキュメントでは、PHP アプリケーションの認識と実行に関連した Heroku の一般的な動作について説明します。

アクティベーション

Heroku の PHP サポートがアプリケーションに適用されるのは、アプリケーションに composer.json​ という名前のファイルがルートディレクトリにある場合だけです。アプリケーションに Composer​ 依存関係がない場合でも、PHP アプリケーションとして認識されるために少なくとも空​ ({}​) の composer.json​ を含んでいなければなりません。

Heroku は PHP アプリケーションを認識すると、それに応じてプッシュ中に応答します。

$ git push heroku main
-----> PHP app detected
…

composer.json​ があらゆる種類の依存関係を require​ セクションで指定すると、対応する composer.lock​ が composer update​ を実行することで生成されますが、リポジトリにもコミットされなければなりません。そうしないと、プッシュは拒否されます。これにより、Heroku がインストールする依存関係が他のあらゆる環境の依存関係と全く同じになります。詳細な説明は、PHP デプロイガイドの「依存関係の管理」セクション​を参照してください。

PHP ランタイム

Heroku では、公式 PHP​ ランタイムを使用してご使用のアプリケーションを実行できます。

サポートされているバージョン

Heroku の PHP サポートは、PHP 8.1​、PHP 8.2​、PHP 8.3​ シリーズの利用可能な最新リリースを使用するアプリケーションにまで及びます。

Heroku プラットフォームでの PHP リリースシリーズのサポートに適用される PHP Group のサポートポリシー​では、一般に初期 x.y.0 バージョンの後 2 年間のアクティブアップデートがあり、その後 1 年間のセキュリティアップデートがあります。

PHP リリースシリーズがサポート終了になると、Heroku によってサポートされなくなりますが、その最新リリースは、顧客がアプリケーションを新しい PHP バージョンにアップグレードできるようにビルドで利用可能なままになります。

利用可能なバージョン

次の表に、各スタック​のビルドで利用可能なランタイムバージョンの一覧を示します。

ランタイムの設定

すべての PHP ランタイムがそれぞれのリリースの php.ini-production​ ファイルをベース php.ini​ 設定​として使用します。

上記にもかかわらず、次の INI ディレクティブは Heroku 固有の値に設定されています。

• date.timezone​ を UTC​ に設定
• error_reporting​ を以下に設定
  • E_ALL & ~E_STRICT​ (8.1 より前の PHP バージョン)
  • E_ALL & ~E_STRICT & ~E_DEPRECATED​ (PHP 8.1 以降)
• expose_php​ を Off​ に設定
• session.sid_length​ を 32​ に設定 (PHP 7.1 以降)
• short_open_tag​ を On​ に設定
• user_ini.cache_ttl​ を 86400​ に設定
• variables_order​ を EGPCS​ に設定

さらに、PHP ランタイムでは常に OPcache​ が有効になっているためパフォーマンスが向上しており、次の設定変更が Heroku の dyno の固有特性に合わせて最適化されています。

• opcache.enable_cli​ を 1​ に設定
• opcache.validate_timestamps​ を 0​ に設定

PHP CLI

php​ CLI 実行可能ファイルの memory_limit​ PHP INI ディレクティブは、PHP バージョン 7.2 以降について完全に利用可能な dyno メモリにデフォルトで設定されます。つまり、たとえば php​ コマンドを使用する Worker dyno は、デフォルトの PHP INI の値 128M​ の代わりにこのメモリ制限を使用します。

デフォルトランタイム

アプリケーションで composer.json​ を使用しない場合や、composer.lock​ でパッケージ php​ の要件がどの依存パッケージにも含まれていない場合、アプリケーションは heroku-20​ スタックでは利用可能な最新バージョンの PHP 7 または PHP 8 を選択し、その他のすべてのスタックでは PHP 8 を選択します。

ランタイムを選択する

使用するランタイムを Composer Platform Packages​ composer.json​ を介して選択できます。プッシュ時に、Heroku は必要な情報を composer.lock​ から (ある場合) 読み取り、ない場合は composer.json​ に戻ります。

たとえば、次の composer.json​ が Heroku に使用するよう指示するのは最新バージョンの PHP 8 (8.2.0 以降) で、PHP 9 ではありません。

{
  "require": {
    "php": "^8.2.0"
  }
}

Heroku は、解決済でインストールされるバージョンをプリントします。

-----> Installing platform packages...
       - php (8.2.13)

不明なバージョンやサポートされていないバージョンを指定するとエラーになり、代替えのバージョンのリストが表示されます。

PHP

「php​」を composer.json​ の require​ セクションで依存関係として指定して、PHP をランタイム (たとえば PHP 8.1 以降) として使用します。

{
  "require": {
    "php": "^8.1.0"
  }
}

次に、新しい要件が composer.lock​ に「凍結」されていることを確認するため、次を実行します。

$ composer update

最後に、両方のファイルを git add​ および git commit​ することを忘れないでください。

アップグレード

ランタイムバージョン依存関係を明記していないアプリケーションをデプロイすると、当時の最新バージョンの PHP が使用されます。ご使用のアプリケーションは、より新しいバージョンの PHP がある場合、次のデプロイ時に自動的にアップグレードされます。

ご使用のアプリケーションがランタイムバージョン依存関係を明記している場合、バージョン制約に適合する最新のバージョンがインストールで選択されます。

拡張機能

利用可能なビルトイン拡張機能

次の表に、PHP にバンドルされているどのビルトイン拡張機能が PHP の各リリースシリーズで利用できるか、問題の拡張機能がデフォルトでロードされるかどうか、または composer.json​ 経由で明示的に有効化される​必要があるかどうかの一覧を示します。

利用可能なサードパーティ拡張機能

次の表に、PHP の各リリースで利用できるサードパーティ拡張機能の一覧を示します。これらは PHP ランタイムとは別々に配布されているため、これらのバージョンも一覧で示しています。これらはデフォルトでロードされないため、composer.json​ 経由で明示的に有効化​する必要があります。

オプションの拡張機能を使用する

使用したいオプションの拡張機能を、composer.json​ から Composer Platform Packages​ を使用して明記できます。パッケージ名で上の拡張機能のリストの中の好きな識別子の前に「ext-​」を付けるだけです。

たとえば、オプションでバンドルされている拡張機能 bcmath​ や GMP​、サードパーティの Memcached​、サードパーティの MongoDB​ の特定のバージョンを有効にする場合、以下のようになります。

{
    "require": {
        "ext-bcmath": "*",
        "ext-gmp": "*",
        "ext-memcached": "*",
        "ext-mongodb": "^1.19.0"
    }
}

次に、新しい要件が composer.lock​ に「凍結」されていることを確認するため、次を実行します。

$ composer update

最後に、両方のファイルを git add​ および git commit​ することを忘れないでください。

$ composer update --ignore-platform-reqs

次のプッシュ時に、Heroku が対応する PHP 拡張機能をインストールして有効にします。

-----> Installing platform packages...
       - php (8.2.13)
       - ext-bcmath (bundled with php)
       - ext-mcrypt (bundled with php)
       - ext-mongodb (1.17.0)
       - ext-memcached (3.2.0)
       - apache (2.4.58)
       - nginx (1.24.0)

userland パッケージによって “provide” 済みの拡張機能の扱い

さまざまな Symfony Polyfill​ などの特定の Composer パッケージは、そのパッケージメタデータ内でネイティブ PHP 拡張機能を provide​ 済みとして宣言します (また、その拡張機能の機能を、純粋に PHP コードを使用して部分的または完全に実装します)。それにより、Composer は依存関係の解決中に、それらを実際のネイティブ PHP 拡張機能の可能性のある置き換えであると見なすようになります。

ビルド中に、これらの “polyfill” 宣言は、Composer がパッケージのインストール​に適用するのとまったく同じルールを使用して、プラットフォームパッケージのインストール時に Heroku によって遵守されます。

つまり、symfony/polyfill-mbstring​ では ext-mbstring​ が provide​ 済みとして宣言されているため、composer.lock​ 内に symfony/polyfill-mbstring​ パッケージも存在する場合は、たとえば ext-mbstring​ に対する composer.json​ (または何らかの依存関係) の要件があってもネイティブ ext-mbstring​ 拡張機能はインストールされません。

-----> Installing platform packages...
       - php (8.1.2)
       - apache (2.4.52)
       - composer (2.2.5)
       - nginx (1.20.2)

最大のパフォーマンスと互換性のために、プラットフォームパッケージの依存関係の最初の解決がこの方法で完了した後、Heroku の PHP サポートでは、userland パッケージが provide​ 済みとして宣言しているすべての拡張機能のネイティブバージョンをインストールしようと試みます。

-----> Installing platform packages...
       - php (8.1.2)
       - apache (2.4.52)
       - composer (2.2.5)
       - nginx (1.20.2)
       NOTICE: detected userland polyfill packages for PHP extensions
       NOTICE: now attempting to install native extension packages
       Installing extensions provided by symfony/polyfill-mbstring:
       - ext-mbstring (bundled with php)

これらのインストールの試みは、問題の拡張機能が Heroku で使用できない可能性があるため、または選択された PHP バージョンのために、必ずしも成功するとは限りません。

-----> Installing platform packages...
       - php (8.1.2)
       - apache (2.4.52)
       - composer (2.2.5)
       - nginx (1.20.2)
       NOTICE: detected userland polyfill packages for PHP extensions
       NOTICE: now attempting to install native extension packages
       Installing extensions provided by phpseclib/mcrypt_compat:
       NOTICE: no suitable native version of ext-mcrypt available

特に、すでに解決されているプラットフォームパッケージは何も変更されません。インストールされている PHP バージョンでネイティブバリアントが使用できない場合、このような拡張機能を使用できるようになる PHP バージョンへのダウングレードは実行されません。その低い PHP バージョンがその他のすべての依存関係によって許可される場合でも同様です。

この動作により、userland polyfill パッケージは、PHP にバンドルされなくなった拡張機能の置き換えとして機能している (たとえば、上の例で phpseclib/mcrypt_compat​ が ext-mcrypt​ に対して行っているように) 場合など、必要に応じてその目的を確実に正しく果たすことができます。その一方で同時に、最大のパフォーマンスと互換性のために可能な場合は常に、問題のネイティブ PHP 拡張機能が確実にインストールされるようになります。

設定をカスタマイズする

PHP

PHP マニュアルの指示に従って​プロジェクトに置かれたあらゆる .user.ini​ ファイルが、メイン php.ini​ の後にロードされます。これらを使用して、PHP_INI_ALL​、PHP_INI_USER​ および PHP_INI_PERDIR​ のコンテキストで認められたあらゆるディレクティブを設定できます。

この詳細や PHP ランタイムの設定をカスタマイズする他の方法については、対応する Dev Center の記事​を参照してください。

動作のビルド

依存関係のインストール

以下のコマンドはデプロイ時に実行されて、依存関係を解決します。ただし composer.json​ が空で composer.lock​ が存在しない場合を除きます。

$ composer install --no-dev --prefer-dist --optimize-autoloader --no-interaction

インストールしたバージョンの Composer はプリントされるので、インストールが開始される前に参照できます。ビルドは、アプリケーションの composer.lock​ と互換性がある Composer バージョン (1.x、2.2.x LTS、または 2.3+) を使用して実行されます。Composer のそれぞれのバージョンは、コマンド名 composer​ でアプリの実行時に $PATH​ で参照できます。

後続のデプロイでのパッケージのインストールを高速化するために、アプリケーションの Composer キャッシュディレクトリはビルド間で保持されます。

使用可能な Composer バージョン

次の Composer バージョンが現在利用できます。

カスタムコンパイルステップ

アプリケーションがビルド中に実行したい追加のコンパイルステップを標準の post-install-cmd​ Composer スクリプト​ (たとえばアセットコンパイルまたはキャッシュプレウォーム手順) の一部にすべきでない場合、compile​ カスタムコマンド​ (composer.json​ にある場合) が次のコマンドを使用して実行されます。

$ composer compile --no-dev --no-interaction

composer.json で定義されているそうしたカスタムスクリプトコマンドはいずれも、1 つの文字列か、実行する複数のコマンドの配列です。​例:

{
  "scripts": {
    "compile": [
      "@php app/console assetic:dump --env=prod --no-debug",
      "MyVendor\\MyClass::postDeployComposerCallback"
    ]
  }
}

プライベートリポジトリ

Private Packagist​ のようなプライベートリポジトリや、認証を必要とするソースからのパッケージ (プライベートの GitHub リポジトリのパッケージなど) を使用するには、Composer を認証詳細 (一般にはプロバイダまたはサービスにより生成されたトークン) とともに指定しなければなりません。

開発マシンで、これらは一般に Composer により auth.json​ に保存されます。しかし Heroku では、このような秘密情報は環境変数として保存されます​。COMPOSER_AUTH​環境変数は自動的に Composer から読み込まれます​。その JSON 構造は auth.json​ と同じです。

以下のエントリは、JSON ドキュメントで最上位の鍵として認められています。

• http-basic
• github-oauth
• gitlab-oauth
• gitlab-token
• bitbucket-oauth

各エントリにはドメインのハッシュが鍵として、認証詳細が値として含まれます。認証詳細構造は、上記の各ソースに固有のものであり、ドキュメントで説明されています。

たとえば、Private Packagist​ アカウントの認証詳細を保管するには、COMPOSER_AUTH​ 変数を heroku config:set​ と http-basic​ 詳細を使用して設定します (“YOURTOKEN” を生成された実際のトークン Private Packagist に置き換えます)。

$ heroku config:set COMPOSER_AUTH='{"http-basic":{"repo.packagist.com":{"username":"token","password":"YOURTOKEN"}}}'

もう 1 つの例を挙げると、プライベート GitHub リポジトリのコードを Composer 依存関係として使用​しているとき、個人用の OAuth トークン​を認証で設定できます。新しい Token を作成した後で​、それを Heroku で設定できます (“YOURTOKEN” を生成された実際のトークン GitHub に置き換えます)。

$ heroku config:set COMPOSER_AUTH='{"github-oauth":{"github.com":"YOURTOKEN"}}'

複数の認証詳細セットを組み合わせて 1 つのドキュメントにして、たとえばプライベート GitHub リポジトリとプライベート BitBucket リポジトリの両方を使用することもできます。

$ heroku config:set COMPOSER_AUTH='{
    "github-oauth": {"github.com": "YOURTOKEN"},
    "bitbucket-oauth": {"bitbucket.org": {
        "consumer-key": "YOURKEY", "consumer-secret": "YOURSECRET"}
    }
}'

Composer 設定

Composer の次の設定は、便宜上、環境変数を使用して自動的に設定されます。

• $COMPOSER_MEMORY_LIMIT​ はデフォルトで、利用可能な dyno メモリに設定されます。
• $COMPOSER_MIRROR_PATH_REPOS​ はデフォルトで 1​ に設定されます。
• $COMPOSER_NO_INTERACTION​ はデフォルトで 1​ に設定されます。

ランタイムの動作

$PATH​ 環境変数には、アプリケーションがランタイム時に機能するために必要なすべてのパスが含まれています。Composer bin-dir​ は便宜上 $PATH​ に付け加えられています。

PHP-FPM 設定

PHP-FPM は、dyno サイズと設定された PHP memory_limit​ に基づいて、適切な数の Worker プロセスを自動的に生成するよう設定されます。詳細は、「Optimizing PHP Application Concurrency​」(PHP アプリケーションの並列性の最適化) を参照してください。

タイムアウト

リクエストが Heroku ルーターのリクエストタイムアウトに達した​場合であっても、PHP-FPM プロセスは、外部タイムアウトが発生するまで実行を継続することがあります。これにより PHP-FPM プロセスが拘束されることがあり、他の受信リクエストに応答しなくなる可能性があります。

PHP 7.4 以降を使用するアプリケーションの場合、PHP-FPM は次の動作を行います。

• 3 秒 (request_slowlog_timeout​ ディレクティブ) 以上かかっているリクエストのバックトレースをログに記録する
• 実行時間が 30 秒 (request_terminate_timeout​ ディレクティブ) を超過したことによりタイムアウトした​可能性があるリクエストを終了する。

PHP-FPM の設定を調節して、​ 次の (あるいはその他の) 設定を変更することができます。

Composer 設定

Composer の次の設定は、便宜上、環境変数を使用して自動的に設定されます。

• $COMPOSER_MEMORY_LIMIT​ はデフォルトで、利用可能な dyno メモリに設定されます。
• $COMPOSER_MIRROR_PATH_REPOS​ はデフォルトで 1​ に設定されます。
• $COMPOSER_NO_INTERACTION​ はデフォルトで 1​ に設定されます。
• $COMPOSER_PROCESS_TIMEOUT​ はデフォルトで 0​ に設定されます。

Web サーバー

Apache HTTPD 2.4​ と Nginx​ が Heroku で専用 Web サーバーとしてサポートされています。テスト目的のため、ユーザーは PHP のビルトイン Web サーバーを使用することもありますが、これは推奨していません。

“Web” dyno タイプに Procfile​ エントリがないとき、Apache Web サーバーは PHP ランタイムと併用されます。

次の Web サーバーのバージョンがサポートされており、ビルド中に自動的にインストールされます。

Apache

Apache は、FastCGI 経由で mod_proxy_fcgi​ を使用して、PHP-FPM とインターフェース接続します。

Apache を PHP-FPM と一緒に正しいすべての設定で起動するには、heroku-php-apache2​ スクリプトを使用します。

web: heroku-php-apache2

デフォルトでは、プロジェクトのルートフォルダはドキュメントルート​として使用されます。サブディレクトリを使用するには、サブフォルダの名前 (たとえば “public_html”) を引数としてブートスクリプトに渡します。

web: heroku-php-apache2 public_html

正規の .htaccess​ ファイルを使用して Apache の動作 (URL 書き換え​など) をカスタマイズできます。この詳細や Apache の設定をカスタマイズする他のオプションについては、該当の Dev Center の記事​を参照してください。

Nginx

Nginx は、FastCGI 経由で PHP-FPM とインターフェース接続します。

Nginx を PHP-FPM と一緒に正しいすべての設定で起動するには、heroku-php-nginx​ スクリプトを使用します。

web: heroku-php-nginx

デフォルトでは、プロジェクトのルートフォルダはドキュメントルート​として使用されます。サブディレクトリを使用するには、サブフォルダの名前 (たとえば “public_html”) を引数としてブートスクリプトに渡します。

web: heroku-php-nginx public_html

Nginx の設定をカスタマイズする様々な方法の詳細は、該当の Dev Center の記事​を参照してください。

PHP ビルトイン Web サーバー

テスト目的のため、PHP のビルトイン Web サーバー​を起動するには、php -S 0.0.0.0:$PORT​ を Procfile​ の “web” でエントリとして使用します。

web: php -S 0.0.0.0:$PORT

代わりのドキュメントルートを渡すか、いわゆるルータースクリプトを使用してリクエストを処理することもできます。詳細は、PHP プロジェクトのビルトイン Web サーバーに関するドキュメント​を参照してください。