Configuration système requise pour les pilotes Microsoft pour PHP pour SQL Server

Télécharger le pilote PHP

Cet article liste les composants que vous devez installer sur votre système pour accéder aux données dans SQL Server ou Azure SQL Database en utilisant soit le pilote SQLSRV, soit PDO_SQLSRV.

Pour plus d’informations sur les cycles de vie de support et les exigences des pilotes PHP, consultez la matrice de support. Les pilotes SQLSRV et PDO_SQLSRV dans chaque version ont les mêmes exigences en PHP, système d’exploitation, architecture, sécurité des threads et ODBC.

Comment la pile de pilotes s’assemble

Une application PHP ne se connecte pas directement au serveur de base de données. Chaque couche doit être compatible avec la couche adjacente :

SQLSRV et PDO_SQLSRV fournissent différentes API PHP sur le même pilote ODBC. Installez les deux lorsque votre application utilise les deux API. Installer une extension ne permet pas d’installer ou d’activer automatiquement l’autre.

Les extensions peuvent être installées indépendamment. PDO_SQLSRV nécessite aussi que le PDO se charge avant PDO_SQLSRV.

Choisissez un ensemble compatible

Avant de télécharger ou de compiler un pilote, effectuez ces vérifications :

1. Identifiez tous les environnements d’exécution PHP qui servent l’application. Une tâche planifiée, un worker en ligne de commande, un site IIS, un module Apache et un pool PHP-FPM peuvent utiliser différents exécutables PHP et fichiers de configuration.

2. Exécutez la commande suivante avec chaque exécutable PHP :

   php -i | findstr /I "PHP Version Architecture Thread Safety extension_dir"
   

   Sous Linux ou macOS, utilisez :

   php -i | grep -E "PHP Version|Thread Safety|extension_dir"
   file "$(php -r 'echo PHP_BINARY;')"
   

   La commande file indique l’architecture de l’exécutable. S’il indique un exécutable universel macOS, sélectionnez explicitement l’architecture prévue, telle que arch -arm64 php --version ou arch -x86_64 php --version. Utilisez la même sélection d’architecture lors de la construction, du chargement et des tests des extensions.

3. Sélectionnez une version de pilote PHP qui prend en charge la version mineure de PHP, le système d’exploitation et la cible de base de données.

4. Sélectionnez une version prise en charge du pilote Microsoft ODBC dans la table de compatibilité de cet article.

5. Associez le fichier d’extension ou la compilation PIE à l’architecture PHP et au mode de sécurité des threads. Ne copiez pas une extension depuis une autre installation de PHP, sauf si toutes les valeurs suivantes correspondent.

6. Configurez et vérifiez séparément les environnements d’exécution de la CLI et du serveur web. Une commande réussie php -m prouve seulement que le runtime CLI a chargé l’extension.

PHP

Téléchargez des binaires PHP depuis le site PHP. Choisissez une version PHP listée dans le support des versions PHP.

• Activez le fichier du pilote qui correspond à votre version PHP. Pour les noms de fichiers, voir Versions des pilotes. Téléchargez les fichiers depuis Télécharger les pilotes Microsoft pour PHP pour SQL Server. Pour obtenir les instructions de configuration, consultez Charger les pilotes Microsoft pour PHP pour SQL Server.

• Choisissez un serveur web et une méthode d’intégration PHP supportés par PHP et votre framework applicatif. Suivez la documentation d’installation de PHP et les instructions de déploiement de votre framework pour configurer le serveur web afin d’exécuter PHP. Vérifiez le chargement des extensions dans l’environnement d’exécution du serveur web séparément de la ligne de commande.

Sécurité des threads et architecture

Le build PHP et le fichier d’extension doivent s’accorder sur les deux valeurs.

La CLI peut utiliser une version PHP thread-safe ou non thread-safe. Sélectionnez l’extension en fonction de la valeur indiquée, plutôt que de supposer que toutes les versions CLI sont non thread-safe.

Pilote ODBC

Installez un pilote Microsoft ODBC compatible pour SQL Server sur l’ordinateur qui exécute PHP. Téléchargez le pilote depuis Download ODBC Driver for SQL Server.

Si vous téléchargez la version Windows du pilote sur une version 64 bits de Windows, le programme d’installation ODBC 64 bits installe les pilotes ODBC 32 bits et 64 bits. Si vous utilisez une version 32 bits de Windows, utilisez le programme d’installation ODBC x86. Sur les plateformes non Windows, seules les versions 64 bits du pilote sont disponibles.

Le tableau inclut les combinaisons historiques pour la planification des mises à niveau. Utilisez la version actuelle du pilote PHP et ses versions ODBC listées pour une nouvelle installation. La compatibilité avec une version antérieure ne prolonge pas son cycle de vie de support. Vérifiez à la fois le cycle de vie de la prise en charge du pilote PHP et les versions prises en charge par PHP.

Une cellule vierge ne signifie pas que le pilote PHP rejette nécessairement cette version ODBC. Les fonctionnalités individuelles peuvent nécessiter des versions ODBC plus récentes que la combinaison de base.

Si vous utilisez le pilote SQLSRV, sqlsrv_client_info retourne des informations sur la version du pilote ODBC Microsoft pour SQL Server utilisée par les pilotes Microsoft pour PHP pour SQL Server. Si vous utilisez le pilote PDO_SQLSRV, vous pouvez utiliser PDO::getAttribute pour découvrir la version.

SQL Server

Pour les versions prises en charge de SQL Server, voir Versions prises en charge de la base de données.

Évaluez séparément la prise en charge de chaque cible : SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics, base de données SQL dans Microsoft Fabric et entrepôt de données dans Microsoft Fabric. Les exigences d'installation sont celles côté client et n'établissent pas que chaque méthode d'authentification, option de connexion, fonctionnalité Transact-SQL (T-SQL) ou type de données est disponible sur chaque plateforme cible. Utilisez la matrice de support et la documentation du produit cible pour le scénario utilisé par votre application.

Systèmes d’exploitation

Pour les systèmes d’exploitation pris en charge, voir Systèmes d’exploitation pris en charge.

Versions de pilotes

Chaque version des Microsoft Drivers for PHP for SQL Server propose les fichiers pilotes SQLSRV et PDO_SQLSRV en variantes thread-safe et non-thread-safe. Sous Windows, chaque variante est également compilée pour PHP 32 bits et 64 bits. Associez le fichier du pilote à votre version PHP, au mode de sûreté des threads et à votre architecture. Pour activer un fichier de pilote après l’avoir téléchargé, voir Chargement des pilotes Microsoft pour PHP pour SQL Server.

Sous Linux et macOS, installez les drivers avec PIE, l’installateur PHP pour les extensions, comme décrit dans les instructions d’installation Linux et macOS. PIE remplace le système de paquets PHP Extension Community Library (PECL ) obsolète et nomme l’extension sqlsrv.so installée ou pdo_sqlsrv.so. Les tableaux suivants listent les noms de fichiers des paquets binaires préconstruits que vous téléchargez manuellement depuis la page Microsoft Drivers for PHP for SQL Server releases.

Les tableaux suivants listent les fichiers des paquets de version 5.13. Dans les noms de fichiers, ts et TS signifient thread-safe, et nts et NTS signifient non-thread-safe.

Fichiers de pilotes Windows

Le Windows_5.13.xRTW.zip paquet contient ces fichiers.

Utilisez un fichier pilote non thread-safe avec une version PHP non thread-safe, et un fichier pilote thread-safe avec une version PHP thread-safe. L’interface de ligne de commande (CLI) peut utiliser l’une ou l’autre des versions. Pour vérifier la version dont vous disposez, exécutez php -i et vérifiez la valeur Thread Safety.

Fichiers de pilotes Linux et macOS

Les packages Linux_5.13.xRTW.tar.gz et Mac_5.13.xRTW.tar.gz contiennent ces fichiers. L’archive Linux contient des binaires x64, et l’archive macOS contient des binaires Arm64.

Les fichiers préconstruits doivent également correspondre aux bibliothèques natives de votre système d’exploitation. Les binaires Linux 5.13.3 nécessitent glibc 2.38 et versions ultérieures ainsi qu’un runtime C++ qui fournit GLIBCXX_3.4.32. Les binaires de macOS 5.13.3 déclarent macOS 26 comme leur cible minimale de déploiement. Ces exigences binaires sont distinctes de la prise en charge des systèmes d’exploitation pour les compilations à partir des sources.

Utilisez PIE lorsque l’architecture de l’archive ou les exigences de la bibliothèque native ne correspondent pas à votre installation PHP. PIE génère des compilations pour la version de PHP installée et les bibliothèques natives. Ne remplacez pas manuellement les bibliothèques système pour charger une extension préconstruite.

Copiez chaque fichier dont vous avez besoin dans votre répertoire d’extensions PHP. Vous pouvez garder le nom de fichier package et écrire extension=SQLSRV_8.4_NTS.so, ou renommer le fichier en sqlsrv.so et écrire la forme extension=sqlsrvcourte . Appliquez le même choix de nom à PDO_SQLSRV. Pour trouver le répertoire d’extension, exécutez php -i | grep extension_dir. Suivez les instructions de Charger les pilotes sous Linux et macOS pour activer les extensions dans le bon fichier de configuration et charger les Objets de données PHP (PDO) avant PDO_SQLSRV.

Versions antérieures

Pour les fichiers de pilotes inclus dans les versions antérieures à la 5.13, téléchargez le paquet de cette version depuis la page des versions Microsoft Drivers for PHP for SQL Server et listez son contenu. Les versions antérieures à la 5.12 publient un paquet séparé pour chaque système d’exploitation et chaque version de PHP au lieu d’un paquet unique par plateforme.

Vérifiez l’environnement sélectionné

Effectuez ces vérifications après avoir installé les extensions PHP et le pilote ODBC, mais avant de configurer un serveur web :

php --version
php --ini
php --ri sqlsrv
php --ri pdo_sqlsrv

Les deux dernières commandes doivent afficher des sections d’information de module séparées. Si l’une des commandes indique que l’extension n’est pas présente, terminez la procédure d’installation et de chargement de la plateforme avant de tester une connexion à la base de données.

Créer verify-php-drivers.php pour vérifier les deux API PHP sans nécessiter d’identifiants :

<?php
$failures = [];

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

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

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

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

Exécutez-le avec l’exécutable PHP qui sert l’application :

php verify-php-drivers.php

Sortie attendue :

SQLSRV and PDO_SQLSRV are loaded.

Cette vérification vérifie le chargement des extensions. Il ne vérifie pas la connectivité ODBC, l’authentification, la confiance des certificats, l’accès au réseau ou les autorisations de la base de données.

Supprimez verify-php-drivers.php après avoir enregistré le résultat.

Diagnostiquer les échecs liés aux exigences

Contenu connexe

• Bien démarrer avec les pilotes Microsoft pour PHP pour SQL Server
• Guide de programmation pour les pilotes Microsoft pour PHP pour SQL Server
• Informations de référence sur l’API du pilote SQLSRV
• Référence du pilote PDO_SQLSRV