Installez les pilotes PHP pour SQL Server sur Windows

Utilisez cet article pour installer les pilotes SQLSRV et PDO_SQLSRV pour PHP sur Windows. Les pilotes sont des extensions PHP qui utilisent le pilote Microsoft ODBC pour SQL Server.

Avant de commencer, confirmez que votre version PHP, votre architecture et votre mode de sécurité de thread sont pris en charge dans la matrice de support. L’environnement d’exécution PHP utilisé par un processus en ligne de commande et celui utilisé par un serveur web peuvent utiliser des fichiers php.ini différents. Configurez et vérifiez chaque runtime séparément.

À la fin de la procédure, à la fois sqlsrv_connect() et le pilote PDO sqlsrv doivent être disponibles pour la CLI ou l’application web prévue, et chaque API doit effectuer une requête de test. Une copie réussie du fichier à elle seule n’est pas une installation terminée.

Choisir une méthode d’installation

Method Utilisez-le quand Ce qu’il installe
Installateur PHP pour extensions (PIE) Vous souhaitez que le programme d’installation sélectionne la version du pilote correspondant à l’exécutable PHP Non versionné php_sqlsrv.dll et php_pdo_sqlsrv.dll, avec tentative de configuration automatique
Package ZIP publié Vous devez choisir, inspecter ou déployer vous-même des fichiers précompilés spécifiques DLL versionnés sélectionnés par la version mineure de PHP, le mode de sécurité des threads et l’architecture

Utilisez une seule méthode pour les deux extensions. Ne gardez pas les entrées de configuration PIE et ZIP actives en même temps.

Prérequis d’installation

  1. Installez une compilation PHP prise en charge depuis le site PHP for Windows. Ajoutez le répertoire PHP à PATH.

  2. Installez le Visual C++ Redistributable requis par votre compilation PHP. Faites correspondre l’architecture x64 ou x86 à celle de PHP, comme décrit dans les exigences de PHP pour Windows.

  3. Installez le dernier pilote Microsoft ODBC pour SQL Server.

  4. Exécutez les commandes suivantes pour vérifier l’environnement d’exécution PHP et le fichier de configuration :

    php --version
php --ini

    Si Loaded Configuration File indique (none), copiez php.ini-development vers php.ini dans le répertoire PHP.

  5. Dans php.ini, définissez le répertoire des extensions et activez les extensions requises par l’installateur PHP pour les extensions (PIE) :

    extension_dir = "ext"
extension=openssl
extension=zip

  6. Confirmez que PHP peut localiser les extensions préalables :

    php --ri openssl
php --ri zip

    Corrigez ces prérequis avant de télécharger PIE.

Installer avec PIE

PIE installe le driver précompilé correspondant pour le runtime PHP. Il ne nécessite pas de compilateur C sous Windows.

  1. Placez-vous dans un répertoire où vous pouvez écrire, et téléchargez la dernière archive PIE PHP (PHAR) :

    curl.exe -fL --output pie.phar https://github.com/php/pie/releases/latest/download/pie.phar

    Les commandes PIE restantes désignent le fichier comme .\pie.phar, donc exécutez-les depuis ce même répertoire.

    Avant d’exécuter le PHAR, vérifiez-le avec l’interface en ligne de commande (CLI) de GitHub :

    gh attestation verify --owner php .\pie.phar

    Confirmez le téléchargement avant de continuer :

    dir pie.phar
php .\pie.phar --version

  2. Installez chaque pilote séparément :

    php .\pie.phar install microsoft/sqlsrv
php .\pie.phar install microsoft/pdo_sqlsrv

  3. Vérifiez l’environnement d’exécution en ligne de commande :

    php --ri sqlsrv
php --ri pdo_sqlsrv
php -m | findstr /I "sqlsrv pdo_sqlsrv"

PIE tente d’activer les extensions dans la configuration utilisée par l’exécutable de ligne de commande. Si PIE indique qu’il n’a pas pu activer une extension, ajoutez les entrées d’extension spécifiques à PIE.

Si votre serveur web utilise une autre installation de PHP, installez les deux pilotes pour la version de PHP, l’architecture et le mode de sécurité des threads de cette installation avant de la configurer. Si la même installation PHP utilise une autre php.ini pour le serveur web, activez les drivers installés dans ce fichier. Vérifiez le runtime web séparément, puis redémarrez le serveur web après avoir modifié sa configuration.

PIE modifie l’installation PHP sélectionnée. Il ne configure pas IIS, ne sélectionne pas un site IIS, ni ne redémarre les processus PHP existants.

Installer manuellement un package ZIP publié

Utilisez cette méthode lorsque vous devez sélectionner vous-même les fichiers du pilote ou lorsque PIE n’est pas adapté.

  1. Téléchargez le ZIP Windows pour la version publiée du pilote depuis la page Microsoft Drivers for PHP pour SQL Server releases.

  2. Exécutez php -i | findstr /I "PHP Version Thread Safety Architecture extension_dir" et enregistrez la version PHP, le mode de sécurité des threads, l’architecture et le répertoire d’extension.

  3. À partir du fichier ZIP, copiez les deux bibliothèques de liens dynamiques (DLL) correspondantes dans le répertoire des extensions :

    php_sqlsrv_<php-version>_<ts-or-nts>_<x86-or-x64>.dll
php_pdo_sqlsrv_<php-version>_<ts-or-nts>_<x86-or-x64>.dll

    Par exemple, un environnement d’exécution PHP 8.5 x64 thread-safe utilise php_sqlsrv_85_ts_x64.dll et php_pdo_sqlsrv_85_ts_x64.dll.

  4. Ajoutez les noms d’extensions correspondants au php.ini utilisé par l’environnement d’exécution :

    extension=php_sqlsrv_85_ts_x64.dll
extension=php_pdo_sqlsrv_85_ts_x64.dll

    Remplacez 85, ts, et x64 par les valeurs de votre runtime PHP. Ne mélangez pas les fichiers thread-safe et non-thread-safe, les fichiers 32 bits et 64 bits, ou les fichiers conçus pour une autre version mineure PHP.

  5. Vérifiez le runtime avec php --ri sqlsrv, php --ri pdo_sqlsrv, et php -m. Pour un serveur web, restreignez l’accès aux pages de diagnostic avant de créer une page temporaire phpinfo() . Vérifiez le fichier de configuration chargé et les deux sections du pilote, puis supprimez la page.

Configurez un serveur web

Pour IIS, configurez le php-cgi.exe souhaité en tant qu’application FastCGI en suivant les instructions d’installation de PHP sur IIS. Confirmez que l’application FastCGI utilise le même dossier PHP et la même architecture que vous avez utilisés pour installer les pilotes.

Pour tout serveur web Windows :

  1. Restreignez l’accès à la page de diagnostic avant de créer une phpinfo() page temporaire. Identifiez l’exécutable PHP et le fichier php.ini actif du serveur web.

  2. Assurez-vous que les deux pilotes sont installés pour l’environnement d’exécution web. Pour une installation PHP séparée, utilisez PIE avec l’exécutable PHP de cette installation, ou copiez les deux DLL correspondantes du ZIP publié vers son répertoire d’extension. Ajoutez les entrées du pilote à la configuration du runtime web, y compris lorsque seul son php.ini diffère de celui de la CLI.

  3. Redémarrez le serveur web ou les processus FastCGI.

  4. Confirmez que la page contient des sections sqlsrv et pdo_sqlsrv distinctes.

  5. Supprime la page phpinfo().

Testez les deux API PHP

Enregistrez ce programme sous verify-php-drivers.php:

<?php
$failures = [];

if (!extension_loaded('sqlsrv') || !function_exists('sqlsrv_connect')) {
    $failures[] = 'SQLSRV is not available.';
}

if (!extension_loaded('pdo_sqlsrv') || !in_array('sqlsrv', PDO::getAvailableDrivers(), true)) {
    $failures[] = 'PDO_SQLSRV is not available.';
}

echo $failures === []
    ? "SQLSRV and PDO_SQLSRV are available." . PHP_EOL
    : implode(PHP_EOL, $failures) . PHP_EOL;

exit($failures === [] ? 0 : 1);

Lancez-le d’abord depuis la ligne de commande :

php verify-php-drivers.php

Sortie attendue :

SQLSRV and PDO_SQLSRV are available.

Si vous devez vérifier un environnement d’exécution web, placez temporairement le fichier dans la racine documentaire du site et ouvrez-le dans un navigateur. Retirez-le après les tests. Ce programme vérifie les API PHP sans exiger ni exposer les identifiants de la base de données.

Tester une connexion à une base de données

Le chargement des extensions n’est que la première vérification d’installation. Testez les deux API sur la base de données cible utilisée par l’application, de sorte que le test couvre également le pilote ODBC, le chemin réseau, le chiffrement, l’authentification, l’exécution de requêtes, les valeurs retournées et le nettoyage.

Définissez des variables d’environnement temporaires dans PowerShell en répondant aux invites. Entrez les noms du serveur et de la base de données sous forme de valeurs brutes, sans guillemets ni codage de pilote. Utilisez la boîte de dialogue ou l’invite d’informations d’identification pour un compte test pouvant se connecter à la base de données. N’incluez pas les identifiants dans une ligne de commande ou une session terminal enregistrée :

$env:SQL_SERVER_NAME = Read-Host "Server name (tcp:<server>,1433)"
$env:SQL_DATABASE = Read-Host "Database name"
$credential = Get-Credential -Message "Enter the database test account"
if ($null -eq $credential) {
    throw "Database test credentials are required."
}
$env:SQL_UID = $credential.UserName
$env:SQL_PWD = $credential.GetNetworkCredential().Password
Remove-Variable credential

L’invite d’identification masque le mot de passe. L’environnement contient le mot de passe en clair pour que PHP puisse le lire. Utilisez ces variables uniquement pendant la session de test, ne les imprimez pas, et effacez-les après le test.

Enregistrez ce programme sous le nom test-php-drivers.php. Gardez les valeurs d’environnement inchangées. Le programme double les accolades fermantes et ajoute des accolades externes avant de transmettre le nom de la base de données, le nom d’utilisateur et le mot de passe au pilote. Ce codage préserve les accolades littérales et empêche les points-virgules de séparer les options de connexion.

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

if ($serverName === false || $serverName === ''
    || $database === false || $database === ''
    || $uid === false || $uid === ''
    || $pwd === false || $pwd === '') {
    fwrite(STDERR, "Set SQL_SERVER_NAME, SQL_DATABASE, SQL_UID, and SQL_PWD." . PHP_EOL);
    exit(1);
}

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

$connectionOptions = [
    "Database" => $database,
    "UID" => $uid,
    "PWD" => $pwd,
    "Encrypt" => 1,
    "TrustServerCertificate" => 0,
];

$sqlsrvConnection = sqlsrv_connect($serverName, $connectionOptions);
if ($sqlsrvConnection === false) {
    foreach (sqlsrv_errors() as $error) {
        fwrite(
            STDERR,
            "SQLSRV {$error['SQLSTATE']} ({$error['code']}): {$error['message']}" . PHP_EOL
        );
    }
    exit(1);
}

$sqlsrvStatement = sqlsrv_query($sqlsrvConnection, "SELECT 1 AS TEST_VALUE");
if ($sqlsrvStatement === false) {
    foreach (sqlsrv_errors() as $error) {
        fwrite(
            STDERR,
            "SQLSRV {$error['SQLSTATE']} ({$error['code']}): {$error['message']}" . PHP_EOL
        );
    }
    sqlsrv_close($sqlsrvConnection);
    exit(1);
}

$sqlsrvRow = sqlsrv_fetch_array($sqlsrvStatement, SQLSRV_FETCH_ASSOC);
if ($sqlsrvRow === false || $sqlsrvRow === null || (int) $sqlsrvRow['TEST_VALUE'] !== 1) {
    fwrite(STDERR, "SQLSRV returned an unexpected result." . PHP_EOL);
    sqlsrv_free_stmt($sqlsrvStatement);
    sqlsrv_close($sqlsrvConnection);
    exit(1);
}

echo "SQLSRV query: 1" . PHP_EOL;
sqlsrv_free_stmt($sqlsrvStatement);
sqlsrv_close($sqlsrvConnection);

$failed = false;
try {
    $pdoConnection = new PDO(
        "sqlsrv:server=$serverName;Database=$database;Encrypt=1;TrustServerCertificate=0",
        $uid,
        $pwd,
        [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]
    );
    $pdoStatement = $pdoConnection->query("SELECT 1 AS TEST_VALUE");
    $pdoRow = $pdoStatement->fetch(PDO::FETCH_ASSOC);
    if ($pdoRow === false || (int) $pdoRow['TEST_VALUE'] !== 1) {
        throw new RuntimeException("PDO_SQLSRV returned an unexpected result.");
    }

    echo "PDO_SQLSRV query: 1" . PHP_EOL;
} catch (Throwable $exception) {
    fwrite(STDERR, $exception->getMessage() . PHP_EOL);
    $failed = true;
} finally {
    unset($pdoStatement);
    unset($pdoConnection);
}

exit($failed ? 1 : 0);

Exécutez le programme avec le même exécutable PHP que vous avez vérifié :

php test-php-drivers.php

Sortie attendue :

SQLSRV query: 1
PDO_SQLSRV query: 1

Si la vérification de l’extension réussit, mais que ce programme échoue, utilisez le code SQLSTATE et l’erreur native pour identifier la couche responsable. Ne réinstallez pas les extensions PHP pour une erreur de réseau, de certificat, d’authentification ou d’autorisation de base de données.

Supprimez le script et les variables temporaires après le test :

Remove-Item .\verify-php-drivers.php, .\test-php-drivers.php
Remove-Item Env:\SQL_SERVER_NAME, Env:\SQL_DATABASE, Env:\SQL_UID, Env:\SQL_PWD

Troubleshooting

Symptôme Que vérifier Réparer
Could not open input file: .\pie.phar Répertoire actuel et lieu de téléchargement Retournez dans le répertoire contenant le PHAR vérifié, ou téléchargez-le et vérifiez-le à nouveau
Unable to load dynamic library extension_dir, nom exact de la DLL, version mineure de PHP, architecture et mode de sécurité du thread Sélectionnez la DLL correspondante ou relancez le PIE avec l’exécutable PHP prévu
The specified module could not be found Dépendances des DLL du pilote Confirmez l’existence de la DLL d’extension, installez le Visual C++ Redistributable correspondant, et inspectez toute dépendance DLL manquante
Les deux pilotes sont chargés en CLI, mais pas dans IIS Exécutable PHP différent ou php.ini Comparez php --ini avec phpinfo(), configurez l’environnement d’exécution IIS, et redémarrez FastCGI
Module "sqlsrv" is already loaded Les entrées PIE et ZIP, ou les entrées répétées Gardez une entrée SQLSRV et une entrée PDO_SQLSRV
Rapports PDO could not find driver PDO_SQLSRV configuration Exécutez php --ri pdo_sqlsrv et vérifiez PDO::getAvailableDrivers()
PIE rapporte un succès mais une ancienne version subsiste Entrées ZIP versionnées encore actives Remplacez les anciennes entrées par les entrées DLL non versionnées de PIE et redémarrez chaque processus PHP

Si les deux extensions se chargent bien, PHP peut appeler leurs API. Capturez les erreurs SQLSRV ou l’exception PDO avant de changer les fichiers de pilote. Les erreurs de réseau, d’authentification, de chiffrement, de certificats et d’autorisations de base de données ne sont pas corrigées en réinstallant l’extension PHP.

Contenu connexe

  • Dernière mise à jour :