Pilotes Microsoft pour PHP pour SQL Server

Télécharger le pilote PHP

Les pilotes Microsoft pour PHP pour SQL Server sont des extensions PHP qui permettent de lire et d’écrire des données dans le Microsoft SQL Moteur de base de données à partir de scripts PHP. Le package propose deux pilotes qui encapsulent le même pilote Microsoft ODBC pour SQL Server et partagent les mêmes options de connexion, vous permettant de choisir l’API qui correspond à votre base de code :

  • SQLSRV expose une API procédurale (sqlsrv_*fonctions) adaptée aux fonctionnalités de SQL Server.
  • PDO_SQLSRV implémente l’interface PHP Data Objects (PDO), de sorte que le code qui utilise déjà le PDO pour d’autres bases de données puisse cibler SQL Server avec des modifications minimales.

Les deux pilotes se connectent à Azure SQL Database, SQL Database dans Microsoft Fabric, Azure SQL Managed Instance, ainsi qu’à toutes les versions et éditions supportées de SQL Server (y compris les éditions Express). Ils utilisent des flux PHP pour déplacer de grandes valeurs binaires et de caractères sans les charger entièrement en mémoire.

Choisir votre point de départ

Objectif Commencer ici
Configurez un environnement de développement PHP et lancez votre première requête Étape 1 : Configurez l’environnement de développement, puis Étape 2 : Créez une base de données SQL et Étape 3 : Preuve de concept se connectant à SQL en utilisant PHP.
Installez le pilote sous Linux ou macOS Tutoriel d’installation pour Linux et macOS et téléchargez les pilotes Microsoft pour PHP pour SQL Server.
Connectez-vous à Azure SQL avec une authentification sans mot de passe Connectez-vous en utilisant les options d’authentification et de connexion Microsoft Entra.
Rendez une application existante résiliente aux pannes transitoires Résilience des connexions inactives et Étape 4 : Connectez-vous résiliemment au SQL avec PHP.
Décidez entre SQLSRV et PDO_SQLSRV Aperçu des pilotes Microsoft pour PHP pour SQL Server et Comparaison des fonctions d’exécution.
Diagnostiquer un problème d’installation, de connexion ou de requête Dépannage, gestion des erreurs et avertissements, et exploitation de journalisation.
Accélérez la création d’une application existante Réglage de performance.

Connexion rapide

Le extrait suivant est la connexion de bout en bout la plus courte qu’une installation PHP fonctionnelle puisse exécuter sur SQL Server ou Azure SQL. Utilisez-le pour confirmer que votre pilote, les dépendances ODBC et le chemin réseau sont câblés avant de passer à la ligne de base de production dans la section suivante.

<?php
$server   = getenv('SQL_SERVER')   ?: 'localhost';
$database = getenv('SQL_DATABASE') ?: 'master';
$user     = getenv('SQL_USER');
$password = getenv('SQL_PASSWORD');

$dsn = "sqlsrv:Driver={ODBC Driver 18 for SQL Server};Server=$server;Database=$database;Encrypt=true";
$pdo = new PDO($dsn, $user, $password, [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
]);

foreach ($pdo->query('SELECT @@VERSION AS version') as $row) {
    echo $row['version'], PHP_EOL;
}

Pour une connexion sans mot de passe avec Azure SQL, ajoutez Authentication=ActiveDirectoryMsi (identité gérée) ou une autre Authentication valeur au DSN et supprimez les $user/$password arguments. La base de production qui suit développe le même schéma avec des tentatives, des délais d’attente et des diagnostics.

Pour un SQL Server local utilisant un certificat auto-signé, Encrypt=true la validation échoue. Ajouter TrustServerCertificate=true uniquement pour le développement local. Voir les erreurs de certificat TLS pour les alternatives de production.

Base de référence de production pour Azure SQL

Utilisez cet extrait comme point de départ pour une connexion Azure SQL orientée production avec le pilote PDO_SQLSRV. Il lit le serveur et la base de données à partir des variables d’environnement (par exemple, les paramètres de l’application Azure App Service), s’authentifie avec une identité managée, active la sécurité de la couche de transport (TLS) avec la validation des certificats serveur, définit un délai d’expiration de connexion couvre un basculement à froid, et définit ConnectRetryCount une ConnectRetryInterval résilience de connexion inactive pour SQL Server. Les applications connectWithRetry au niveau application et queryWithRetry les assistants enveloppent à la fois la connexion initiale et chaque instruction avec un backoff exponentiel borné, et séparent les erreurs de connexion transitoires (qui nécessitent une connexion fraîche) des erreurs de requête transitoires (qui réutilisent la même connexion).

Nécessite PHP 8.0 et versions ultérieures, l’extension PDO_SQLSRV, et Microsoft pilote ODBC pour SQL Server 17.3.1.1 et versions ultérieures pour Authentication=ActiveDirectoryMsi. Pour la liste complète des valeurs prises en chargeAuthentication, voir Connect using Microsoft Entra authentication.

<?php
declare(strict_types=1);

// Transient errors that require a fresh connection to recover. SQLSTATE values
// starting with '08' cover ODBC connection-established and connection-broken
// states (for example, 08001, 08S01).
const CONNECT_RETRY_SQLSTATE_PREFIX = '08';

// SQL Server error codes that are transient regardless of when they surface:
// 1205 (deadlock victim), 1222 (lock request timeout), and the Azure SQL
// throttling, mid-query failover, and "database not currently available"
// codes that arrive with SQLSTATE HY000.
const TRANSIENT_SERVER_ERROR_CODES = [1205, 1222, 40501, 40613, 40197, 10928, 10929, 49918];

/**
 * Open a connection, retrying transient failures with exponential backoff.
 */
function connectWithRetry(string $dsn, array $options, int $maxAttempts = 3): PDO
{
    for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
        try {
            $pdo = new PDO($dsn, null, null, $options);
            error_log(sprintf('connected on attempt %d/%d', $attempt, $maxAttempts));
            return $pdo;
        } catch (PDOException $e) {
            $sqlstate = (string) $e->getCode();
            $driverCode = isset($e->errorInfo[1]) ? (int) $e->errorInfo[1] : 0;
            $isTransient = str_starts_with($sqlstate, CONNECT_RETRY_SQLSTATE_PREFIX)
                || in_array($driverCode, TRANSIENT_SERVER_ERROR_CODES, true);
            if (!$isTransient || $attempt === $maxAttempts) {
                error_log(sprintf('connect failed on attempt %d/%d: %s', $attempt, $maxAttempts, $e->getMessage()));
                throw $e;
            }
            $delay = 2 ** ($attempt - 1); // 1, 2, 4 seconds
            error_log(sprintf('connect attempt %d hit transient %s/%d; retrying in %d seconds', $attempt, $sqlstate, $driverCode, $delay));
            sleep($delay);
        }
    }
    throw new RuntimeException('connectWithRetry exhausted retries');
}

/**
 * Run a parameterized query, retrying transient statement failures on the same
 * connection. Deadlocks (1205) roll back the transaction before the driver sees
 * the error, so rerunning a single statement is safe. If the statement was part
 * of a multistatement transaction, wrap the whole transaction in your own retry
 * loop so earlier statements replay too.
 */
function queryWithRetry(PDO $pdo, string $sql, array $params = [], int $maxAttempts = 3): PDOStatement
{
    for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
        try {
            $stmt = $pdo->prepare($sql);
            $stmt->execute($params);
            return $stmt;
        } catch (PDOException $e) {
            $driverCode = isset($e->errorInfo[1]) ? (int) $e->errorInfo[1] : 0;
            $isTransient = in_array($driverCode, TRANSIENT_SERVER_ERROR_CODES, true);
            if (!$isTransient || $attempt === $maxAttempts) {
                error_log(sprintf('query failed on attempt %d/%d: %s', $attempt, $maxAttempts, $e->getMessage()));
                throw $e;
            }
            $delay = 2 ** ($attempt - 1);
            error_log(sprintf('query attempt %d hit transient code %d; retrying in %d seconds', $attempt, $driverCode, $delay));
            sleep($delay);
        }
    }
    throw new RuntimeException('queryWithRetry exhausted retries');
}

// Load endpoint details from application configuration. In Azure App Service,
// these can come from app settings or Key Vault-backed settings.
$server = getenv('SQL_SERVER') ?: null;
$database = getenv('SQL_DATABASE') ?: null;

if ($server === null || $database === null) {
    throw new RuntimeException('Set SQL_SERVER and SQL_DATABASE in your application configuration.');
}

$dsn = sprintf(
    'sqlsrv:Driver={ODBC Driver 18 for SQL Server};Server=%s;Database=%s;'
    . 'Encrypt=true;TrustServerCertificate=false;'
    . 'LoginTimeout=90;Authentication=ActiveDirectoryMsi;'
    . 'ConnectRetryCount=5;ConnectRetryInterval=15;'
    . 'MultiSubnetFailover=true;',
    $server,
    $database
);

$options = [
    PDO::ATTR_ERRMODE               => PDO::ERRMODE_EXCEPTION,
    PDO::ATTR_DEFAULT_FETCH_MODE    => PDO::FETCH_ASSOC,
    PDO::ATTR_EMULATE_PREPARES      => false,
    PDO::SQLSRV_ATTR_QUERY_TIMEOUT  => 30,
];

$pdo = connectWithRetry($dsn, $options);
$stmt = queryWithRetry($pdo, 'SELECT TOP (?) name FROM sys.databases ORDER BY name', [5]);
foreach ($stmt as $row) {
    echo $row['name'], PHP_EOL;
}

Cet extrait est adapté pour les groupes de basculement d’Azure SQL Database et pour Azure SQL Managed Instance.

  • Driver={ODBC Driver 18 for SQL Server} épingle le pilote ODBC 18. Si l’hôte a également ODBC 17 installé, PDO_SQLSRV peut se lier à ODBC 17. Les anciennes versions 17.x rejettent les valeurs plus Authentication récentes ; par exemple, Authentication=ActiveDirectoryMsi nécessitent ODBC 17.3.1.1 ou une version ultérieure. Voir Valeur invalide spécifiée pour l'attribut de chaîne de connexion 'Authentification'.

  • ConnectRetryCountet ConnectRetryInterval sont des mots-clés de chaîne de connexion ODBC qui permettent la résilience des connexions inactives à SQL Server : le pilote reconnecte de manière transparente une connexion inactive défaillante. Cela se distingue du niveau queryWithRetryapplication , qui tente à nouveau une instruction qui échoue avec une erreur transitoire telle qu’un blocage ou un délai d’attente de requête. Les deux sont complémentaires, donc gardez les deux. Assurez-vous LoginTimeout au ConnectRetryCount * ConnectRetryInterval moins que le chemin dle-reconnexion ait son budget complet ; l’échantillon utilise 90 secondes pour couvrir 5 × 15 secondes de tentatives plus la marge de manœuvre pour la connexion initiale sur un basculement à froid.

  • Compléter les appels au niveau error_log() de l’application par des diagnostics côté pilote. Pour PDO_SQLSRV, set-in pdo_sqlsrv.log_severityphp.ini (configurable à l’initialisation uniquement) ; pour SQLSRV, call sqlsrv_configure("LogSubsystems", ...) à l’exécution. Pour plus d’informations, voir Activité de journalisation.

    ; php.ini - enable PDO_SQLSRV driver diagnostics alongside the application-level
; error_log() calls in the sample. Use 1 (errors) in production; -1 (all) is
; useful during triage but very chatty.
[pdo_sqlsrv]
pdo_sqlsrv.log_severity = 1

  • Pour une identité gérée attribuée par l’utilisateur , passez l’ID de l’identité comme argument de $username PDO (new PDO($dsn, $identityId, null, $options)). Utilisez l'ID client de l'identité sur Azure App Service ou Azure Container Instance ; sinon, utilisez son ID d'objet. Les pilotes PHP héritent de ce comportement du pilote sous-jacent Microsoft ODBC Driver for SQL Server ; pour plus d’informations, voir Utilisation de Microsoft Entra ID avec le pilote ODBC. PDO_SQLSRV rejette UID directement dans le DSN, donc utilisez le slot constructeur. Passer null comme l’utilisateur (comme le fait l’exemple) sélectionne l’identité gérée assignée par le système de l’hôte Azure. Pour SQLSRV (procédural), passez UID le tableau d’options de connexion.

  • Définissez MultiSubnetFailover=true lorsque vous vous connectez à un écouteur de groupe de basculement, un écouteur de groupe de disponibilité ou un point d’accès d’instance de cluster de basculement. Le réglage améliore les performances de connexion pour les auditeurs de groupes de disponibilité à sous-réseau unique et multi-sous-réseau. Pour plus d’informations, voir Support for High Availability, reprise après sinistre.

  • Pour une extension de lecture ou un second lisible, ajoutez ApplicationIntent=ReadOnly au nom de la source de données (DSN).

  • Pour les clouds souverains où le certificat Subject Alternative Name (SAN) n'inclut pas l'hôte auquel vous vous connectez, ajoutez HostNameInCertificate au DSN (par exemple, *.database.usgovcloudapi.net pour Azure Government).

  • Le pilote repose sur le pilote sous-jacent Microsoft ODBC Driver for SQL Server pour l’acquisition de jetons. Les flux d’identité managée, de principal de service et de jeton d’accès passent tous par ODBC. Pour plus d’informations, consultez Utilisation de Microsoft Entra ID avec le Pilote ODBC.

  • Pour une meilleure sécurité et portabilité entre environnements, gardez les informations de connexion en dehors de votre code. Stockez les informations de connexion dans le système de configuration de votre application, et utilisez Azure Key Vault pour les valeurs sensibles et les paramètres de connexion gérés de manière centralisée.

  • La connexion SQLSRV équivalente utilise sqlsrv_connect($server, ['Database' => $database, 'Encrypt' => true, 'Authentication' => 'ActiveDirectoryMsi', /* ... */]) et retourne une ressource. Le schéma de réessai est le même : capter un false retour de sqlsrv_connect, inspecter sqlsrv_errors() pour SQLSTATE, puis reculer avant de réessayer. Pour un exemple résolu, voir l’étape 4 : Connectez-vous résiliemment à SQL avec PHP.

  • Les assistants à la réessayage lisent $e->errorInfo[1] protégés par isset(). PDOException::$errorInfo est déclaré comme ?array et passe par défaut à null, donc le contrôle défensif revient à un code de pilote de 0 et laisse le préfixe SQLSTATE 08 décider s’il faut réessayer.

Pour plus d’informations sur chaque partie de cette configuration, consultez :

Pour le catalogue d’erreurs temporaires Azure SQL, consultez Résoudre les erreurs de connexion temporaires.

Principales fonctionnalités

  • Deux API, un ensemble de pilotes : SQLSRV procédural pour le code SQL Server-first, ou PDO_SQLSRV pour le code PDO portable.
  • Support large de la plateforme : Fonctionne sous Windows, Linux et macOS avec des versions PHP prises en charge.
  • Connexions chiffrées : Connexions chiffrées TLS via Encrypt=true, avec la validation des certificats serveur contrôlée par TrustServerCertificate.
  • Authentification Microsoft Entra ID : Les connexions sans mot de passe avec identité managée, principal de service et jeton d’accès circulent via le pilote Microsoft ODBC sous-jacent pour SQL Server.
  • Always Encrypted : chiffrement côté client pour les colonnes sensibles, avec enclaves sécurisées facultatives pour les opérations sur place.
  • Résilience de la connexion : La connexion inactive intégrée réessaie avec ConnectRetryCount et ConnectRetryInterval.
  • Flux PHP : Lire et écrire de grandes valeurs binaires et de caractères sous forme de flux au lieu de les charger en mémoire.
  • Prise en charge des types de données Rich SQL Server : datetimeoffset, paramètres à valeurs de table, nvarchar, et Unicode avec PDO::SQLSRV_ENCODING_UTF8.

Get started

Article Description
Configuration système requise Versions prises en charge pour PHP, système d’exploitation et SQL Server.
Matrice de prise en charge Matrice de compatibilité détaillée pour les versions des pilotes PHP.
Téléchargez les pilotes Microsoft pour PHP pour SQL Server Liens de téléchargement et publie les artefacts.
Tutoriel d’installation pour Linux et macOS Installez le pilote et ses prérequis ODBC sur Linux et macOS.
Chargement des pilotes Activez les extensions dans php.ini.
Débuts avec le pilote SQL PHP Un guide de bout en bout qui relie les quatre étapes de départ.
Aperçu du pilote SQL PHP Qu’y a-t-il dans le package, et quand choisir SQLSRV ou PDO_SQLSRV.

Configuration et connexion

Article Description
Connexion au serveur Ouvrez une connexion vers une instance SQL Server depuis PHP.
Options de connexion Référence complète pour les mots-clés de connexion, les paramètres par défaut et comment les configurer.
Connexion à Microsoft Azure SQL Database Connectez une application PHP à Azure SQL Database.
Connectez-vous sur un port spécifié Visez un port TCP non par défaut.
Regroupement de connexions Réutilisez les connexions ODBC entre les requêtes PHP.
Désactiver les ensembles de résultats actifs multiples (MARS) Désactivez MARS pour la compatibilité.
Prise en charge de la base de données locale Connectez-vous à une instance LocalDB de SQL Server.
Support de la haute disponibilité et reprise après sinistre Écouteurs de groupe de disponibilité et basculement multi-sous-réseau.
Résilience des connexions inactives Reconnexion automatique pour les connexions d’inactivité cassées.

Authenticate

Article Description
Se connecter à l’aide de l’authentification Microsoft Entra Identité gérée, principal de service, jeton d’accès et flux de mots de passe.
Connectez-vous en utilisant l’authentification SQL Server Utilisez une connexion SQL avec un nom d’utilisateur et un mot de passe.
Connectez-vous en utilisant l’authentification Authentification Windows Utilisez l’authentification intégrée Windows sur les hôtes liés au domaine.

Secure

Article Description
Sécurité Modèle de menace et directives approfondies de défense pour les applications PHP.
Toujours chiffré avec les pilotes PHP Configurez le chiffrement côté client pour les colonnes sensibles.
Always Encrypted avec enclaves sécurisées Activez des opérations enrichies sur des colonnes chiffrées avec des enclaves sécurisées.

Récupérer et mettre à jour les données

Article Description
Guide de programmation Guide de programmation de bout en bout pour les deux pilotes.
Comparaison des fonctions d’exécution Choisissez la fonction d’exécution adaptée à votre charge de travail.
Exécution directe et préparée des instructions (PDO_SQLSRV) Quand utiliser l’exécution directe versus les déclarations préparées.
Récupération des données Récupérez les lignes, colonnes et valeurs de streaming.
Mise à jour des données Insérer, mettre à jour et supprimer des lignes.
Effectuer des requêtes paramétrées Liez des paramètres pour protéger contre l’injection SQL.
Envoyer des données sous forme de flux Diffusez de grandes valeurs binaires et de caractères vers SQL Server.
Réalisation de transactions Regrouper les relevés en transactions atomiques.
Utilisation de paramètres à valeurs de table Passer un TABLE paramètre à une procédure stockée.
Spécifiez un type de curseur et sélectionnez des lignes Choisissez les curseurs en avant, statique, dynamique ou de jeu de touches.

Types de données

Article Description
Conversion des types de données Comment le pilote associe les types PHP aux types SQL Server.
Types de données par défaut du SQL Server Type de SQL Server par défaut pour chaque valeur PHP.
Types de données PHP par défaut Type de PHP par défaut pour chaque type de colonne SQL Server.
Spécifier les types de données SQL Server (SQLSRV) Suppliez le type SQL Server lors de la liaison des paramètres.
Spécifier les types de données PHP Supprime le type PHP lors de la récupération.
Envoyer et récupérer les données UTF-8 À utiliser PDO::SQLSRV_ENCODING_UTF8 pour les allers-retours Unicode.
Envoyer et récupérer des données ASCII sur Linux et macOS Gérer les allers-retours ASCII sur des hôtes non-Windows.
Formater décimales et argent (SQLSRV) Formatez les colonnes décimales et argent avec le pilote SQLSRV.
Format décimales et monnaie (PDO_SQLSRV) Formatez les colonnes décimales et argent avec le pilote PDO_SQLSRV.
Paramètres de zone non liés au système Séparateurs décimaux localisés et autres considérations locales.

Erreurs et diagnostics

Article Description
Erreurs de gestion et avertissements Gestion des erreurs et des avertissements avec les deux pilotes.
Configurer la gestion des erreurs et des avertissements (SQLSRV) Ajustez la façon dont le pilote SQLSRV signale les erreurs et les avertissements.
Gérer les erreurs et avertissements (SQLSRV) Inspecter les erreurs retournées par les fonctions SQLSRV.
Activité forestière Activez la journalisation des pilotes pour la capture de diagnostic.

Déployer et exploiter

Article Description
Réglage des performances Gestion de connexion, batching, instructions préparées, curseurs, mémoire et surveillance côté serveur.
Résolution des problèmes Diagnostiquer les problèmes courants d’installation, de connexion, de requête, de type de données, de transaction et de conteneurs.

Reference

Article Description
Référence API de pilote SQLSRV Toutes les sqlsrv_* fonctions, paramètres et valeurs de retour.
PDO_SQLSRV référence du pilote Les méthodes PDO et PDOStatement prises en charge par le pilote PDO_SQLSRV.
Constantes Constantes exposées par les pilotes, y compris les constantes de type et d’encodage.
Article Description
Notes de publication Historique par version avec nouvelles fonctionnalités, corrections de bugs, changements de support de plateforme et liens de téléchargement.
À propos des exemples de code dans la documentation Conventions utilisées par les exemples de code de cette section.
Exemples de code pour le pilote SQL PHP Exemples d’applications de bout en bout pour SQLSRV et PDO_SQLSRV.
Ressources de support technique Communauté et canaux de soutien.

Contenu connexe

  • Last updated on