ServBay でカスタム PHP モジュールをコンパイル・インストールする（macOS）

ServBay は、macOS 向けに設計されたパワフルなローカル Web 開発環境です。PHP、Node.js、Python、Go、Java、各種データベース（MySQL, PostgreSQL, MongoDB）、キャッシュ（Redis）、Web サーバー（Caddy, Nginx, Apache）など、豊富なテクノロジースタックを統合 & 複数バージョン対応で提供しています。プロジェクトごとに柔軟に環境を切り替えられるため、現代の Web 開発者の幅広い要件に応えます。

ServBay には多くの一般的な PHP モジュールがプリインストールされていますが、特定の開発要件によっては、PHP の機能拡張やサードパーティサービス連携のために追加モジュールを独自にコンパイル・インストールする必要がある場合があります。

本ガイドでは、ServBay 環境下で、任意の PHP バージョン向けにカスタムモジュールをコンパイル・インストールする手順を詳しくご案内します。代表例として、画像処理の定番である imagick モジュールと、Microsoft SQL Server 接続に使われる sqlsrv モジュールのインストール手順を取り上げ、具体的な流れを解説します。

前提条件

重要なお知らせ

どの PHP モジュールのコンパイルを始める前にも、最も重要なステップ は ServBay 公式ドキュメントの手順通りにビルド環境の初期化を済ませ、システムの環境変数を正しく設定することです。これを怠ると、コマンドやライブラリ、ヘッダーファイルが見つからず、ビルドにほぼ確実に失敗します。

ServBay のビルド初期化スクリプトは、PATH（ServBay 独自のビルドツールが格納されている）、SERVBAY_PACKAGE_FULL_PATH（ServBay パッケージルート）、CPU_NUMBER（並列ビルド用コア数）など、重要な環境変数を自動設定します。これらは後述するビルドコマンドの実行に不可欠です。

ビルド環境初期化の詳しい手順は ServBay での再コンパイル手順 をご覧ください。必ず事前に、ドキュメント通り環境準備を完了し、設定内容をしっかり理解したうえで進めてください。

モジュールのビルド作業を開始する前に、上記の ServBay ビルド環境初期化が正しく行われ、必要な環境変数がターミナルで適切に設定済みかどうか必ずご確認ください。

PHP バージョン指定の重要性

ServBay の大きな特長として、1台のマシン内で複数 PHP バージョンの共存・切り替えが可能な点が挙げられます。この柔軟性により、プロジェクトごとに PHP バージョンを簡単に変更できます。ただし、PHP モジュールをコンパイルする際は特定バージョン専用でビルドする必要があります。ビルドやバージョン情報取得に使う phpize および php-config は必ず対象バージョンと一致させてください。

• phpize：PHP 拡張モジュールのビルド環境を準備するスクリプト。config.m4 を読み込み、標準的な configure スクリプト等を生成します（一般的な C/C++ ソフトウェアのビルド工程の最初の一歩）。
• php-config：インストール済み PHP バージョンのビルド情報を参照できます。ビルドツール用のパスやオプション、拡張モジュールの配置ディレクトリやヘッダーファイルのありか等がわかります。configure スクリプトはこの情報を使い、対象 PHP に適合させてビルドします。

よって phpize や php-config を使う際は、フルパスで明確に 対象とする PHP バージョンのものを指定してください。例えば ServBay 内の PHP 8.3 であれば /Applications/ServBay/package/php/8.3/current/bin/phpize および /Applications/ServBay/package/php/8.3/current/bin/php-config という指定になります。意図したバージョンを選択することで、モジュールの互換性エラーや「未定義シンボル」等の問題を避けられます。

このドキュメントのサンプルでは ServBay の PHP 8.3 を例に解説しています。実際の運用時には、ご自身がモジュールを追加したい PHP バージョンのパスに読み替えて作業を進めてください。

PHP imagick モジュールのコンパイル

imagick は PHP で最も人気のある画像処理拡張モジュールの1つで、強力な ImageMagick ライブラリを利用して多彩な画像操作ができます。imagick を使えば、画像のリサイズ・クロップ・フォーマット変換・ウォーターマーク追加・合成など、様々な高度画像処理を PHP から簡単に実現できます。以下に、ServBay 上で任意 PHP バージョン向けに imagick モジュールをビルド＆インストールする詳細手順を紹介します。

ステップ1：ImageMagick のインストール

imagick PHP モジュールにはシステムに ImageMagick ライブラリ（開発ヘッダー含む）が必要です。macOS では Homebrew パッケージマネージャの利用をおすすめします。未導入の場合は Homebrew公式サイト からインストールしてください。

ターミナルで以下コマンドを実行して ImageMagick とその開発用ファイルをインストールします。

brew install imagemagick

ステップ2：imagick モジュールのソース取得

次に、PHP 拡張（PECL）公式サイトから imagick モジュールのソースを取得します。PECL imagick ページ から目的のバージョン（通常は最新安定版）を探し、ダウンロードリンクを確認してください。本ガイド執筆時点ではバージョン 3.7.0 を例にしています。

wget https://pecl.php.net/get/imagick-3.7.0.tgz

ステップ3：ソース解凍とディレクトリ移動

ダウンロード完了後、tar コマンドで解凍し、cd で展開ディレクトリに移動します。

tar zxvf imagick-3.7.0.tgz
cd imagick-3.7.0

ステップ4：ビルド環境準備（phpize の使用）

ソースディレクトリ内で、ターゲット PHP バージョンの phpize ツール（フルパス）を使いビルド環境を整えます。例：PHP 8.3（SERVBAY_PACKAGE_FULL_PATH 環境変数が正しく設定されている前提）。

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/phpize

phpize を成功させると、config.m4 を元に configure や各種ビルド用ファイルが生成されます。端末には構成準備が完了した旨のメッセージが表示されます。

ステップ5：ビルドオプションの設定

生成された configure スクリプトを実行し、ビルド用の設定を行います。この時、--with-php-config オプションでターゲット PHP バージョンの php-config フルパスを正しく指定してください。

./configure --with-php-config=${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php-config

configure スクリプトが、ImageMagick のライブラリ・ヘッダーファイルや PHP のビルド設定を参照しつつ Makefile を生成します。エラーの場合、ほとんどは依存関係の欠如やパス指定ミスです。

ステップ6：モジュールのビルド＆インストール

Makefile 生成後、make でビルド、make install で完成したモジュール（soファイル）を PHP の拡張ディレクトリへコピーします。${CPU_NUMBER}（ServBay 環境初期化時設定済み）は並列ビルドのプロセス数です。

make -j ${CPU_NUMBER}
make install

make install で、ビルド済みの imagick.so は ServBay の PHP 8.3 拡張モジュールディレクトリ（例：/Applications/ServBay/package/php/8.3/current/lib/php/extensions/no-debug-non-zts-YYYYMMDD/）にコピーされます（パスはバージョンとビルドにより異なります）。

ステップ7：モジュールの有効化

ビルド後、対象 PHP バージョンの設定ファイルでモジュールを有効にします。ServBay では GUI での簡単な操作が可能です。

• ServBay アプリケーションを起動
• 左メニューで「言語」 >「PHP」>「PHP 8.3」を選択
• 右側で「PHP」タブを選び、一番下「追加パラメーター」に extension=imagick.so と入力
• 「保存」をクリックすると PHP プロセスが自動再起動し、拡張モジュールが反映

ステップ8：モジュールの読込確認

モジュール有効化後、必ず ServBay の PHP パッケージを再起動し、新しい設定を反映させてください。ServBay 管理画面で対象 PHP バージョンの「再起動」ボタンを押すか、ServBay のコマンドラインツールでも操作可能です（詳細コマンドは ServBay ドキュメントを参照）。

PHP 再起動後、次のコマンドで imagick モジュールの読込状態を確認できます。

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep imagick

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php で ServBay の当該バージョン PHP を利用し、-m で全モジュール一覧を取得します。imagick が表示されればロード成功です。

より詳細な確認には、Web のドキュメントルート（初期 /Applications/ServBay/www）に info.php というファイルを作成し、内容を <?php phpinfo(); ?> と記述。ブラウザで http://localhost/info.php または設定ドメインでアクセスし、phpinfo ページ内で "imagick" を検索して有効化やバージョン情報を調べてください。

PHP sqlsrv/pdo_sqlsrv モジュールのコンパイル

sqlsrv、pdo_sqlsrv は PHP 公式拡張の1つで、Microsoft SQL Server に接続・操作する際に利用します。マイクロソフト公式の ODBC ドライバを利用します。ServBay 環境下の PHP で SQL Server にアクセスする場合、これらのモジュールのビルドとインストールが必要です。次に、その主な手順を解説します。

注意：重要な事前準備

macOS で sqlsrv モジュールのビルドには、Microsoft 提供の SQL Server ODBC ドライバ（msodbcsql18）とコマンドラインツール（mssql-tools18）の事前インストールが必須です。これらは ServBay に含まれないため、ユーザーご自身で導入する必要があります。

Homebrew 経由でのインストールが推奨されます。未インストールの場合は Homebrew 公式サイト を参照して事前準備を行ってください。

Microsoft ODBC ドライバ＆ツールのインストールコマンドは以下の通りです。利用規約の同意には HOMEBREW_ACCEPT_EULA=Y の環境変数が必要な場合があります。

brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql18 mssql-tools18

これら依存パッケージは、Apple Silicon Mac なら /opt/homebrew/、Intel Mac なら /usr/local/ にインストールされるのが一般的です。ビルド時にはこのパス指定が必要となります。

ワンポイント

sqlsrv と pdo_sqlsrv は別々のモジュールですが、コンパイル方法はほぼ同じです。以下は sqlsrv 用の例ですが、pdo_sqlsrv でも同様に実施してください。

ステップ1：Microsoft ODBC ドライバ＆ツールのインストール

（上記の方法で msodbcsql18 および mssql-tools18 を必ず事前に Homebrew からインストールしておくこと）

ステップ2：sqlsrv モジュールのソース取得

PECL 公式から sqlsrv および pdo_sqlsrv モジュールのソースをダウンロードします。PECL sqlsrv ページ で最新バージョンを確認し、下記の例（5.12.0）の要領で取得してください。

wget https://pecl.php.net/get/sqlsrv-5.12.0.tgz  # sqlsrv
wget https://pecl.php.net/get/pdo_sqlsrv-5.12.0.tgz  # pdo_sqlsrv

ステップ3：ソースの解凍＆ディレクトリ移動

ダウンロード完了後、tar で解凍・cd でディレクトリに移動します。

tar zxvf sqlsrv-5.12.0.tgz
cd sqlsrv-5.12.0

# pdo_sqlsrv も同様、以下は sqlsrv 例として進めます

ステップ4：ビルド環境準備（phpize の使用）

対応 PHP バージョンの phpize（フルパス）でビルド環境を整備します（SERVBAY_PACKAGE_FULL_PATH 設定済みを前提）。

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/phpize

ステップ5：ビルドオプション設定（依存パス指定あり）

sqlsrv は Homebrew の Microsoft ODBC ドライバおよび unixODBC に強く依存しているため、LDFLAGS・CPPFLAGS で適切なパスを指定しつつ ./configure（要 --with-php-config）を実行してください。

Homebrew のインストールパスは Intel Mac だと /usr/local、Apple Silicon Mac だと /opt/homebrew です。以下例は /opt/homebrew の場合。

export LDFLAGS="-L/opt/homebrew/lib ${LDFLAGS}"
export CPPFLAGS="-I/opt/homebrew/opt/unixodbc/include -I/opt/homebrew/include ${CPPFLAGS}" # すべてのヘッダー探索用
./configure --with-php-config=${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php-config

• LDFLAGS: リンカにライブラリ探索パスを追加（例: -L/opt/homebrew/lib）
• CPPFLAGS: プリプロセッサにヘッダー探索パスを追加（例: -I/opt/homebrew/opt/unixodbc/include, -I/opt/homebrew/include など）。${CPPFLAGS} ${LDFLAGS} の追加は既存フラグの維持のため。

ステップ6：ビルド＆インストール

Makefile 生成後、make でビルド、make install で PHP 拡張ディレクトリへコピーします。

make -j ${CPU_NUMBER}
make install

make install で、ビルド済みの sqlsrv.so および pdo_sqlsrv.so（同時ビルド時）が ServBay の PHP 拡張ディレクトリに配置されます。

ステップ7：モジュールの有効化

ビルド済みモジュールは、対象 PHP バージョン設定ファイルで有効化します（GUI 操作）。

• ServBay アプリケーションを起動
• 左メニューから「言語」>「PHP」>「PHP 8.3」を選択
• 右側で「PHP」タブを選び、「追加パラメーター」に extension=sqlsrv.so および extension=pdo_sqlsrv.so を追記
• 「保存」をクリック、PHP プロセスが自動再起動します

ステップ8：モジュール読込確認

有効化後、必ず再起動し設定を反映させましょう。

再起動後、コマンドラインでモジュールの読込状態を確認します。

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep sqlsrv
${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep pdo_sqlsrv

sqlsrv や pdo_sqlsrv が表示されていればロード成功です。phpinfo() でも詳細な状態を確認できます。

よくある質問（FAQ）

• Q: "Cannot find autoconf" などビルド時にエラーが出る場合？
  • A: 99%は ServBay ビルド環境の初期化不足です。先頭「前提条件」に戻り、再コンパイル手順 に従い再度初期化してください。autoconf, automake, libtool などビルドツールが正しく環境変数に登録されているか確認を。通常は初期化スクリプト実行後、端末を再起動すれば解決します。
• Q: configure で「特定のライブラリやヘッダーファイルが見つからない」エラーが出る場合？
  • A: モジュールの依存ライブラリやヘッダーが未インストール、またはパス指定の誤りです。
    • imagick の場合：ImageMagick 開発パッケージがインストールされていることを確認。Homebrew なら brew install imagemagick。
    • sqlsrv の場合：必ず事前に Microsoft ODBC ドライバ（msodbcsql18）および mssql-tools18 を Homebrew 経由でインストールし、LDFLAGS・CPPFLAGS に Homebrew パス（例: /opt/homebrew/lib, /opt/homebrew/opt/unixodbc/include）を含めること。
    • ServBay ビルド環境の PATH に Homebrew の bin パスが含まれているか、または手動で追加が必要な場合があります。
• Q: make や make install で失敗する場合？
  • A: 主な原因は以下の通りです。
    • 必要なビルド依存が不足：エラーメッセージをよく読み、該当モジュールやパッケージを追加インストール。
    • 設定パラメーターの間違い：configure で --with-php-config パスが ServBay の正しい PHP バージョンを指しているか確認。
    • 権限エラー：make install で拡張ディレクトリへ書き込めない場合、sudo make install を試す（リスク理解の上、慎重に）。
    • ソース破損：ダウンロードしたソースが正しいか、再取得も検討。
• Q: .so ファイルを拡張ディレクトリに置き、ini ファイルも正しく編集したのに、php -m や phpinfo() にモジュールが現れない場合？
  • A:
    • 最も多い原因： ServBay の PHP パッケージを再起動していない。ini 編集後は、必ず ServBay 管理画面やコマンドラインで対象 PHP バージョンを完全再起動すること。Web サーバ（Caddy/Nginx）のみ再起動では不十分です。
    • ini ファイルの記述ミス・文法エラー。extension=modulename.so の拼字や書式ミスに注意。
    • 拡張ディレクトリ（extension_dir）の誤設定。php-config --extension-dir で絶対パスを調べ、php.ini の該当設定が正しいか確認を。
    • モジュールのビルド失敗や PHP バージョン非対応。ソースバージョン・PHP バージョンの組み合わせを再確認し、ビルドをやり直す。ServBay ログ（通常、インストールディレクトリの logs 配下）も確認してください。

まとめ

このガイドの手順を順守することで、ServBay macOS ローカル開発環境に imagick や sqlsrv など任意の PHP モジュールを自在にビルド・インストールできます。特に意識すべきポイントは以下の通りです。

1. ServBay ビルド環境を正確に初期化：すべてのビルド作業の前提となる重要ステップです。
2. 適切な PHP バージョンパスの利用：phpize・php-config を確実に該当バージョンのパスで指定してください。
3. モジュール外部依存の解決：必要なライブラリやツール（ImageMagick、Microsoft ODBC ドライバ等）を準備し、LDFLAGS や CPPFLAGS などの環境変数で ./configure 時に正しいパスを指定、configure スクリプトに認識させること。
4. modulename.so の正しい有効化：conf.d 配下で ini 追加または編集し、extension=modulename.so で設定。
5. PHP パッケージの再起動：新規モジュールや設定が反映されるよう確実に再起動する。

ServBay は MySQL, PostgreSQL, MongoDB, Redis, Caddy, Nginx, Apache, Node.js, Python, Go, Java, .NET, Ruby, Rust など、多様なテクノロジースタックに幅広く対応する包括的なローカル開発環境です。ACME ベースの実証 SSL 証明書取得、CORS 設定、設定・サイト・DB・SSL を含む自動バックアップ、DB root パスワードリセット、ローカル HTTPS 開発用 ServBay User CA & Public CA の活用など、便利な機能が満載。開発効率や再現性、小規模～大規模案件まで柔軟にサポートできます。

本ガイドが、ServBay の PHP 環境で必要な拡張機能追加や開発フロー改善のお役に立てば幸いです。その他の疑問は ServBay 公式ドキュメント＆コミュニティサポートも合わせてご利用ください。