Vue d’ensemble des pilotes Microsoft pour PHP pour SQL Server

Télécharger le pilote PHP

Les pilotes Microsoft pour PHP pour SQL Server incluent deux extensions PHP, SQLSRV et PDO_SQLSRV. PDO_SQLSRV implémente l’interface PHP Data Objects (PDO). Les deux extensions utilisent le pilote Microsoft ODBC pour SQL Server afin de se connecter à Microsoft SQL. Leurs API PHP, leurs options spécifiques au pilote et leurs types de PHP par défaut diffèrent. Par exemple, SQLSRV renvoie par défaut des valeurs de date et d’heure comme DateTime objets, tandis que PDO_SQLSRV renvoie des chaînes par défaut. Pour les exigences système, voir Exigences système pour les pilotes Microsoft pour PHP pour SQL Server.

Choisissez SQLSRV ou PDO_SQLSRV

Si vous... Utiliser
Démarrer un nouveau projet sans code PDO ailleurs Choisissez l’interface que votre application utilisera de manière cohérente. SQLSRV expose des fonctions procédurales et des descripteurs de paramètres explicites. PDO_SQLSRV s’adapte au code organisé autour des objets PDO et PDOStatement.
J’utilise déjà PDO avec une autre base de données (MySQL, PostgreSQL, SQLite) PDO_SQLSRV, donc votre couche d’accès aux données reste cohérente entre les bases de données.
Utilisez un framework ou une bibliothèque qui attend un objet de connexion PDO PDO_SQLSRV.
Besoin d’un contrôle manuel, morceau par morceau, du moment où les données du flux sont envoyées SQLSRV, avec sqlsrv_send_stream_data(). PDO_SQLSRV prend aussi en charge le streaming de grandes valeurs, en liant une ressource de flux PHP avec PDO::PARAM_LOB, mais il envoie l’ensemble du flux automatiquement pendant execute() plutôt que dans des chunks contrôlés par l’appelant.
Maintenir une application qui appelle déjà des fonctions sqlsrv_* SQLSRV, à moins que vous ne prévoyiez de réécrire son code d’accès aux données pour PDO.

Installez soit une extension, soit les deux. Les téléchargements Windows contiennent des binaires d’extension séparés ; sous Linux et macOS, installez séparément les paquets sqlsrv et pdo_sqlsrv. Vous pouvez charger les deux dans le même processus PHP. SQLSRV retourne les ressources de connexion et d’instruction ; PDO_SQLSRV retourne les objets PDO et PDOStatement. Ne faites pas passer une ressource d’une API à l’autre.

Utiliser PDO ne rend pas la syntaxe Transact-SQL (T-SQL) portable vers une autre base de données. PDO vous offre une interface PHP commune ; vos requêtes, schéma, authentification et attributs spécifiques au pilote peuvent toujours être spécifiques à Microsoft SQL. De même, utiliser l’extension procédurale ne nécessite pas d’organisation procédurale dans toute votre application : vous pouvez appeler SQLSRV depuis vos propres classes.

Comparez le même résultat dans les deux API

Exécutez ces programmes avant de choisir la représentation PHP attendue par votre application. Ils sélectionnent le même entier, la même date et la même requête SQL NULL, mais les paramètres par défaut ne sont pas identiques. Aucun tableau ni base de données d’exemple n’est requis.

Installez et chargez l’extension sélectionnée. Définissez SQL_SERVER, SQL_DATABASE, SQL_USER, et SQL_PASSWORD dans l’environnement de processus pour une base de données de test SQL Server existante. Le certificat serveur doit être approuvé et correspondre au point de terminaison configuré. Pour la configuration et les alternatives Azure sans mot de passe, voir Connexion au serveur.

SQLSRV

Enregistrez ce programme complet sous le nom de compare-sqlsrv.php, et exécutez php compare-sqlsrv.php.

<?php
$config = [];
foreach (['SQL_SERVER', 'SQL_DATABASE', 'SQL_USER', 'SQL_PASSWORD'] as $name) {
    $value = getenv($name);
    if ($value === false || $value === '') {
        throw new RuntimeException("Set $name before running this example.");
    }
    $config[$name] = $value;
}
foreach (['SQL_DATABASE', 'SQL_USER', 'SQL_PASSWORD'] as $name) {
    $config[$name] = '{' . str_replace('}', '}}', $config[$name]) . '}';
}
$conn = sqlsrv_connect($config['SQL_SERVER'], [
    'Database' => $config['SQL_DATABASE'],
    'UID' => $config['SQL_USER'],
    'PWD' => $config['SQL_PASSWORD'],
    'Encrypt' => true,
    'TrustServerCertificate' => false,
    'LoginTimeout' => 30,
    'CharacterSet' => 'UTF-8',
]);
if ($conn === false) {
    throw new RuntimeException(print_r(sqlsrv_errors(), true));
}
$stmt = null;
try {
    $stmt = sqlsrv_query($conn, "SELECT CAST(42 AS int) AS CountValue, "
        . "CAST('2026-10-19' AS date) AS DayValue, CAST(NULL AS int) AS Missing");
    if ($stmt === false) {
        throw new RuntimeException(print_r(sqlsrv_errors(), true));
    }
    $row = sqlsrv_fetch_array($stmt, SQLSRV_FETCH_ASSOC);
    if ($row === false) {
        throw new RuntimeException(print_r(sqlsrv_errors(), true));
    }
    if (!is_array($row) || $row['CountValue'] !== 42
        || !($row['DayValue'] instanceof DateTime)
        || $row['DayValue']->format('Y-m-d') !== '2026-10-19'
        || $row['Missing'] !== null) {
        throw new RuntimeException('Unexpected SQLSRV values or default types.');
    }
    echo get_debug_type($row['CountValue']), ', ',
        get_debug_type($row['DayValue']), ', ', get_debug_type($row['Missing']), PHP_EOL;
} finally {
    if (is_resource($stmt)) {
        sqlsrv_free_stmt($stmt);
    }
    sqlsrv_close($conn);
}

Sortie attendue :

int, DateTime, null

PDO_SQLSRV

Enregistrez ce programme séparé sous le nom de compare-pdo.php, et exécutez php compare-pdo.php. Il laisse délibérément la récupération des valeurs numériques et des dates à leurs valeurs par défaut PDO_SQLSRV.

<?php
$config = [];
foreach (['SQL_SERVER', 'SQL_DATABASE', 'SQL_USER', 'SQL_PASSWORD'] as $name) {
    $value = getenv($name);
    if ($value === false || $value === '') {
        throw new RuntimeException("Set $name before running this example.");
    }
    $config[$name] = $value;
}
foreach (['SQL_DATABASE', 'SQL_USER', 'SQL_PASSWORD'] as $name) {
    $config[$name] = '{' . str_replace('}', '}}', $config[$name]) . '}';
}
$server = $config['SQL_SERVER'];
$database = $config['SQL_DATABASE'];
$pdo = new PDO(
    "sqlsrv:Server=$server;Database=$database;Encrypt=true;"
    . "TrustServerCertificate=false;LoginTimeout=30",
    $config['SQL_USER'],
    $config['SQL_PASSWORD'],
    [
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
        PDO::SQLSRV_ATTR_ENCODING => PDO::SQLSRV_ENCODING_UTF8,
    ]
);
$stmt = null;
try {
    $stmt = $pdo->query("SELECT CAST(42 AS int) AS CountValue, "
        . "CAST('2026-10-19' AS date) AS DayValue, CAST(NULL AS int) AS Missing");
    $row = $stmt->fetch(PDO::FETCH_ASSOC);
    if ($row !== ['CountValue' => '42', 'DayValue' => '2026-10-19', 'Missing' => null]) {
        throw new RuntimeException('Unexpected PDO_SQLSRV values or default types.');
    }
    echo get_debug_type($row['CountValue']), ', ',
        get_debug_type($row['DayValue']), ', ', get_debug_type($row['Missing']), PHP_EOL;
} finally {
    $stmt = null;
    $pdo = null;
}

Sortie attendue :

string, string, null

Les deux programmes demandent explicitement des clés de résultats nommées. Ces tableaux PHP utilisent des noms de colonnes tels que CountValue, plutôt que des indices numériques commençant à 0. Un SQL NULL devient PHP null dans l’une ou l’autre des API. Ce n’est pas la chaîne vide ni une ligne de résultats manquante.

Les deux programmes lisent le nom réel de la base de données, le nom d’utilisateur et le mot de passe depuis l’environnement. Ces valeurs sont échappées une fois pour la gestion de connexion de type ODBC du pilote PHP. Doubler les accolades fermantes et inclure la valeur entre accolades préserve les caractères spéciaux ; cela ne renomme pas la base de données ni ne modifie le mot de passe stocké. Pour plus d’informations, voir Connexion au serveur.

Les exemples s’arrêtent sur les erreurs et libèrent des ressources au niveau de finally. SQLSRV rapporte les défaillances de la base de données via false et sqlsrv_errors(); PDO_SQLSRV lève des exceptions pour les échecs de connexion et utilise des exceptions pour les échecs de requête avec le mode d’erreur configuré. Dans une application web, détectez ces exceptions dans le code qui gère la requête. Enregistrez les détails de diagnostic dans des journaux protégés au lieu de les renvoyer au navigateur.

Après l’exercice, supprime compare-sqlsrv.php et compare-pdo.php si tu n’en as plus besoin. Effacez les variables d’environnement des identifiants du processus de test lorsque vous avez terminé.

Choisir les types, l’encodage et la gestion des erreurs

Décidez quels types PHP votre application attend, comment elle gère le texte et les erreurs, et quand elle libère les ressources de la base de données.

Décision SQLSRV PDO_SQLSRV Effet sur le code applicatif
Types de résultats entiers Entiers PHP natifs pour les colonnes SQL int. Chaînes par défaut ; les requêtes PDO::SQLSRV_ATTR_FETCHES_NUMERIC_TYPE acceptent les types PHP numériques. Les comparaisons strictes et les sorties sérialisées peuvent différer. Ne supposez pas que chaque type numérique SQL correspond à un entier PHP ou à un float.
Résultats de dates et d’heures DateTime sélectionne les objets par défaut ; ReturnDatesAsStrings sélectionne des chaînes de caractères. Des chaînes par défaut ; PDO::SQLSRV_ATTR_FETCHES_DATETIME_TYPE sélectionne des objets. Normalisez la représentation avant de la sérialiser ou de la passer au code applicatif.
Codage des caractères Définissez CharacterSet => 'UTF-8' explicitement. UTF-8 est la norme par défaut ; configurez-la avec PDO::SQLSRV_ATTR_ENCODING. Ne transférez pas l’option SQLSRV dans un DSN PDO.
Gestion des erreurs Vérifiez false et capturez immédiatement la collection complète d’erreurs SQLSRV. Configurer PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION. Une ligne manquante et une requête ratée nécessitent une gestion différente.
Réutilisation des paramètres Liez les variables par référence dans les descripteurs sqlsrv_prepare(). Utilisez bindParam() pour une variable ou bindValue() pour sa valeur actuelle. La réattribution de la variable affecte une liaison de référence, pas une liaison à une valeur précédente.
Nettoyage Libérez les instructions, puis fermez la ressource de connexion. Références à l’instruction release, puis à l’objet PDO. Une requête peut maintenir une connexion PDO active après qu’une autre référence est définie à null.

Si vous migrez une application existante, testez ces comportements avec des valeurs représentatives avant de modifier son code de base de données. Inclure le texte non ASCII, SQL NULL, les dates, les valeurs décimales exactes et les paramètres de sortie des procédures stockées. Comparez aussi comment votre framework configure les attributs PDO. Remplacer uniquement les noms de fonctions ne migre pas la gestion des erreurs, la liaison de références ou les types PHP retournés.

Pour un exemple de flux de travail d’écriture et de lecture avec les deux API, utilisez le guide de programmation. Pour les exécutions répétées et les entrées saisies, utilisez Comparer les fonctions d’exécution de requête.

Sachez à quoi sert chaque composant

Votre choix d’extension modifie l’API PHP et ses conversions de type. Les deux extensions utilisent ODBC pour communiquer avec le serveur, chiffrer les connexions et s’authentifier auprès du serveur. Le système d’exploitation fournit des certificats et des services de confiance tels que l’authentification Windows ou Kerberos. La cible SQL contrôle les permissions, le schéma et les instructions T-SQL prises en charge.

Les programmes de comparaison utilisent l’authentification SQL pour se connecter à SQL Server. Pour Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics, SQL database dans Fabric ou Warehouse dans Fabric, configurez le point de terminaison de service et l’authentification prise en charge avant de réutiliser le motif de récupération. Les deux produits Fabric nécessitent une authentification Microsoft Entra ID ; Warehouse nécessite également de désactiver plusieurs ensembles de résultats actifs (MARS). Une comparaison de types réussie sur SQL Server n'établit pas qu'une cible différente supporte toutes les fonctionnalités listées dans cet aperçu.

Ce que fournissent les deux extensions

  • Authentification intégrée, authentification SQL et authentification Microsoft Entra ID, en fonction de la prise en charge par la cible. L’identité gérée n’utilise pas de mot de passe d’application ; ActiveDirectoryServicePrincipal utilise un identifiant client et un secret client. Pour plus d’informations, voir Connexion au serveur.
  • requêtes paramétrées, instructions préparées et paramètres directionnels (entrée/sortie). Pour plus d’informations, voir Comparer les fonctions d’exécution et Utilisation des paramètres directionnels.
  • Transactions, paramètres d’entrée de flux pour les valeurs de caractères et binaires de grande taille, et paramètres à valeurs de table.
  • Always Encrypted, y compris les enclaves sécurisées si le pilote ODBC et SQL Server cible les prennent en charge. Pour plus d’informations, voir Utilisation de Always Encrypted avec les pilotes Microsoft pour PHP pour SQL Server.
  • Connexions à 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 fonctionnalités d’authentification et SQL varient selon la cible ; voir connexions Azure et Fabric.

Contenu connexe

  • Dernière mise à jour :