Installez les pilotes Microsoft pour PHP sur Linux et macOS

Ces instructions installent PHP, le pilote ODBC Microsoft pour SQL Server, ainsi que les extensions SQLSRV et PDO_SQLSRV. Chaque onglet utilise le package PHP fourni par le dépôt depuis lequel cet onglet installe, donc la version dans les commandes diffère d’un onglet à l’autre. Remplacez-le par une autre version PHP listée dans la matrice de support si ce dépôt en propose une différente.

Les pilotes SQLSRV et PDO_SQLSRV utilisent la même dépendance ODBC et peuvent être installés indépendamment. Installez les deux extensions si votre application utilise les deux pilotes.

À la fin de la procédure, la CLI et l’environnement d’exécution du serveur Web sélectionné doivent charger les deux extensions, les deux API PHP doivent être disponibles, et l’échantillon de chaque API doit retourner la version du serveur de base de données.

Avant de commencer

  1. Choisissez une version PHP prise en charge par la version actuelle du pilote et disponible pour votre version du système d’exploitation.

  2. Décidez quels environnements d’exécution PHP vous devez choisir :

    • CLI pour les scripts, les tâches planifiées ou les workers.
    • Module Apache pour PHP exécuté sous Apache.
    • PHP-FPM pour nginx ou une configuration Apache FastCGI.

  3. Confirmez l’architecture du système d’exploitation. Les archives Linux publiées contiennent des binaires x64 et les archives macOS publiées contiennent des binaires Arm64. PIE compile pour l’installation de PHP sur l’ordinateur et constitue la méthode d’installation principale dans cet article.

  4. Installez le pilote Microsoft ODBC et le package de développement unixODBC. Le package Microsoft gère la communication avec la base de données. Le paquet unixODBC fournit les en-têtes nécessaires à la compilation de SQLSRV et PDO_SQLSRV.

  5. Prévoyez de redémarrer chaque serveur web, pool PHP-FPM et worker de longue durée après avoir installé ou modifié une extension.

Le gestionnaire de paquets de plateforme installe PHP et les prérequis natifs. PIE compile et installe les extensions PHP. La configuration PHP contrôle si chaque environnement d’exécution les charge. Le pilote ODBC gère la communication et le chiffrement de la base de données une fois l’extension chargée.

Installez les pilotes avec PIE

PIE, l’installateur PHP pour les extensions, est l’installateur d’extensions pris en charge pour les versions actuelles des pilotes. Il remplace le flux de travail obsolète de la PHP Extension Community Library (PECL).

Remplissez les prérequis de la plateforme dans les sections suivantes avant d’installer les pilotes. Ensuite, installez PIE et chaque pilote séparément :

Installer PIE

PIE fonctionne sous PHP 8.1 et versions ultérieures. Il peut installer une extension dans une autre installation PHP lorsque vous sélectionnez les outils de développement de cette installation.

Installe curl et utilise GitHub CLI avant de continuer. Les sections de la plateforme incluent curl là où une installation minimale pourrait ne pas l’offrir.

Téléchargez l’archive PIE PHP (PHAR), et vérifiez-la avec l’interface en ligne de commande GitHub (CLI) avant de l’installer ou de l’exécuter :

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"

Ne continuez que si la vérification réussit :

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

Le répertoire temporaire est propre à votre compte. Si le téléchargement ou la vérification échoue, n’installez pas et ne lancez pas le PHAR. Supprimez le fichier temporaire et le répertoire avant de réessayer.

Confirmez que le PHAR installé fonctionne avec l’exécutable PHP que vous comptez utiliser :

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

Installez les pilotes SQLSRV et PDO_SQLSRV

Sous Linux et macOS, PIE vérifie le compilateur et les outils de développement PHP dont il a besoin. Installez le paquet de développement ODBC de la plateforme et un compilateur C++ avant d’exécuter PIE. Faites tourner le PIE depuis un terminal interactif. Il peut demander votre sudo mot de passe lorsqu’il a besoin d’une autorisation pour installer des fichiers dans les répertoires système.

PIE cible l’installation PHP utilisée pour l’invoquer. Pour une installation versionnée, ajoutez --with-php-config à chaque commande d’installation pour sélectionner les outils de développement correspondants. Par exemple, utilisez pie install --with-php-config=/usr/bin/php-config8.4 microsoft/sqlsrv lorsque l’outil prévu est /usr/bin/php-config8.4. Appliquez la même option à microsoft/pdo_sqlsrv. Alpine utilise des noms exécutables versionnés ; suivez les commandes Alpine au lieu des commandes non versionnées de cette section.

Exécutez une commande pour chaque extension. Ces commandes utilisent l’installation PHP par défaut de PIE :

pie install microsoft/sqlsrv
pie install microsoft/pdo_sqlsrv

PIE tente d’activer chaque extension via les outils de configuration PHP de la plateforme ou une extension= entrée, et avertit si ce n’est pas possible. PHP utilise une interface de programmation d’applications serveur (SAPI) pour chaque environnement d’exécution. Sur Debian, Ubuntu et SUSE, les configurations en ligne de commande, Apache et PHP FastCGI Process Manager (PHP-FPM) peuvent différer. Une installation réussie en ligne de commande ne confirme pas qu’un serveur web peut charger les pilotes.

Consultez php --ini pour la ligne de commande. Avant de créer une page temporaire phpinfo() pour le serveur web, restreignez l’accès aux pages de diagnostic. Vérifiez le fichier de configuration chargé et les fichiers scannés .ini pour chaque environnement d’exécution. Si les entrées manquent, suivez Charger les pilotes sur Linux et macOS pour les ajouter dans le bon ordre de chargement. Redémarrez le serveur web ou PHP-FPM après des modifications de configuration. Red Hat partage généralement php.ini entre les SAPI, mais vérifiez la configuration active avant de vous appuyer sur une exécution PIE unique.

Installez sur votre plateforme

Sélectionnez votre système d’exploitation et la configuration de votre serveur web. Terminez les étapes d’installation dans cet onglet, puis suivez Tester votre installation.

Installer sur Ubuntu

Note

Les commandes suivantes utilisent le dépôt PHP packages.sury.org afin que vous puissiez sélectionner une version PHP prise en charge. Utilisez les instructions officielles de Microsoft pour installer le pilote ODBC pour votre version Ubuntu.

Étape 1. Installer 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

Étape 2. Prérequis d’installation (Ubuntu)

Suivez Installez le pilote Microsoft ODBC pour SQL Server sur Linux, puis installez les en-têtes de développement.

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

Étape 3. Installez les pilotes PHP pour Microsoft SQL Server avec PIE (Ubuntu)

Suivez la procédure Installer les pilotes avec PIE, en ajoutant --with-php-config=/usr/bin/php-config8.4 aux deux commandes d’installation. Vérifiez les fichiers de configuration de la ligne de commande avec 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

Étape 4. Installer Apache et configurer le chargement du pilote (Ubuntu)

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

Étape 5. Redémarrez Apache et testez l’exemple de script (Ubuntu)

sudo systemctl restart apache2

Pour tester votre installation, consultez Test de votre installation à la fin de ce document.

Ancienne installation de PECL

PECL est déprécié pour les versions actuelles des drivers. Utilisez PIE pour les nouvelles installations et mises à jour. Si un déploiement existant est épinglé à PECL, gardez ses versions de paquet alignées avec le runtime PHP et prévoyez un passage à PIE.

Testez votre installation

Vérifiez le runtime en ligne de commande. Sur Alpine, remplacez php par php84. Pour une installation PHP versionnée sur une autre distribution, utilisez son exécutable correspondant.

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

Les deux --ri commandes doivent imprimer les informations du module incluant ExtensionVer. La liste des modules doit contenir des lignes séparées sqlsrv et pdo_sqlsrv.

Avant de tester une connexion, vérifiez les deux interfaces de l’API PHP avec verify-php-drivers.php:

<?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);

Sortie attendue :

SQLSRV: loaded
PDO_SQLSRV: loaded

Pour PHP-FPM ou un serveur web, restreignez l’accès aux pages de diagnostic avant de créer une page temporaire phpinfo() . Confirmez le fichier de configuration chargé, extension_dir, et les deux sections des pilotes. Redémarrez PHP-FPM ou le serveur web après avoir modifié la configuration ou remplacé une extension. Supprimez la page après vérification.

Pour tester une connexion en direct, créez un fichier appelé testsql.php dans la racine du document de votre système. Ce chemin se trouve /var/www/html sur Ubuntu, Debian et Red Hat, /srv/www/htdocs sur SUSE, /var/www/localhost/htdocs sur Alpine ou $(brew --prefix)/var/www sur macOS. Définissez les variables d’environnement SQL_SERVER_NAME, SQL_DATABASE, SQL_UID et SQL_PWD pour le processus PHP avant d’exécuter le script. N'intégrez pas les identifiants de connexion en dur dans un fichier sous la racine du document.

Pour un test en ligne de commande, utilisez les invites interactives pour définir les variables d’environnement sans entrer de mot de passe dans l’historique du shell.

Pour un test de module Apache, gardez les identifiants hors du fichier de configuration généralement lisible du site :

  1. Créez un fichier privé en dehors de la racine du document. Utilisez un nom de fichier inutilisé dans le répertoire de configuration d’Apache. Sur Linux :

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

    Sur Red Hat, remplacez /etc/apache2 par /etc/httpd. Sur macOS, créez le fichier avec le compte qui démarre l’Apache de Homebrew :

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

    Seuls le propriétaire du fichier et root peuvent lire ces réglages. Le compte qui lance Apache doit pouvoir lire le fichier.

  2. Modifiez le fichier privé dans un éditeur de texte et ajoutez ces entrées :

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

    Dans les arguments entre guillemets doubles, écrivez \\ pour chaque barre oblique inversée littérale et \" pour chaque guillemet double littéral. Conservez les espaces de début et de fin à l’intérieur des guillemets. Apache remplace ${NAME} également les références. Si une valeur contient cette séquence ou une saut de ligne, utilisez plutôt le test en ligne de commande. Pour plus d’informations, voir configuration Apache : guillemets et caractères d’échappement.

  3. À l’intérieur de l’hôte virtuel du site, ajoutez un bloc Files qui inclut uniquement le fichier privé pour testsql.php. Si aucun hôte virtuel n’est configuré, placez le bloc dans la configuration principale du serveur. Remplacez l’espace réservé par le chemin absolu du fichier privé :

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

  4. Redémarrez Apache. Après les tests, supprimez le Files bloc que vous avez ajouté, supprimez le fichier privé, puis redémarrez Apache. Gardez des paramètres du site sans rapport.

PHP-FPM efface par défaut les variables d’environnement héritées, et nginx ne transmet pas son environnement à PHP-FPM. Utilisez la procédure suivante d’Ubuntu ou Red Hat uniquement avec un service PHP-FPM test isolé et un pool. N’ajoutez pas d’identifiants de test à un service ou un pool qui exécute d’autres applications : chaque script de ce pool peut les lire. Si vous utilisez un hébergement partagé, utilisez plutôt le test en ligne de commande.

  1. Créez un fichier appartenant à la racine en dehors de la racine du document, comme /etc/php-sql-driver-test.env, et restreignez l’accès à celui-ci :

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

    Ajoutez les paramètres de connexion au fichier :

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

    Gardez chaque réglage sur une seule ligne. Dans les guillemets doubles, écrivez \\ pour chaque barre oblique inverse littérale et \" pour chaque guillemet double littéral. Les signes dollar et les guillemets inversés ne sont pas évalués comme des expressions du shell. Éditez le fichier directement plutôt que de l’exécuter ou de le sourcer dans un shell. Pour plus d’informations, voir la syntaxe EnvironmentFile de systemd.

  2. Faites tourner sudo systemctl edit php8.4-fpm sur Ubuntu ou sudo systemctl edit php-fpm sur Red Hat. Ajoutez ce remplacement systemd :

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

  3. Ajoutez ces entrées à la configuration du pool PHP-FPM actif. Les emplacements courants sont /etc/php/8.4/fpm/pool.d/www.conf sur Ubuntu et /etc/php-fpm.d/www.conf sur Red Hat :

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

  4. Rechargez la configuration de systemd et redémarrez le service PHP-FPM applicable :

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

    Sur Red Hat, remplacez php8.4-fpm par php-fpm.

Après les tests, supprimez le fichier d’environnement temporaire, l’entrée EnvironmentFile= que vous avez ajoutée, les entrées du pool de test, et testsql.php. Supprimez le fichier de dérogation du service uniquement si vous l’avez créé pour ce test et qu’il ne contient aucun autre paramètre. Conservez tous les paramètres de dérogation et de groupe existants. Rechargez systemd et redémarrez PHP-FPM après avoir supprimé la configuration de test.

Exemple SQLSRV

Gardez les valeurs d’environnement inchangées. Chaque exemple rejette les paramètres manquants ou vides avant de se connecter. Chaque exemple double alors 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');
$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);
?>

Exemple 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);
?>

Dirigez votre navigateur vers http://localhost/testsql.php (http://localhost:8080/testsql.php sur macOS). Une connexion réussie affiche la chaîne de versions du serveur de base de données. Les deux exemples écrivent les détails des erreurs dans le journal d’erreurs PHP. Si la page affiche une erreur, vérifiez ce log.

Pour comparer le comportement en ligne de commande et en serveur web, définissez les mêmes variables d’environnement pour votre terminal et exécutez :

php testsql.php

Si l’exécution depuis la ligne de commande réussit mais que rien n’apparaît dans votre navigateur, vérifiez les fichiers journaux Apache. Pour plus d’aide, consultez les ressources de support pour le pilote SQL PHP.

Évaluez séparément les connecteurs pour SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics, la base de données SQL dans Microsoft Fabric et Warehouse dans Microsoft Fabric. La méthode d’authentification sélectionnée, les options de connexion et la requête doivent être prises en charge par la cible. L’installation se fait côté client. Une vérification réussie des extensions ne prouve pas qu’une cible accepte les identifiants, fait confiance au client ou supporte toutes les fonctionnalités de la base de données.

Résoudre les problèmes d’installation

Symptôme Couche propriétaire Mesure corrective
PIE ne trouve pas phpize, php-config, ni les en-têtes Packages de développement PHP Installez le paquet de développement pour la version PHP cible et passez l’option correspondante --with-php-config
La compilation échoue car un compilateur C++ manque Outils de compilation du système d’exploitation Installer le package du compilateur C++ de la plateforme, tel que g++ ou gcc-c++
La compilation ne peut pas trouver sql.h Chemins des paquets de développement ODBC ou du compilateur Installez unixodbc-dev ou unixODBC-devel; sur les Mac Apple silicon, définir les options Homebrew include et library
php --ri dit que l’extension n’est pas présente Configuration PHP Inspectez le php.ini chargé et analysez le répertoire, ajoutez la bonne entrée, puis redémarrez le processus
Rapports PDO could not find driver Chargement de PDO_SQLSRV ou ordre de chargement de PDO Confirmez que le PDO charge d’abord et que PDO_SQLSRV utilise un fichier de configuration analysé ultérieurement
CLI fonctionne mais Apache, nginx ou PHP-FPM échouent Configuration spécifique au SAPI Comparez la sortie CLI avec phpinfo(), configurez le SAPI web, puis redémarrez-le
Le navigateur retourne HTTP 502 via nginx Routage de nginx vers PHP-FPM Vérifiez le fastcgi_pass socket avec la version PHP-FPM installée et confirmez que le service fonctionne
L’exemple de navigateur signale des valeurs d’environnement manquantes Serveur web ou environnement PHP-FPM Configurez les variables pour l’exécution web sélectionnée, puis redémarrez-la
Les extensions se chargent mais la connexion n’aboutit pas ODBC, réseau, certificat, authentification ou produit SQL Lisez l’état SQLSTATE et l’erreur native depuis le journal serveur ; ne reconstruisez pas l’extension à moins que l’erreur n’indique un chargement ou une compatibilité binaire

Supprimer la configuration de test temporaire

Après vérification :

  1. Supprimez testsql.php, verify-php-drivers.php, et toute page temporaire phpinfo() de la racine du document.

  2. Supprimez les identifiants temporaires et les entrées de redirection d’environnement.

  3. Rechargez la configuration du gestionnaire de services lorsque vous changez un fichier de surcharge systemd, puis redémarrez PHP-FPM ou le serveur web.

  4. Conservez les entrées d’extension et les paquets installés que l’application exige.

Contenu connexe

  • Dernière mise à jour :