LinuxとmacOSでPHP用のMicrosoftドライバーをインストールしてください

これらの手順は、PHP、Microsoft ODBC Driver for SQL Server、SQLSRVおよびPDO_SQLSRV拡張をインストールします。 各タブは、各タブのインストール元リポジトリが提供するPHPパッケージを使用しているため、コマンドのバージョンはタブごとに異なります。 もしそのリポジトリが別のPHPバージョンを提供しているなら、 サポートマトリックス に記載されている別のPHPバージョンに置き換えてください。

SQLSRVおよびPDO_SQLSRVドライバは同じODBC依存関係を使用し、独立してインストール可能です。 アプリケーションが両方のドライバーを使っている場合は、両方の拡張機能をインストールしてください。

手順の最後に、CLIと選択したウェブサーバーランタイムが両方の拡張を読み込み、両方のPHP APIが利用可能で、各APIのサンプルはデータベースサーバーバージョンを返すはずです。

始める前に

  1. 現在のドライバリリースでサポートされ、かつ、お使いのオペレーティングシステムリリースで利用可能なPHPバージョンを選択します。

  2. どのPHPランタイムが必要かを決めてください:

    • スクリプト、スケジュールされたタスク、ワーカー用のCLIです。
    • ApacheホストPHP用のApacheモジュール。
    • nginx または Apache の FastCGI 構成向けの PHP-FPM です。

  3. オペレーティングシステムのアーキテクチャを確認してください。 リリースされたLinuxアーカイブにはx64バイナリが含まれ、リリースされたmacOSアーカイブにはArm64バイナリが含まれています。 PIE はコンピュータ上の PHP インストール向けにビルドされ、この記事の主なインストール方法です。

  4. Microsoft ODBCドライバーとunixODBC開発パッケージをインストールしてください。 Microsoftパッケージはデータベース通信を担当します。 unixODBCパッケージは、SQLSRVやPDO_SQLSRVを構築するために必要なヘッダーを提供します。

  5. 拡張機能をインストールまたは変更した後は、すべてのウェブサーバー、PHP-FPM プール、長期間稼働しているワーカーを再起動する計画を立ててください。

プラットフォームパッケージマネージャーはPHPとネイティブの前提要件をインストールします。 PIEはPHP拡張をビルドしインストールします。 PHPの設定は、各ランタイムがそれらを読み込むかどうかを制御します。 拡張が読み込まれた後、ODBCドライバはデータベース通信と暗号化を処理します。

PIEでドライバーをインストールしてください

PIE（PHP Installer for Extensions）は、現在のドライバー リリースでサポートされている拡張機能インストーラーです。 これは、廃止された PHP拡張コミュニティライブラリ(PECL) ワークフローに代わるものです。

ドライバーをインストールする前に、以下のセクションでプラットフォームの前提条件を完了してください。 次にPIEと各ドライバーを別々にインストールします:

PIEをインストールする

PIEはPHP 8.1以降のバージョンで動作します。 そのインストールの開発ツールを選択すると、拡張機能を別のPHPインストールにインストールできます。

curl GitHub CLIをインストールしてから続けてください。 プラットフォームセクションには、最小限のインストールでは含まれない場合がある curl もあります。

PIE PHPアーカイブ(PHAR)をダウンロードし、インストールまたは実行前にGitHubのコマンドラインインターフェース(CLI)を使用して検証してください:

pie_tmp=$(mktemp -d)
curl -fL --output "$pie_tmp/pie.phar" https://github.com/php/pie/releases/latest/download/pie.phar
gh attestation verify --owner php "$pie_tmp/pie.phar"

検証が成功した場合のみ継続してください:

sudo install -m 755 "$pie_tmp/pie.phar" /usr/local/bin/pie
rm "$pie_tmp/pie.phar"
rmdir "$pie_tmp"
unset pie_tmp

一時的なディレクトリはあなたのアカウント専用です。 ダウンロードや検証に失敗した場合は、PHARのインストールや実行はしないでください。 再試す前に一時ファイルとディレクトリを削除してください。

インストールされたPHARが使用予定のPHP実行ファイルで動作しているか確認してください:

php /usr/local/bin/pie --version

SQLSRVとPDO_SQLSRVドライバーをインストールしてください

LinuxやmacOSでは、PIEが必要なコンパイラやPHP開発ツールがあるか確認します。 PIEを実行する前に、プラットフォーム用ODBC開発パッケージとC++コンパイラをインストールしてください。 インタラクティブ端末からPIEを実行する。 システムディレクトリにファイルをインストールする許可が必要なときに、あなたのsudoパスワードを要求できます。

PIEは、PIEの実行に使用されるPHPインストールをターゲットにしています。 バージョン付きのインストールの場合は、各インストールコマンドに --with-php-config を追加して開発ツールを選択します。 例えば、意図したツールが pie install --with-php-config=/usr/bin/php-config8.4 microsoft/sqlsrv の場合は /usr/bin/php-config8.4 を使う。 同じオプションを microsoft/pdo_sqlsrvにも適用してください。 Alpineはバージョン指定の実行ファイル名を使用します。このセクションのバージョンなしのコマンドではなく、Alpine コマンドに従ってください。

各拡張機能に対して1つのコマンドを実行します。 これらのコマンドはPIEのデフォルトのPHPインストールを使用しています:

pie install microsoft/sqlsrv
pie install microsoft/pdo_sqlsrv

PIEはプラットフォームのPHP設定ツールや extension= エントリを通じて各拡張機能を有効にしようと試み、有効にできない場合は警告を出します。 PHPは各実行環境に対してサーバーアプリケーションプログラミングインターフェース(SAPI)を使用します。 Debian、Ubuntu、SUSEでは、コマンドライン、Apache、PHPのFastCGIプロセスマネージャー（PHP-FPM）の構成が異なる場合があります。 コマンドラインインストールが成功しても、ウェブサーバーがドライバーを読み込むことを確認するものではありません。

コマンド ラインについてはphp --iniを確認してください。 ウェブサーバー用の一時的な phpinfo() ページを作成する前に、 診断ページへのアクセスを制限してください。 各ランタイムごとに 読み込まれた設定ファイル とスキャン済み .ini ファイルを確認してください。 もしエントリーが欠けている場合は、正しいロード順で追加するには、Linux と macOS でドライバーをロードする に従ってください。 設定変更後にウェブサーバーまたはPHP-FPMを再起動してください。 Red Hatは一般的にSAPI間で php.ini を共有しますが、単一のPIE実行結果に頼る前にアクティブな構成を確認してください。

お使いのプラットフォームにインストール

オペレーティングシステムとウェブサーバーの設定を選択してください。 そのタブのインストール手順を完了し、次にインストールをテストするに従ってください。

Ubuntu にインストールする

注

以下のコマンドは packages.sury.org PHPリポジトリを利用し、サポートされているPHPバージョンを選択できます。 Ubuntuリリース用のODBCドライバーをインストールするには、公式のMicrosoftの説明書に従ってください。

ステップ 1. PHP (Ubuntu) をインストールする

sudo apt-get update
sudo apt-get install ca-certificates apt-transport-https curl gnupg2 lsb-release -y
sudo install -d -m 755 /etc/apt/keyrings
sudo curl -fsSL https://packages.sury.org/php/apt.gpg -o /etc/apt/keyrings/php.gpg
sudo chmod 644 /etc/apt/keyrings/php.gpg
echo "deb [signed-by=/etc/apt/keyrings/php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/php.list
sudo apt-get update
sudo apt-get install php8.4 php8.4-dev php8.4-xml -y

手順 2. 前提条件のインストール (Ubuntu)

Linux に Microsoft ODBC Driver for SQL Server をインストールに従って、開発ヘッダーをインストールしてください。

sudo apt-get install unixodbc-dev g++ make git -y

手順 3. Microsoft SQL Server用のPHPドライバーをPIE(Ubuntu)でインストールしてください

「 PIEでドライバーをインストールする」に従い、両方のインストールコマンドに --with-php-config=/usr/bin/php-config8.4 を追加してください。 コマンドラインの設定ファイルを確認してください php8.4 --ini。

/usr/local/bin/pie install --with-php-config=/usr/bin/php-config8.4 microsoft/sqlsrv
/usr/local/bin/pie install --with-php-config=/usr/bin/php-config8.4 microsoft/pdo_sqlsrv

手順 4. Apache をインストールしてドライバーの読み込みを構成する (Ubuntu)

sudo apt-get install apache2 libapache2-mod-php8.4 -y
sudo a2enmod php8.4

ステップ 5. Apache を再起動してサンプル スクリプトをテストする (Ubuntu)

sudo systemctl restart apache2

インストールをテストするには、このドキュメントの最後にある インストールのテスト を参照してください。

レガシー PECL のインストール

PECLは現在のドライバーリリースでは非推奨となっています。 新規インストールやアップグレードにはPIEを使いましょう。 既存のデプロイメントがPECLにピン留めされている場合は、パッケージのバージョンをPHPランタイムに合わせ、PIEへの移行を計画してください。

インストールをテストする

コマンドライン ランタイムを確認してください。 アルパインでは php を php84に置き換えてください。 別のディストリビューション上のバージョン付きPHPインストールの場合は、対応する実行ファイルを使用します。

php --ri sqlsrv
php --ri pdo_sqlsrv
php -m | grep -E "sqlsrv|pdo_sqlsrv"

両方の --ri コマンドは ExtensionVer を含むモジュール情報を表示するはずです。 モジュールリストには別々の sqlsrv 行と pdo_sqlsrv 行を含めるべきです。

接続をテストする前に、verify-php-drivers.php の両方のPHP APIサーフェスを確認してください:

<?php
$checks = [
    'SQLSRV' => extension_loaded('sqlsrv') && function_exists('sqlsrv_connect'),
    'PDO_SQLSRV' => extension_loaded('pdo_sqlsrv')
        && in_array('sqlsrv', PDO::getAvailableDrivers(), true),
];

$failed = false;
foreach ($checks as $name => $loaded) {
    echo "$name: " . ($loaded ? 'loaded' : 'missing') . PHP_EOL;
    $failed = $failed || !$loaded;
}

exit($failed ? 1 : 0);

予想される出力:

SQLSRV: loaded
PDO_SQLSRV: loaded

PHP-FPM やウェブサーバーでは、phpinfo()してから一時的なページを作成してください。 ロード済み設定ファイル、extension_dir、そして両方のドライバーセクションを確認してください。 設定を変更したり拡張機能を交換したりした後、PHP-FPM またはウェブサーバーを再起動してください。 認証後にページを削除してください。

ライブ接続をテストするには、システムのドキュメントルートに testsql.php という名前のファイルを作成します。 このパスは、Ubuntu、Debian、Red Hat では/var/www/html、SUSE では/srv/www/htdocs、Alpine では/var/www/localhost/htdocs、または macOS では$(brew --prefix)/var/wwwです。 スクリプトを実行する前に、PHPプロセスの SQL_SERVER_NAME、 SQL_DATABASE、 SQL_UID、 SQL_PWD 環境変数を設定してください。 ドキュメントルート配下のファイルに認証情報をハードコードしないでください。

コマンドラインテストでは、シェル履歴にパスワードを入力しずに環境変数を設定する インタラクティブプロンプト を使いましょう。

Apacheモジュールテストでは、サイトの通常は閲覧可能な設定ファイルから認証情報は除外してください:

  1. ドキュメントルートの外にプライベートファイルを作成します。 Apacheの設定ディレクトリで使用されていないファイル名を使ってください。 Linux の場合:

    sudo install -o root -g root -m 600 /dev/null /etc/apache2/php-sql-driver-test.conf

    Red Hatでは /etc/apache2 を /etc/httpdに置き換えてください。 macOSでは、HomebrewのApacheを起動するアカウントでファイルを作成してください:

    install -m 600 /dev/null "$(brew --prefix)/etc/httpd/php-sql-driver-test.conf"

    これらの設定を読むのはファイルの所有者とrootだけです。 Apacheを起動するアカウントはファイルを読み取れる必要があります。

  2. テキストエディタでプライベートファイルを編集し、以下のエントリーを追加してください:

    SetEnv SQL_SERVER_NAME "tcp:<server>,1433"
SetEnv SQL_DATABASE "<database>"
SetEnv SQL_UID "<user_id>"
SetEnv SQL_PWD "<password>"

    二重引用符で囲まれた引数の中で、各リテラル バックスラッシュに対して \\ を、各リテラル二重引用符に対して \" と書きます。 引用符の中に先頭と末尾のスペースを残してください。 Apache はまた、${NAME} 参照も置換します。 値にそのシーケンスや改行が含まれている場合は、代わりにコマンドラインテストを使用してください。 詳細については、 Apache configuration quoteing and escaping をご覧ください。

  3. サイトの仮想ホスト内に、Files専用のプライベートファイルを含むtestsql.phpブロックを追加してください。 仮想ホストが設定されていない場合は、ブロックをメインサーバー設定に配置します。 プレースホルダーをプライベートファイルの絶対パスで置き換えます:

    <Files "testsql.php">
    Include "<absolute-path-to-private-file>"
</Files>

  4. Apacheを再起動してください。 テスト後、追加した Files ブロックを削除し、プライベートファイルを削除してApacheを再起動してください。 関連のないサイト設定を保持してください。

PHP-FPM はデフォルトで継承された環境変数をクリアし、nginxは環境をPHP-FPMに渡しません。 以下のUbuntuまたはRed Hatの手順は、隔離されたテスト用のPHP-FPMサービスおよびプールに対してのみ使用してください。 他のアプリケーションを実行するサービスやプールにテスト認証情報を追加しないでください。そのプール内のすべてのスクリプトがそれらを読み取ることができます。 共有ホスティングを使う場合は、コマンドラインテストを使いましょう。

  1. ドキュメントルートの外部にroot所有ファイル(例えば /etc/php-sql-driver-test.env)を作成し、アクセスを制限します:

    sudo touch /etc/php-sql-driver-test.env
sudo chmod 600 /etc/php-sql-driver-test.env

    ファイルに接続設定を追加してください:

    SQL_SERVER_NAME="tcp:<server>,1433"
SQL_DATABASE="<database>"
SQL_UID="<user_id>"
SQL_PWD="<password>"

    各設定は1行にしてください。 ダブルクォート内で、各リテラルバックスラッシュには \\ 、各リテラルダブルクォートには \" と書いてください。 ドル記号やバックティックはシェル式として評価されません。 ファイルをシェルで実行したり source したりせず、直接編集してください。 詳細は systemd EnvironmentFile 構文を参照してください。

  2. Ubuntu では sudo systemctl edit php8.4-fpm を、Red Hat では sudo systemctl edit php-fpm を実行してください。 この systemd オーバーライドを加えます:

    [Service]
EnvironmentFile=/etc/php-sql-driver-test.env

  3. これらのエントリをアクティブ PHP-FPM プール構成に追加してください。 一般的な場所はUbuntuで /etc/php/8.4/fpm/pool.d/www.conf 、Red Hatで /etc/php-fpm.d/www.conf です。

    env[SQL_SERVER_NAME] = $SQL_SERVER_NAME
env[SQL_DATABASE] = $SQL_DATABASE
env[SQL_UID] = $SQL_UID
env[SQL_PWD] = $SQL_PWD

  4. システムドを再ロードし、該当する PHP-FPM サービスを再起動する:

    sudo systemctl daemon-reload
sudo systemctl restart php8.4-fpm

    Red Hatでは php8.4-fpm を php-fpmに置き換えてください。

テスト後、一時的な環境ファイル、追加した EnvironmentFile= エントリ、テストプールのエントリ、 testsql.phpを削除してください。 サービスオーバーライドファイルは、このテスト用に作成したもので、他に設定が含まれていない場合のみ削除してください。 既存のオーバーライドやプール設定はすべて保持してください。 systemdを再読み込みし、テスト設定を解除した後に再度 PHP-FPM を再起動してください。

SQLSRV の例

環境変数の値は変更しないでください。 各例は接続前に、設定が欠落しているか空の場合は拒否します。 各例は閉じ波かっこを二重にし、外側ブレースを追加してから、データベース名、ユーザー名、パスワードをドライバーに渡します。 このエンコーディングによりリテラルな中括弧が保持され、セミコロンで接続オプションを区切るのを防ぎます。

<?php
$serverName = getenv('SQL_SERVER_NAME');
$databaseName = getenv('SQL_DATABASE');
$uid = getenv('SQL_UID');
$pwd = getenv('SQL_PWD');

if ($serverName === false || $serverName === ''
    || $databaseName === false || $databaseName === ''
    || $uid === false || $uid === ''
    || $pwd === false || $pwd === '') {
    handle_failure("Set SQL_SERVER_NAME, SQL_DATABASE, SQL_UID, and SQL_PWD.");
}

$databaseName = '{' . str_replace('}', '}}', $databaseName) . '}';
$uid = '{' . str_replace('}', '}}', $uid) . '}';
$pwd = '{' . str_replace('}', '}}', $pwd) . '}';
$connectionOptions = array(
    "Database" => $databaseName,
    "UID" => $uid,
    "PWD" => $pwd,
    "Encrypt" => 1,
    "TrustServerCertificate" => 0
);

function handle_failure($message) {
    error_log($message);
    http_response_code(500);
    echo "<h1>Failure</h1>";
    echo "An error occurred. Check the server error log for details.";
    exit(1);
}

function format_errors($errors) {
    $lines = [];
    foreach ($errors as $error) {
        $lines[] = "SQLSTATE: {$error['SQLSTATE']}, code: {$error['code']}, message: {$error['message']}";
    }
    return implode(PHP_EOL, $lines);
}

$conn = sqlsrv_connect($serverName, $connectionOptions);
if ($conn === false) {
    handle_failure(format_errors(sqlsrv_errors()));
}

$tsql = "SELECT @@Version AS SQL_VERSION";

$stmt = sqlsrv_query($conn, $tsql);
if ($stmt === false) {
    handle_failure(format_errors(sqlsrv_errors()));
}

$row = sqlsrv_fetch_array($stmt, SQLSRV_FETCH_ASSOC);
if ($row === null || $row === false) {
    handle_failure("Query returned no rows.");
}

echo "<h1>Success</h1>";
echo htmlspecialchars($row['SQL_VERSION']);

sqlsrv_free_stmt($stmt);
sqlsrv_close($conn);
?>

PDO_SQLSRV の例

<?php
$serverName = getenv('SQL_SERVER_NAME');
$databaseName = getenv('SQL_DATABASE');
$uid = getenv('SQL_UID');
$pwd = getenv('SQL_PWD');

if ($serverName === false || $serverName === ''
    || $databaseName === false || $databaseName === ''
    || $uid === false || $uid === ''
    || $pwd === false || $pwd === '') {
    handle_failure(new RuntimeException("Set SQL_SERVER_NAME, SQL_DATABASE, SQL_UID, and SQL_PWD."));
}

$databaseName = '{' . str_replace('}', '}}', $databaseName) . '}';
$uid = '{' . str_replace('}', '}}', $uid) . '}';
$pwd = '{' . str_replace('}', '}}', $pwd) . '}';

function handle_failure($exception) {
    error_log($exception->getMessage());
    http_response_code(500);
    echo "<h1>Failure</h1>";
    echo "An error occurred. Check the server error log for details.";
    exit(1);
}

try {
    $conn = new PDO(
        "sqlsrv:server=$serverName;Database=$databaseName;Encrypt=1;TrustServerCertificate=0",
        $uid,
        $pwd
    );
    $conn->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

    $tsql = "SELECT @@Version AS SQL_VERSION";

    $stmt = $conn->query($tsql);
    $row = $stmt->fetch(PDO::FETCH_ASSOC);
    if ($row === false) {
        throw new RuntimeException("Query returned no rows.");
    }

    echo "<h1>Success</h1>";
    echo htmlspecialchars($row['SQL_VERSION']);
} catch (Throwable $exception) {
    handle_failure($exception);
}

unset($stmt);
unset($conn);
?>

ブラウザーを http://localhost/testsql.php (macOS 上のhttp://localhost:8080/testsql.php ) にポイントします。 接続が成功すると、データベースサーバーのバージョン文字列が表示されます。 どちらの例もPHPエラーログにエラー詳細を書き込んでいます。 ページにエラーが表示されたら、そのログを確認してください。

コマンドラインとウェブサーバーの動作を比較するには、ターミナルで同じ環境変数を設定し、次を実行します:

php testsql.php

コマンドラインからの実行が成功してもブラウザに何も表示されない場合は、Apacheのログファイルを確認してください。 詳細については、 PHP SQLドライバーのサポートリソースをご覧ください。

SQL Server、Azure SQL Database、Azure SQL Managed Instance、Azure Synapse Analytics、Microsoft FabricのSQLデータベース、Microsoft FabricのWarehouseの接続プログラムを別々に評価してください。 選択した認証方法、接続オプション、クエリは対象でサポートされている必要があります。 インストールはクライアント側で行われます。 拡張機能チェックが成功しても、ターゲットが認証情報を受け入れているか、クライアントを信頼しているか、すべてのデータベース機能をサポートしているかを証明するわけではありません。

インストールのトラブルシューティング

症状: 所有レイヤー 是正措置
PIEは phpize、 php-config、ヘッダーを見つけられません PHP開発パッケージ ターゲット PHP バージョンの開発パッケージをインストールし、対応する --with-php-config オプションを指定します
コンパイルが失敗するのは、C++コンパイラが欠けているからです OS ビルド ツール プラットフォーム用のC++コンパイラパッケージ（g++ や gcc-c++ など）をインストールしてください。
コンパイル時にsql.hが見つかりません ODBC開発パッケージまたはコンパイラパス インストール unixodbc-dev または unixODBC-devel;Appleシリコン上でHomebrewのincludeとライブラリフラグを設定します
php --ri は拡張機能が存在しないと述べています PHPの設定 読み込まれた php.ini とスキャンディレクトリを確認し、正しいエントリを追加して処理を再実行します
PDOレポート could not find driver PDO_SQLSRV の読み込みまたは PDO の読み込み順 まずPDOが読み込まれ、PDO_SQLSRVが後でスキャンされる設定ファイルを使うことを確認する
CLIは動作しますが、Apache、nginx、または PHP-FPM は動作しません SAPI固有の構成 CLIの出力と phpinfo()を比較し、ウェブSAPIを設定して、それを再起動します
ブラウザはnginxを通じてHTTP 502を返します nginx から PHP-FPM へのルーティング fastcgi_passソケットをインストール済みの PHP-FPM バージョンと比較して、サービスが稼働しているか確認してください
ブラウザのサンプルは環境変数が不足していることを報告します ウェブサーバーまたは PHP-FPM 環境 選択したウェブランタイムの変数を設定し、再起動してください
拡張機能は読み込まれますが、接続に失敗します ODBC、ネットワーク、証明書、認証、またはSQL製品 サーバーログでSQLSTATEとネイティブエラーを確認し、エラーが読み込みまたはバイナリ互換性の問題を示していない限り、拡張を再構築しないでください

一時的なテスト構成を削除してください

検証後:

  1. ドキュメントのルートから testsql.php、 verify-php-drivers.php、そして一時的な phpinfo() ページを削除してください。

  2. 一時的な資格情報と環境転送エントリを削除する。

  3. systemdオーバーライドを変更したらサービスマネージャーを再読み込み、その後 PHP-FPM またはウェブサーバーを再起動してください。

  4. アプリケーションが必要な拡張機能エントリとインストール済みパッケージは保持してください。

関連するコンテンツ

  • 最終更新: