Pilotes Microsoft SQL Server pour PHP

Télécharger le pilote PHP

Les pilotes Microsoft pour PHP pour SQL Server sont des extensions PHP que vous pouvez utiliser pour lire et écrire des données dans le Microsoft SQL Moteur de base de données à partir de scripts PHP. Les deux extensions utilisent le même pilote Microsoft ODBC pour SQL Server, mais elles proposent des API PHP différentes et des options spécifiques à chaque pilote :

• 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). Vous pouvez garder les appels PDO dans le code existant de la base de données, mais revoir ses requêtes et les paramètres spécifiques au pilote avant de changer de base de données.

Les deux pilotes se connectent à Azure SQL Database, SQL Database dans Microsoft Fabric, Azure SQL Managed Instance, ainsi qu’à toutes les versions et éditions prises en charge de SQL Server, y compris les éditions Express. Les deux drivers acceptent les flux PHP comme paramètres d’entrée. SQLSRV prend en charge la récupération de grandes valeurs binaires et de caractères sous forme de flux. Ne supposez pas que PDO_SQLSRV a le même comportement de streaming de sortie.

Choisir votre point de départ

• Pour vérifier votre installation et lancer une requête paramétrée en utilisant SQLSRV ou PDO_SQLSRV, commencez par Quickstart : Connect et requête avec les pilotes Microsoft pour PHP.
• Pour installer le pilote sur Linux ou macOS, commencez par le tutoriel d’installation pour Linux et macOS et téléchargez les pilotes Microsoft pour PHP pour SQL Server.
• Pour se connecter à Azure SQL avec une authentification sans mot de passe, commencez par Connect en utilisant les options d’authentification Microsoft Entra et de Connexion.
• Pour rendre une application existante résiliente aux pannes transitoires, allez dans la résilience des connexions inactives.
• Pour choisir entre SQLSRV et PDO_SQLSRV, rendez-vous dans Aperçu des Microsoft Pilotes pour PHP pour SQL Server et Comparaison des fonctions d’exécution.
• Pour diagnostiquer un problème d’installation, de connexion ou de requête, allez dans Dépannage, Gestion des erreurs et avertissements, et Activité de journalisation.
• Pour rendre une application existante plus rapide, allez dans Performance Tuning.

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

Cet exemple PDO_SQLSRV lit le serveur et la base de données à partir des variables d’environnement et se connecte avec une identité gérée. Il construit un nom de source de données (DSN) et active la sécurité de la couche de transport (TLS) avec validation des certificats. Lisez ces valeurs depuis la configuration d’application fiable, pas les paramètres de requête web. Exécutez le programme sur un hôte avec un point de terminaison à identité gérée après avoir accordé à l’identité l’accès à la base de données.

Les fonctions d’assistance peuvent effectuer jusqu’à trois tentatives de connexion ou d’exécution de la requête en lecture seule lorsqu’une erreur listée survient. Ils attendent plus longtemps entre les tentatives, un schéma de retentative appelé reculement exponentiel. Si une erreur de requête nécessite une nouvelle connexion, l’assistant de requête lance l’exception pour que le code appelant la gère.

Utilisez une version PHP prise en charge, l’extension PDO_SQLSRV, et Microsoft pilote ODBC 18 pour SQL Server. Pour les valeurs d’authentification prises en charge, voir Se connecter à l’aide de l’authentification Microsoft Entra. Ne réutilisez pas l’assistant de requête pour les écritures ou les transactions multi-instructions sans concevoir une politique de réessayage spécifique à l’application : une erreur ne vous indique pas toujours si une écriture a été commitée.

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

// This read helper retries only the listed errors on the same connection.
// Other errors propagate; the caller must decide whether to reconnect.
const RETRYABLE_READ_ERROR_CODES = [1205, 1222, 40501, 10928, 10929];

/**
 * 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);
            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');
}

/**
 * Retry the standalone read-only query for errors that allow connection reuse.
 */
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, RETRYABLE_READ_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.');
}
$databaseValue = '{' . str_replace('}', '}}', $database) . '}';

$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,
    $databaseValue
);

$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 name FROM sys.databases WHERE database_id > ? ORDER BY name', [1]);
foreach ($stmt as $row) {
    echo $row['name'], PHP_EOL;
}

Utilisez ces paramètres pour les groupes de basculement Azure SQL Database et Azure SQL Managed Instance.

• Driver={ODBC Driver 18 for SQL Server} sélectionne explicitement le pilote ODBC 18 plutôt que de s’appuyer sur la découverte du pilote. Installez-le avant de lancer l’exemple.

• Réglez SQL_DATABASE sur le nom exact de la base de données. Le programme double les accolades fermantes et entoure le nom entre accolades avant de le placer dans le DSN. Échapper empêche les caractères spéciaux du nom de modifier la façon dont le pilote lit les paramètres de connexion.

• ConnectRetryCount et ConnectRetryInterval contrôlent la résilience des connexions ODBC au repos. Le délai d’expiration de la requête limite la récupération pendant l’exécution. Avec le délai d’attente de 30 secondes de requête de l’échantillon, ODBC pourrait s’arrêter avant d’avoir épuisé les cinq tentatives de reconnexion. LoginTimeout=90 Contrôle l’établissement de la connexion, et non ce budget de reprise. L’assistant au niveau de l’application réessaie certaines erreurs serveur ; il ne réessaie pas un délai d’expiration de requête ni ne rejoue les résultats partiellement récupérés.

• Activez la connexion des conducteurs en même temps que les appels du error_log() programme. Pour PDO_SQLSRV, réglez-vous pdo_sqlsrv.log_severity en php.ini ou avec ini_set() pendant l’exécution. Pour SQLSRV, configurez LogSeverity et LogSubsystems avec sqlsrv_configure(). 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, transmettez l’identifiant de l’identité comme argument $username de 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. Utilisez l’argument du nom d’utilisateur du constructeur PDO plutôt que d’intégrer l’identité dans le DSN. Transmettre null en tant qu’utilisateur (comme dans l’exemple) sélectionne l’identité gérée attribuée par le système de l’hôte Azure. Pour SQLSRV (procédural), passez UID dans le tableau des options de connexion.

• Définissez MultiSubnetFailover=true quand vous vous connectez à un écouteur de groupe de basculement, à un écouteur de groupe de disponibilité ou à un point de terminaison d’instance de cluster de basculement. Le fait de définir ce paramètre améliore les performances de connexion pour les listeners de groupes de disponibilité à sous-réseau unique et à sous-réseaux multiples. Pour plus d’informations, voir Support for High Availability, reprise après sinistre.

• Pour une extension en lecture ou un secondaire lisible, ajoutez ApplicationIntent=ReadOnly au DSN.

• Utilisez le point de terminaison fourni par votre service SQL, y compris son domaine spécifique au cloud. Enquêtez sur les incompatibilités entre les noms de certificat plutôt que de désactiver la validation des certificats. Utilisez HostNameInCertificate uniquement lorsque vous connaissez le nom attendu du certificat pour ce terminaison.

• ODBC acquiert des jetons pour l’identité gérée et l’authentification du principal de service. Avec AccessToken, votre application acquiert le jeton et le transmet au pilote ; ODBC ne l’acquiert pas pour vous. Pour plus d’informations, consultez Utilisation de Microsoft Entra ID avec le Pilote ODBC.

• Gardez les informations de connexion en dehors de votre code. Stockez-le dans le système de configuration de votre application, et utilisez Azure Key Vault pour les secrets.

• Avec SQLSRV, définissez les options de connexion dans le tableau passé à sqlsrv_connect(). Vérifiez s’il y a un false retour et inspectez sqlsrv_errors() avant de décider s’il faut réessayer. Définissez séparément les délais d’attente des instructions avec QueryTimeout. La résilience de la connexion inactive démontre une reconnexion ODBC, et non une boucle de réessayage au niveau de l’application.

• Les fonctions utilitaires de nouvelle tentative lisent $e->errorInfo[1], qui est protégé 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 :

• Options de connexion
• Se connecter à l’aide de l’authentification Microsoft Entra
• Résilience des connexions inactives
• Connexion à Microsoft Azure SQL Database
• Support de la haute disponibilité et reprise après sinistre

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

Principales fonctionnalités

• Deux API PHP : SQLSRV fournit des fonctions procédurales. PDO_SQLSRV met en œuvre le PDO. Installez soit une extension, soit les deux.
• 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 : Identité managée, principal de service et jetons d’accès acquis externement via le pilote sous-jacent Microsoft ODBC pour SQL Server. L’identité gérée est sans mot de passe ; ActiveDirectoryServicePrincipal utilise un secret client.
• Always Encrypted : Chiffrez les colonnes sensibles côté client, avec des enclaves sécurisées pour les opérations prises en charge sur des données chiffrées.
• Résilience de la connexion : La connexion inactive intégrée réessaie avec ConnectRetryCount et ConnectRetryInterval.
• streams PHP : Envoyez de grandes valeurs binaires et de caractères depuis les paramètres de flux avec l’une ou l’autre API. Utilisez SQLSRV pour la récupération en streaming.
• Prise en charge complète des types de données SQL Server : datetimeoffset, paramètres table, nvarchar et Unicode avec PDO::SQLSRV_ENCODING_UTF8.

Get started

Configuration et connexion

Authenticate

Secure

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

Types de données

Erreurs et diagnostics

Déployer et exploiter

Contenu de référence

Tâches associées

Demander une fonctionnalité

Pour demander une fonctionnalité, ouvrez un problème dans le dépôt Microsoft Drivers for PHP for SQL Server GitHub.

Contenu connexe

• Pilotes Microsoft pour PHP pour SQL Server sur GitHub
• Pilote ODBC Microsoft pour SQL Server
• Pilotes et frameworks SQL de Microsoft