PHP 拡張機能の管理

最終更新日 2025年03月17日(月)

Heroku は PHP アプリケーションで使用できるさまざまな組み込みおよびサードパーティの拡張機能を提供します。お使いのアプリのオプションの拡張機能を使用することもできます。この記事では、オプションの拡張機能を宣言する方法を説明します。

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

使用するオプションの拡張機能を、Composer Platform Packages​ を使用して composer.json​ から宣言できます。パッケージ名で、上の拡張機能のリスト内の任意の識別子に「ext-​」という接頭辞を付けるだけです。

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

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

PHP にバンドルされている拡張機能を指定するときは、「*​」をバージョンセレクタとして使用することをお勧めします。これは、そのバージョン番号が一致しない可能性があるためです (しばしばバージョンが「0」として報告されます)。

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

$ composer update

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

お使いのコンピューターでローカルに使用できる希望の拡張機能がない場合は、composer.json​ の要件を満たすことができないため、composer update​ ステップは失敗します。 pecl​、brew​、または同様の方法 (開発/本番パリティ)​を維持するために必ず行うべきこと) を使用して欠落している拡張機能をコンピューターにインストールできない場合は、欠落している (「プラットフォーム」) 要件を無視するよう Composer に指示できます。

$ composer update --ignore-platform-reqs

新しい環境 (他の開発者のコンピューターなど) で拡張機能が同様に使用できない場合、composer install​ をさらなる依存関係インストールで実行するときに、同じ --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)

インストールする拡張機能のリストは composer.lock​ から読み込まれるため、Heroku にプッシュされたプロジェクトの依存関係が必要とするあらゆる PHP 拡張機能が自動的にインストールされます。

たとえば、プロジェクトが stripe/stripe-php​ PHP SDK for Stripe​ に依存する場合、Stripe SDK が必要とする mbstring​ 拡張機能は、デプロイ時に自動的にインストールされます。ext-mbstring​ パッケージがメイン composer.json​ の require​ セクションで明記される必要はありません。

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

Symfony Polyfill​ のような Composer パッケージはネイティブ PHP 拡張機能をパッケージメタデータで provide​ として宣言し、PHP コードのみを使用してその拡張機能の機能を部分的または完全に実装します。これにより、Composer は依存関係の解決中に、それらを実際のネイティブ PHP 拡張機能の代替として考慮します。

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

つまり、symfony/polyfill-mbstring​ では ext-mbstring​ が provide​ 済みとして宣言されているため、composer.lock​ 内に symfony/polyfill-mbstring​ パッケージも存在する場合は、composer.json​、または ext-mbstring​ などの何らかの依存関係の要件があっても、ネイティブ 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 拡張機能が確実にインストールされるようになります。