Connexion au serveur

Télécharger le pilote PHP

Utilisez ce guide pour ouvrir une connexion, vérifier les valeurs reçues par PHP, puis relâcher la connexion lorsque le travail est terminé. Les programmes utilisent l’authentification SQL Server pour une base de données de test SQL Server locale ou distante. Pour les connexions Azure et Fabric sans mot de passe, utilisez Se connecter à Azure SQL et à Fabric SQL.

SQLSRV accepte un nom de serveur et un tableau associatif d’options de connexion. PDO_SQLSRV implémente les objets de données PHP (PDO) et accepte une chaîne de noms de source de données (DSN), des arguments d’identifiants séparés et un tableau d’attributs PDO. Les deux utilisent le pilote Microsoft ODBC pour SQL Server. Une connexion fonctionnant avec une API ne rend pas les noms d’options ou types PHP de l’autre API interchangeables.

Avant de vous connecter

1. Installez un runtime PHP supporté et un pilote Microsoft ODBC, puis chargez l’extension PHP que vous comptez utiliser.
2. Vérifiez le processus PHP qui fait tourner votre application. Exécutez php --ini pour trouver la configuration en ligne de commande et php -m pour lister ses extensions chargées. SQLSRV nécessite sqlsrv. PDO_SQLSRV nécessite PDO et pdo_sqlsrv. Un serveur web peut utiliser un php.ini, un runtime et un compte différents de ceux de votre terminal.
3. Obtenez l’adresse du serveur, le nom de la base de données et une identité avec la permission de se connecter. Une connexion à la base de données n’accorde pas automatiquement des droits d’accès à toutes les tables.
4. Configurez l’accès réseau et un certificat serveur de confiance. Ces programmes demandent explicitement le chiffrement et la validation des certificats. Connectez-vous en utilisant le nom d’hôte figurant sur le certificat plutôt que de remplacer par une adresse IP que le certificat ne couvre pas.

Définissez ces variables dans l’environnement du processus PHP, en utilisant votre shell, votre outil de développement ou votre configuration d’hébergement. Ne validez pas un fichier de mot de passe et n’imprimez pas l’environnement.

Lisez les paramètres du serveur et de la base de données depuis la configuration d’application fiable, et non des paramètres de requête Web. L’exemple du PDO place ces réglages dans un DSN. Gardez les mots-clés de connexion sous contrôle de l’application.

Stockez le nom réel de la base de données, le nom d’utilisateur et le mot de passe dans les variables d’environnement, sans ajouter ou doubler vous-même les accolades. Les deux extensions PHP nécessitent un échappement de type ODBC même pour les options de tableau SQLSRV et les arguments du constructeur PDO : doubler chaque accolade fermante et englober la valeur entre accolades. Chaque programme fait cela une fois avant de transmettre ces valeurs au pilote. Les accolades extérieures conservent les accolades littérales au début et à la fin d’une valeur, et empêchent les points-virgules à l’intérieur du nom de la base de données de séparer les paramètres DSN du PDO. Cette séquence d’échappement est distincte de la liaison de paramètres Transact-SQL (T-SQL).

Ouvrir, interroger et fermer avec SQLSRV

Enregistrez ce programme sous le nom de connect-sqlsrv.php, et exécutez php connect-sqlsrv.php. Il exécute une requête T-SQL sans créer de tables ni modifier les données. CharacterSet sélectionne UTF-8 pour les données de caractères ; il ne modifie pas les types de colonnes ni la collation de la base de données.

<?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 {
    $sql = "SELECT CAST(42 AS int) AS Value, N'caf' + NCHAR(233) AS Label, "
        . "CAST(NULL AS int) AS Missing";
    $stmt = sqlsrv_query($conn, $sql, [], ['QueryTimeout' => 30]);
    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 ($row !== ['Value' => 42, 'Label' => "caf\u{00e9}", 'Missing' => null]) {
        throw new RuntimeException('Unexpected SQLSRV values or PHP types.');
    }
    echo json_encode($row, JSON_THROW_ON_ERROR), PHP_EOL;
} finally {
    if (is_resource($stmt)) {
        sqlsrv_free_stmt($stmt);
    }
    sqlsrv_close($conn);
}

Sortie attendue :

{"Value":42,"Label":"caf\u00e9","Missing":null}

La connexion et l’instruction sont des ressources PHP, des identifiants que vous passez à des fonctions sqlsrv_*. Vérifiez la présence de false avant d’utiliser l’une ou l’autre poignée. Récupérez sqlsrv_errors() immédiatement après une défaillance car un appel SQLSRV ultérieur peut remplacer la collection d’erreurs.

SQLSRV_FETCH_ASSOC renvoie un tableau associatif avec les noms des colonnes comme clés. SQLSRV_FETCH_NUMERIC renvoie des clés numériques à base zéro ; la valeur par défaut SQLSRV_FETCH_BOTH inclut les deux formes. Pour sqlsrv_fetch_array(), null signifie qu’il n’y a plus de lignes et false signifie une erreur. Un SQL NULL à l’intérieur d’une ligne correspond à du PHP null; cela ne signifie pas que la ligne est manquante. À utiliser === pour distinguer ces valeurs.

Ouvrir, interroger et fermer avec PDO_SQLSRV

Sauvegardez ce programme séparé sous le nom connect-pdo.php, et exécutez php connect-pdo.php avec le même environnement. sqlsrv: sélectionne PDO_SQLSRV, pas le pilote générique de PDO_ODBC de 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]) . '}';
}
$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::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
        PDO::SQLSRV_ATTR_ENCODING => PDO::SQLSRV_ENCODING_UTF8,
    ]
);

$stmt = null;
try {
    $sql = "SELECT CAST(42 AS int) AS Value, N'caf' + NCHAR(233) AS Label, "
        . "CAST(NULL AS int) AS Missing";
    $stmt = $pdo->prepare($sql, [PDO::SQLSRV_ATTR_QUERY_TIMEOUT => 30]);
    $stmt->execute();
    $row = $stmt->fetch();
    if ($row !== ['Value' => '42', 'Label' => "caf\u{00e9}", 'Missing' => null]) {
        throw new RuntimeException('Unexpected PDO_SQLSRV values or PHP types.');
    }
    echo json_encode($row, JSON_THROW_ON_ERROR), PHP_EOL;
} finally {
    $stmt = null;
    $pdo = null;
}

Sortie attendue :

{"Value":"42","Label":"caf\u00e9","Missing":null}

PDO_SQLSRV renvoie cette colonne int comme une chaîne PHP par défaut. Pour demander des types numériques PHP pour les colonnes numériques prises en charge, on règle PDO::SQLSRV_ATTR_FETCHES_NUMERIC_TYPE à true. N’utilisez pas une conversion de type PHP à la va-vite pour les valeurs décimales ; une conversion en virgule flottante peut perdre en précision.

Les attributs PDO sont des réglages sur l’objet de connexion ou d’instruction. PDO::ATTR_ERRMODE avec PDO::ERRMODE_EXCEPTION fait en sorte que les échecs des opérations de base de données génèrent PDOException. La construction de la connexion lève une exception en cas d’échec, quel que soit le réglage. PDO::FETCH_ASSOC donne des clés nommées, PDO::FETCH_NUM donne des clés numériques à base zéro, et PDO::FETCH_BOTH donne les deux. fetch() renvoie false à la fin du résultat ; les valeurs SQL NULL dans une ligne restent PHP null.

Ces programmes en ligne de commande permettent aux échecs d’arrêter l’exécution. Dans une application web, interceptez les exceptions dans le code qui gère la requête. Enregistrez les détails de diagnostic dans des journaux protégés et retournez une réponse d’erreur générique. N’envoyez sqlsrv_errors()pas de traces d’exception, de chaînes de connexion ou de jetons à un navigateur.

Choisir un mode d'authentification

Pour l’authentification SQL, SQLSRV prend UID et PWD dans son tableau d’options de connexion. PDO_SQLSRV prend le nom d’utilisateur et le mot de passe comme deuxième et troisième arguments de new PDO(), et non comme mots-clés DSN. Pour un jeton d’accès, SQLSRV accepte AccessToken dans le tableau d’options, tandis que PDO_SQLSRV le prend dans le DSN.

Si vous omettez le nom d’utilisateur, le mot de passe, Authentication, et AccessToken, les deux pilotes demandent une authentification intégrée à ODBC en utilisant Trusted_Connection=Yes. Sous Linux et macOS, cette requête nécessite un ticket Kerberos valide et une configuration d’authentification intégrée ODBC. Il ne donne pas à un compte local arbitraire un accès à un serveur distant.

Configurez la connexion et ses instructions SQL

Les paramètres de connexion s’appliquent à la session que vous ouvrez. Les paramètres de l’instruction SQL s’appliquent à une requête particulière. Définissez explicitement les délais et les types de résultats lorsque votre application a besoin de valeurs autres que les valeurs par défaut.

Pour la liste complète des mots-clés, des valeurs autorisées et des valeurs par défaut, consultez les options de connexion. Ne placez pas CharacterSet, QueryTimeout ni PDO:: des noms de constantes dans un DSN PDO.

Gérer la durée de vie de la connexion

Ouvrez une connexion lorsqu’une requête ou une tâche nécessite une opération sur la base de données. Réutilise-le tout au long de cette requête ou de cette tâche, puis libérez-le une fois terminé. Ne connectez pas et ne déconnectez pas à chaque ligne. Dans un worker de longue durée, libérez les instructions et terminez chaque transaction avant d’accepter la tâche suivante.

SQLSRV ferme les instructions SQL associées lorsque vous fermez sa connexion. Libérer explicitement les instructions plus tôt libère des ressources sans mettre fin à la connexion. Avec PDO, assigner $pdo = null ne supprime que la référence de cette variable. Un PDOStatement ou une autre variable peut toujours conserver la connexion. Libérez aussi ces références. closeCursor() libère les résultats en attente afin que l’instruction puisse être réutilisée ; ce n’est pas une méthode de fermeture de connexion.

Les deux API sont en mode autocommit : une instruction réussie est validée sans validation distincte de l’application, sauf si vous commencez une transaction. Pour un groupe d’écritures qui doivent réussir ou échouer ensemble, utilisez sqlsrv_begin_transaction() ou $pdo->beginTransaction(), puis validez ou annulez explicitement. Fermer une connexion avec une transaction en attente tente une annulation de transaction, pas une validation. Ne comptez pas sur le nettoyage à l’arrêt pour mettre en œuvre votre politique de transaction. Pour des exemples complets, voir Effectuer des transactions.

Libérer un handle de connexion PHP ne ferme pas nécessairement sa connexion réseau physique. Le regroupement de connexions ODBC peut le conserver pour le réutiliser. Le pooling n’est pas une raison de conserver indéfiniment les ressources PHP, et PDO_SQLSRV ne prend pas en charge PDO::ATTR_PERSISTENT => true. Pour la configuration de pooling spécifique à la plateforme, voir Connection pooling.

Appliquez le guide à votre cible SQL

Les patrons handle, fetch et cleanup s’appliquent aux deux extensions sur des cibles SQL prises en charge. Les points de terminaison de connexion, l’authentification, l’accès réseau et les capacités SQL varient.

Pour la configuration spécifique au service, voir connexions Azure et Fabric.

Résoudre les problèmes de connexion

Commencez par l’étape qui a échoué. Une vérification réussie du protocole de contrôle de transmission (TCP) ne prouve pas que l’authentification ou la validation du certificat ont réussi.

Autres articles sur la connexion

• Connectez-vous sur un port spécifié
• Options de connexion
• Regroupement de connexions
• Désactiver les ensembles de résultats actifs multiples (MARS)
• Prise en charge de la base de données locale
• Support de la haute disponibilité et de la reprise après sinistre
• Connexion à Microsoft Azure SQL Database
• Résilience des connexions inactives

Contenu connexe

• Guide de programmation pour les pilotes Microsoft pour PHP pour SQL Server
• Exemple d’application (pilote SQLSRV)