コンパイラおよび依存ツールの準備

gRPCのPHP拡張モジュールをコンパイルするには、C++14規格に完全準拠したコンパイラ環境が必須です。レガシーなLinuxディストリビューションで標準提供されるGCC 4.8系ではシンタックスエラーが発生するため、事前にGCC 6.1以上へバージョンアップしてください。また、リポジトリの同期処理を安定させるため、Gitクライアントも最新安定版へ更新しておくことを推奨します。

リポジトリの取得とサブモジュール同期

公式ストレージから対象バージョンのソースコードを取得し、内部依存ライブラリを初期化します。ネットワーク帯域やプロキシ環境によっては接続が切断されるため、同期が完了するまでコマンドを再実行する場合があります。

# 作業領域の確保と移動
mkdir -p ~/grpc-compile && cd ~/grpc-compile

# 対象タグのクローン取得
TARGET_RELEASE="v1.50.1"
git clone -b "${TARGET_RELEASE}" https://github.com/grpc/grpc.git

# ディレクトリ移動とサブモジュールの初期化
cd grpc
git submodule sync --recursive
git submodule update --init --recursive

拡張モジュールのコンパイル

プロジェクトルートで基盤ライブラリをビルドした後、PHP拡張用のディレクトリへ移動して phpize および設定スクリプトを実行します。

# パスの定義
export GRPC_ROOT_DIR="$(pwd)"
export PHP_CONFIG_PATH="/usr/local/php/bin/php-config"

# 本体ライブラリの並列ビルド
EXTRA_DEFINES=GRPC_POSIX_FORK_ALLOW_PTHREAD_ATFORK make -j$(nproc)

# PHP拡張ソースディレクトリへ移動
cd "${GRPC_ROOT_DIR}/src/php/ext/grpc"

# 拡張機能のビルド環境構築
phpize
./configure --enable-grpc="${GRPC_ROOT_DIR}" \
            --with-php-config="${PHP_CONFIG_PATH}" \
            GRPC_LIB_SUBDIR="libs/opt"

# クリーンビルドとインストール
make clean
make -j$(nproc)
sudo make install

処理が正常に終了すると、共有オブジェクト grpc.so がPHPの拡張ディレクトリ（例: /usr/local/php/lib/php/extensions/no-debug-non-zts-*）に配置されます。

PHPランタイム設定とサービス反映

インストールされたモジュールを php.ini に登録し、PHPプロセスへ変更を適用します。

# 設定ファイルへの追記
echo "extension=grpc.so" | sudo tee -a /usr/local/php/etc/php.ini > /dev/null

# FPMサービスの再起動
sudo systemctl restart php-fpm.service

# モジュールロード状態の確認
php -m | grep grpc

macOS環境での動的ライブラリ参照エラーへの対応

macOS上でPHPプロセスを起動する際、libgrpc.dylib および libgpr.dylib の検索パスが解決されず、dlopen による警告が出力される場合があります。この問題は、システム標準のライブラリディレクトリにファイルが存在しないことが原因です。ビルド成果物を適切なパスへコピーすることで参照エラーを解消します。

# gRPCプロジェクトルートから実行
LIB_BUILD_DIR="libs/opt"
TARGET_LIB_DIR="/usr/local/lib"

# 共有ライブラリのコピー
sudo cp "${LIB_BUILD_DIR}/libgpr.dylib" "${TARGET_LIB_DIR}/"
sudo cp "${LIB_BUILD_DIR}/libgrpc.dylib" "${TARGET_LIB_DIR}/"

# システムキャッシュの更新（環境に応じて実行）
sudo update_dyld_shared_cache

ファイル配置後、PHPプロセスを再起動し、起動ログにライブラリ未解決の警告が含まれていないことを確認してください。