Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Usa dichiarazioni esplicite per inviare una stringa di input come varchar o nvarchar con una lunghezza SQL specificata. In alternativa, opta per il dimensionamento adattivo per iniziare con una lunghezza scelta e aumentare la dichiarazione quando invii valori più lunghi.
Queste opzioni richiedono la versione 5.14.0 o successiva e si applicano solo a PDO_SQLSRV, il driver PHP Data Objects (PDO). Per SQLSRV, continua a specificare i tipi SQL nell'array di parametri descritto in Specifica i tipi di dati SQL Server. Nessuno dei due approcci cambia la definizione della colonna di destinazione.
Scegli un metodo di dichiarazione
| Method | Configurazione | Behavior |
|---|---|---|
| Metadati espliciti della dichiarazione | Chiama PDOStatement::setAttribute(PDO::SQLSRV_ATTR_PARAM_METADATA, $metadata) dopo prepare. |
Si applica a bindParam, bindValue, e execute($params). |
| Metadati di binding espliciti | Passa un array di dichiarazione come quinto argomento di bindParam. |
Sostituisce l'intera voce dei metadati dell'istruzione per quel binding, inclusa la sua codifica opzionale. |
| Dimensionamento adattivo | Imposta PDO::SQLSRV_ATTR_DEFAULT_STR_LENGTH sulla connessione prima di creare l'istruzione. |
Si applica alle stringhe di input ammissibili senza una dichiarazione esplicita. |
Senza metadati espliciti o dimensionamento adattivo, il comportamento di dimensionamento dei parametri esistente rimane invariato. Non hai bisogno di queste opzioni per le normali query parametrizzate.
Dichiara una stringa di input
Ogni dichiarazione è un array con chiavi costanti di tipo intero e valori interi.
| Key | Value |
|---|---|
PDO::SQLSRV_PARAM_DECLARED_STR_TYPE |
PDO::SQLSRV_PARAM_DECLARED_STR_TYPE_VARCHAR o PDO::SQLSRV_PARAM_DECLARED_STR_TYPE_NVARCHAR. |
PDO::SQLSRV_PARAM_DECLARED_STR_LENGTH |
Per varchar, da 1 a 8.000 byte. Per nvarchar, da 1 a 4.000 unità di codice in Unicode Transformation Format a 16 bit (UTF-16). Usa PDO::SQLSRV_PARAM_DECLARED_STR_LENGTH_MAX per varchar(max) o nvarchar(max). |
PDO::SQLSRV_ATTR_ENCODING (opzionale) |
La codifica dei caratteri della stringa di input PHP. Per l'input in formato di trasformazione Unicode a 8 bit (UTF-8), usa PDO::SQLSRV_ENCODING_UTF8 oppure PDO::SQLSRV_ENCODING_UTF8_VARCHAR. Il tipo dichiarato, non la codifica, imposta il tipo SQL. Puoi anche usare PDO::SQLSRV_ENCODING_SYSTEM per l'input nella codifica del sistema. La codifica binaria non è supportata. |
Devi includere entrambe le chiavi di dichiarazione. Le stringhe numeriche, i valori booleani, le lunghezze zero e le chiavi non riconosciute sono non valide. Un carattere Unicode supplementare, come "\u{1F600}", occupa due unità di codice UTF-16, anche se PHP memorizza la sua rappresentazione UTF-8 in quattro byte.
La codifica descrive i byte sorgente. Il tipo dichiarato descrive il parametro SQL inviato al server. Ad esempio, puoi inviare input UTF-8 come varchar senza convertire i byte di origine nella codifica di sistema. La conversione a varchar dipende comunque dalla collazione SQL e dal suo repertorio di caratteri. Una lunghezza SQL esplicita non alloca un buffer PHP.
Quando il driver dichiara un parametro bound per un'istruzione preparata, ignora i flag PDO::PARAM_STR_NATL e PDO::PARAM_STR_CHAR. Usa una dichiarazione per scegliere varchar o nvarchar.
Per i metadati dell'istruzione, usa una mappa dagli identificatori dei parametri agli array di dichiarazione:
- Usa posizioni a partire da 1 per segnaposti con punto interrogativo, come
[1 => $declaration]. Le posizioni devono essere numeri interi da 1 a 2.100 e devono identificare i parametri vincolati quando si esegue. - Usa un nome segnaposto univoco, con o senza i due punti, come
['name' => $declaration]o[':name' => $declaration]. Un nome provvisorio ripetuto non identifica una posizione univoca. Non specificare la stessa posizione due volte tramite nomi diversi o chiavi numeriche. - Imposta i metadati dopo
prepare, non nel suo array di opzioni. Ogni setter riuscito sostituisce l'intera mappa e resetta la cronologia delle dimensioni adattive. Una sostituzione non valida conserva la mappa precedente. Pass[]per cancellare la mappa;nullnon è valido. - Richiamare
getAttribute(PDO::SQLSRV_ATTR_PARAM_METADATA)sull'istruzione per recuperare la mappa normalizzata a posizioni basate su 1. Restituisce metadati dell'istruzione, non override per binding o cronologia delle dimensioni adattive.
Un array passato a execute fornisce valori, non dichiarazioni. I suoi valori posizionali utilizzano il consueto array PHP basato su zero, come ['text']; la sua mappa di metadati utilizza [1 => $declaration]ancora .
Per bindParam, mantieni il quarto argomento su 0 per una dichiarazione di input. Un quarto argomento positivo seleziona il comportamento del buffer di output; non è la nuova lunghezza della dichiarazione SQL. Le opzioni di codifica intera nel quinto argomento continuano a funzionare. Un array di dichiarazioni sovrascrive l'intera voce dello statement per quel binding, mentre un'opzione di codifica intera sovrascrive solo la codifica. Un nuovo binding senza l'array di dichiarazioni rimuove la sovrascrittura di quel binding, ma mantiene i metadati dello statement.
Esempio: dichiarazioni esplicite
Gli esempi in questo articolo assumono una connessione aperta PDO in $conn che utilizza PDO::ERRMODE_EXCEPTION. Per aprirne uno, vedi Connettersi al server. Essi utilizzano la seguente tabella:
CREATE TABLE dbo.Customers
(
CustomerID int IDENTITY PRIMARY KEY,
Name nvarchar(100) NOT NULL,
Code varchar(10) NOT NULL
);
Senza una dichiarazione, il driver invia ogni valore di stringa nei seguenti esempi come nvarchar(4000). Ogni esempio dichiara invece il tipo e la lunghezza della colonna corrispondente.
Il seguente esempio utilizza parametri nominati, metadati di istruzione e un array passato a execute. Il server riceve @P1 nvarchar(100) e @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'esempio seguente utilizza un segnaposto del punto interrogativo e bindValue per trovare un cliente tramite codice. La chiave 1 dei metadati identifica il primo segnaposto. La dichiarazione di varchar(10) corrisponde alla colonna Code. Quando una colonna varchar viene confrontata con un parametro nvarchar, SQL Server converte il valore della colonna, il che può impedire una ricerca dell'indice.
$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";
Il seguente esempio passa un array di dichiarazione come quinto argomento di bindParam, con 0 come quarto argomento. La lunghezza dichiarata rimane fissa durante le esecuzioni. Un valore superiore a 10 caratteri genera un errore con SQLSTATE 22001 e non inserisce alcuna riga.
$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";
}
Opta per il dimensionamento adattivo
Imposta PDO::SQLSRV_ATTR_DEFAULT_STR_LENGTH nell'array di opzioni del costruttore di connessione oppure con PDO::setAttribute. Il valore deve essere un numero intero da 0 a 8.000. Il valore predefinito, 0, disabilita il dimensionamento adattivo.
Ogni nuova istruzione copia l'impostazione della connessione. Modificarla successivamente influisce sui nuovi statement, non su quelli esistenti. Questo attributo non è un'istruzione o un'opzione prepare.
Per ogni posizione di parametro idonea, il driver parte dal piano configurato e espande la dichiarazione per adattarla a valori più lunghi. Mantiene la dimensione massima utilizzata in quella posizione quando successivamente invii valori più brevi, vuoti o nulli. Per l'input UTF-8 con la codifica predefinita, utilizza nvarchar e misura la crescita in unità di codice UTF-16. Per l'input codificato dal sistema, utilizza varchar e riserva tre byte extra per ogni byte non-ASCII, perché la conversione a una collazione UTF-8 può allungare il valore. Promuove dichiarazioni oltre 4.000 unità nvarchar o 8.000 byte varchar a max, incluso quando il minimo iniziale supera il limite massimo del tipo.
Le dichiarazioni esplicite hanno la precedenza sulla dimensionazione adattiva. I parametri legati come interi, dati binari, flussi o parametri output/input-output mantengono il loro comportamento esistente. Modificare il tipo SQL inferto modificando la codifica avvia una nuova cronologia delle dimensioni per quel parametro.
Esempio: dimensionamento adattivo
Il seguente esempio utilizza la tabella dell'esempio della dichiarazione esplicita. Stabilisce un livello minimo di 20 sulla connessione prima di preparare l'istruzione. La prima esecuzione invia @P1 nvarchar(20) e @P2 nvarchar(20). Il secondo nome ha 30 caratteri, quindi il driver estende @P1 a nvarchar(30). Entrambi i parametri sono nvarchar perché l'input è UTF-8, anche se la colonna Code è varchar. Per corrispondere a una colonna varchar , usa una dichiarazione esplicita.
$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']);
L'impostazione dimensione controlla le dichiarazioni dei parametri, non la capacità della colonna di destinazione.
Limitazioni ed errori
- Le dichiarazioni esplicite supportano solo stringhe di input e valori nulli associati con
PDO::PARAM_STRoPDO::PARAM_NULL. Rifiutano la codifica binaria, gli stream, altri tipi di parametri e i parametri output/input-output. - Nella versione 5.14.0, il varchar esplicito limitato accetta solo input ASCII (American Standard Code for Information Interchange). Per input non ASCII, usa nvarchar, varchar(max) con una collazione adatta o dimensionamento adattivo. Il dimensionamento adattivo non elimina i vincoli di conversione delle regole di confronto.
- Le dichiarazioni esplicite e le dimensionazioni adattive non sono supportate con Always Encrypted o le preparazioni emulate. Un'impostazione adattiva diversa da zero fa fallire la creazione di istruzioni per entrambi i percorsi. Disabilitalo prima di creare tali statement SQL. L'esecuzione diretta attraverso
PDO::SQLSRV_ATTR_DIRECT_QUERYè distinta dalle prepared statement emulate e supporta queste dichiarazioni. - Metadati non validi, percorsi di dichiarazione non supportati e impostazioni adattivi non valide segnalano SQLSTATE
IMSSP. Un input che supera una dichiarazione con limiti validi riporta22001. Gestisci gli errori secondoPDO::ATTR_ERRMODE; gli esempi assumono la modalità eccezione. - Il driver non cerca la colonna di destinazione né riscrive la tua Transact-SQL per selezionare una dichiarazione. Scegli tipi e lunghezze che corrispondono al tuo schema.