Déclarer les types et longueurs de chaînes d’entrée (PDO_SQLSRV)

Utilisez des déclarations explicites pour envoyer une chaîne d’entrée en tant que varchar ou nvarchar avec une longueur SQL spécifiée. Sinon, optez pour un dimensionnement adaptatif pour commencer par une longueur choisie et faire grandir la déclaration lorsque vous envoyez des valeurs plus longues.

Ces options nécessitent la version 5.14.0 ou ultérieure et s’appliquent uniquement à PDO_SQLSRV, le pilote PHP Data Objects (PDO). Pour SQLSRV, continuez à spécifier les types SQL dans le tableau de paramètres décrit dans Spécifier les types de données SQL Server. Aucune des deux approches ne modifie la définition de la colonne de destination.

Choisissez une méthode de déclaration

Method Configuration Behavior
Métadonnées de déclarations explicites Appelez PDOStatement::setAttribute(PDO::SQLSRV_ATTR_PARAM_METADATA, $metadata) après prepare. S’applique à bindParam, bindValue, et execute($params).
Métadonnées explicites de liaison Passez un tableau de déclaration comme cinquième argument de bindParam. Remplace l’intégralité de l’entrée de métadonnées de l’instruction pour cette liaison, y compris son encodage optionnel.
Dimensionnement adaptatif Réglez PDO::SQLSRV_ATTR_DEFAULT_STR_LENGTH sur la connexion avant de créer l’instruction SQL. S’applique aux chaînes d’entrée éligibles sans déclaration explicite.

Sans métadonnées explicites ni dimensionnement adaptatif, le comportement de dimensionnement des paramètres existant reste inchangé. Vous n’avez pas besoin de ces options pour des requêtes paramétrées ordinaires.

Déclarer une chaîne d’entrée

Chaque déclaration est un tableau avec des clés de constantes entières et des valeurs entières.

Key Value
PDO::SQLSRV_PARAM_DECLARED_STR_TYPE PDO::SQLSRV_PARAM_DECLARED_STR_TYPE_VARCHAR ou PDO::SQLSRV_PARAM_DECLARED_STR_TYPE_NVARCHAR.
PDO::SQLSRV_PARAM_DECLARED_STR_LENGTH Pour varchar, de 1 à 8 000 octets. Pour nvarchar, de 1 à 4 000 unités de code en format de transformation Unicode 16 bits (UTF-16). Utilisez PDO::SQLSRV_PARAM_DECLARED_STR_LENGTH_MAX pour varchar(max) ou nvarchar(max).
PDO::SQLSRV_ATTR_ENCODING (optionnel) L’encodage de caractères de la chaîne d’entrée PHP. Pour une entrée en format de transformation Unicode 8 bits (UTF-8), utilisez PDO::SQLSRV_ENCODING_UTF8 ou PDO::SQLSRV_ENCODING_UTF8_VARCHAR. Le type déclaré, et non l’encodage, définit le type SQL. Vous pouvez également utiliser PDO::SQLSRV_ENCODING_SYSTEM pour l’entrée avec l’encodage du système. L’encodage binaire n’est pas pris en charge.

Vous devez inclure les deux clés de déclaration. Les chaînes numériques, valeurs booléennes, longueurs de zéro et clés non reconnues sont invalides. Un caractère Unicode supplémentaire, tel que "\u{1F600}", occupe deux unités de code UTF-16, même si PHP stocke sa représentation UTF-8 sur quatre octets.

L’encodage décrit les octets source. Le type déclaré décrit le paramètre SQL envoyé au serveur. Par exemple, vous pouvez envoyer une entrée UTF-8 en varchar sans changer les octets source vers l’encodage système. La conversion vers varchar dépend toujours de la collation SQL et de son répertoire de caractères. Une longueur SQL explicite n’alloue pas de tampon PHP.

Lorsque le pilote déclare un paramètre lié pour une instruction préparée, il ignore les indicateurs PDO::PARAM_STR_NATL et PDO::PARAM_STR_CHAR. Utilisez une déclaration pour choisir varchar ou nvarchar.

Pour les métadonnées de l’instruction, utilisez une mappe des identifiants de paramètres vers les tableaux de déclaration :

  • Utilisez des positions indexées à partir de 1 pour les espaces réservés « ? », tels que [1 => $declaration]. Les positions doivent être des entiers de 1 à 2 100 et doivent identifier les paramètres liés lors de l’exécution de l’instruction.
  • Utilisez un nom d’espace réservé unique, avec ou sans son deux-points, tel que ['name' => $declaration] ou [':name' => $declaration]. Un nom d’espace réservé répété n’identifie pas une position unique. Ne spécifiez pas la même position deux fois via des noms différents ou des clés numériques.
  • Définissez les métadonnées après prepare, et non dans son tableau d’options. Chaque setter réussi remplace l’intégralité de la map et réinitialise l’historique de taille adaptative. Un remplacement invalide conserve la carte précédente. Passez [] pour effacer la map ; null est invalide.
  • Appelez getAttribute(PDO::SQLSRV_ATTR_PARAM_METADATA) sur l’instruction pour récupérer la carte normalisée à des positions basées sur 1. Il renvoie les métadonnées de l’instruction, et non les overrides par liaison ni l’historique adaptatif des tailles.

Un tableau passé à execute fournit des valeurs, et non des déclarations. Ses valeurs positionnelles utilisent le tableau PHP habituel basé sur zéro, tel que ['text']; sa carte de métadonnées utilise [1 => $declaration]toujours .

Pour bindParam, conservez le quatrième argument à 0 pour une déclaration en entrée. Un quatrième argument positif sélectionne le comportement du tampon de sortie ; ce n’est pas la nouvelle longueur de déclaration SQL. Les options d’encodage sous forme d’entier dans le cinquième argument continuent de fonctionner. Un tableau de déclaration remplace l’intégralité de l’entrée d’instruction pour cette association, tandis qu’une option de codage entier ne remplace que le codage. La redéfinition sans le tableau de déclaration supprime le remplacement de cette liaison, mais conserve les métadonnées de l’instruction.

Exemple : déclarations explicites

Les exemples de cet article partent du principe qu’une connexion PDO est ouverte dans $conn et utilise PDO::ERRMODE_EXCEPTION. Pour en ouvrir un, voir Connexion au serveur. Ils utilisent le tableau suivant :

CREATE TABLE dbo.Customers
(
    CustomerID int IDENTITY PRIMARY KEY,
    Name nvarchar(100) NOT NULL,
    Code varchar(10) NOT NULL
);

Sans déclaration, le pilote envoie chaque valeur de chaîne dans les exemples suivants en tant que nvarchar(4000). Chaque exemple déclare plutôt le type et la longueur de la colonne correspondante.

L’exemple suivant utilise des paramètres nommés, des métadonnées d’instruction et un tableau transmis à execute. Le serveur reçoit @P1 nvarchar(100) et @P2 varchar(10).

$stmt = $conn->prepare('INSERT INTO dbo.Customers (Name, Code) VALUES (:name, :code)');
$stmt->setAttribute(PDO::SQLSRV_ATTR_PARAM_METADATA, [
    'name' => [
        PDO::SQLSRV_PARAM_DECLARED_STR_TYPE => PDO::SQLSRV_PARAM_DECLARED_STR_TYPE_NVARCHAR,
        PDO::SQLSRV_PARAM_DECLARED_STR_LENGTH => 100,
    ],
    'code' => [
        PDO::SQLSRV_PARAM_DECLARED_STR_TYPE => PDO::SQLSRV_PARAM_DECLARED_STR_TYPE_VARCHAR,
        PDO::SQLSRV_PARAM_DECLARED_STR_LENGTH => 10,
    ],
]);
$stmt->execute(['name' => 'Zoë Martín', 'code' => 'C-1001']);

L’exemple suivant utilise un espace réservé au point d’interrogation et bindValue pour trouver un client par code. La clé de métadonnées 1 identifie le premier espace réservé. La déclaration de varchar(10) correspond à la colonne Code. Lorsqu’une colonne varchar est comparée à un paramètre nvarchar, SQL Server convertit la valeur de la colonne, ce qui peut empêcher une recherche d’index.

$stmt = $conn->prepare('SELECT CustomerID, Name FROM dbo.Customers WHERE Code = ?');
$stmt->setAttribute(PDO::SQLSRV_ATTR_PARAM_METADATA, [
    1 => [
        PDO::SQLSRV_PARAM_DECLARED_STR_TYPE => PDO::SQLSRV_PARAM_DECLARED_STR_TYPE_VARCHAR,
        PDO::SQLSRV_PARAM_DECLARED_STR_LENGTH => 10,
    ],
]);
$stmt->bindValue(1, 'C-1001', PDO::PARAM_STR);
$stmt->execute();
$customer = $stmt->fetch(PDO::FETCH_ASSOC);
echo $customer['Name'], "\n";

L’exemple suivant passe un tableau de déclaration comme cinquième argument de bindParam, avec 0 comme quatrième argument. La longueur déclarée reste fixe à travers les exécutions. Une valeur plus longue que 10 caractères échoue avec SQLSTATE 22001 et n’insère aucune ligne.

$stmt = $conn->prepare('INSERT INTO dbo.Customers (Name, Code) VALUES (?, ?)');
$name = 'Kim Abercrombie';
$code = 'C-1002';
$stmt->bindParam(1, $name, PDO::PARAM_STR, 0, [
    PDO::SQLSRV_PARAM_DECLARED_STR_TYPE => PDO::SQLSRV_PARAM_DECLARED_STR_TYPE_NVARCHAR,
    PDO::SQLSRV_PARAM_DECLARED_STR_LENGTH => 100,
]);
$stmt->bindParam(2, $code, PDO::PARAM_STR, 0, [
    PDO::SQLSRV_PARAM_DECLARED_STR_TYPE => PDO::SQLSRV_PARAM_DECLARED_STR_TYPE_VARCHAR,
    PDO::SQLSRV_PARAM_DECLARED_STR_LENGTH => 10,
]);
$stmt->execute();

$name = 'Thomas Hardy';
$code = 'C-100000003';
try {
    $stmt->execute();
} catch (PDOException $error) {
    if ($error->getCode() !== '22001') {
        throw $error;
    }
    echo "The code is longer than 10 characters.\n";
}

Optez pour un dimensionnement adaptatif

Définissez PDO::SQLSRV_ATTR_DEFAULT_STR_LENGTH dans le tableau d’options du constructeur de connexion ou avec PDO::setAttribute. La valeur doit être un entier de 0 à 8 000. La valeur par défaut, 0, désactive le dimensionnement adaptatif.

Chaque nouvelle instruction copie le paramètre de connexion. Le changement ultérieur affecte les nouvelles instructions SQL, pas celles existantes. Cet attribut n’est ni une déclaration ni prepare une option.

Pour chaque position de paramètre éligible, le pilote commence par le minimum configuré et fait grandir la déclaration pour s’adapter à des valeurs plus longues. Il conserve la taille la plus grande utilisée à cette position lorsque vous envoyez plus tard des valeurs plus courtes, vides ou nulles. Pour l’entrée UTF-8 avec l’encodage par défaut, il utilise nvarchar et mesure la croissance en unités de code UTF-16. Pour les entrées encodées par le système, elle utilise varchar et réserve trois octets supplémentaires pour chaque octet non-ASCII, car la conversion vers un collage UTF-8 peut allonger la valeur. Il promeut les déclarations de plus de 4 000 unités nvarchar ou de 8 000 octets varchar en max, y compris lorsque le plancher initial dépasse la limite limite du type.

Les déclarations explicites ont la priorité sur le dimensionnement adaptatif. Les paramètres liés en tant qu’entiers, comme données binaires, comme flux ou comme paramètres de sortie ou d’entrée-sortie conservent leur comportement existant. Modifier le type SQL inféré en modifiant l’encodage commence un nouvel historique de taille pour ce paramètre.

Exemple : dimensionnement adaptatif

L’exemple suivant utilise la table de l’exemple de déclaration explicite. Il fixe une valeur minimale de 20 pour la connexion avant de préparer l’instruction. La première exécution envoie @P1 nvarchar(20) et @P2 nvarchar(20). Le second nom compte 30 caractères, donc le pilote étend @P1 en nvarchar(30). Les deux paramètres sont nvarchar car l’entrée est UTF-8, même si la colonne Code est varchar. Pour correspondre à une colonne varchar , utilisez une déclaration explicite.

$conn->setAttribute(PDO::SQLSRV_ATTR_DEFAULT_STR_LENGTH, 20);
$stmt = $conn->prepare('INSERT INTO dbo.Customers (Name, Code) VALUES (?, ?)');
$stmt->execute(['Ana Trujillo', 'C-1003']);
$stmt->execute(['Hanna Moos-Fernández Bergström', 'C-1004']);

Le réglage de taille contrôle les déclarations de paramètres, pas la capacité de la colonne de destination.

Limitations et erreurs

  • Les déclarations explicites ne supportent que les chaînes d’entrée et les valeurs nulles liées à PDO::PARAM_STR ou PDO::PARAM_NULL. Ils rejettent l’encodage binaire, les flux, d’autres types de paramètres et les paramètres de sortie et d’entrée/sortie.
  • Dans la version 5.14.0, le varchar explicite borné n’accepte que les entrées ASCII (American Standard Code for Information Interchange). Pour les entrées non ASCII, utilisez nvarchar, varchar(max) avec une collation appropriée, ou un dimensionnement adaptatif. Le dimensionnement adaptatif ne supprime pas les contraintes de conversion d’interclassement.
  • Les déclarations explicites et les tailles adaptatives ne sont pas prises en charge avec Always Encrypted ou les préparations ém ulées. Un paramètre adaptatif non nul fait échouer la création d’instructions pour l’un ou l’autre chemin. Désactivez-le avant de créer ces requêtes. L’exécution directe à travers PDO::SQLSRV_ATTR_DIRECT_QUERY se distingue de celle émulée et prend en charge ces déclarations.
  • Les métadonnées invalides, les parcours de déclaration non pris en charge et les paramètres adaptatifs invalides signalent SQLSTATE IMSSP. Une entrée dépassant une déclaration valide avec limites renvoie 22001. Traitez les erreurs selon PDO::ATTR_ERRMODE ; les exemples supposent le mode exception.
  • Le pilote ne consulte pas la colonne de destination et ne réécrit pas votre Transact-SQL pour choisir une déclaration. Choisissez des types et des longueurs correspondant à votre schéma.