Verbinding maken met de server

PHP-stuurprogramma downloaden

Gebruik deze gids om een verbinding te openen, de waarden die PHP ontvangt te controleren en de verbinding vrij te geven wanneer het werk klaar is. De programma's gebruiken SQL Server-authenticatie voor een lokale of externe SQL Server testdatabase. Voor wachtwoordloze Azure- en Fabric-verbindingen gebruik je Connect to Azure SQL and Fabric SQL.

SQLSRV accepteert een servernaam en een associatieve array van verbindingsopties. PDO_SQLSRV implementeert PHP Data Objects (PDO) en accepteert een databronnaam (DSN)-string, aparte argumenten voor aanmeldingsgegevens en een array van PDO-attributen. Beide gebruiken de Microsoft ODBC Driver voor SQL Server. Een verbinding die met de ene API werkt maakt de optienamen of PHP-types van de andere API niet uitwisselbaar.

Voordat je verbinding maakt

1. Installeer een ondersteunde PHP-runtime en Microsoft ODBC-driver, en laad de PHP-extensie die je wilt gebruiken.
2. Controleer het PHP-proces waarmee je applicatie wordt uitgevoerd. Voer php --ini uit om de configuratie van de commandoregelregel te vinden en php -m om de geladen extensies weer te geven. SQLSRV vereist sqlsrv. PDO_SQLSRV vereist PDO en pdo_sqlsrv. Een webserver kan een ander php.ini, runtime en account gebruiken dan je terminal.
3. Verkrijg het serveradres, databasenaam en een identiteit met toestemming om verbinding te maken. Een databaselogin geeft niet automatisch toegang tot alle tabellen.
4. Configureer netwerktoegang en een vertrouwd servercertificaat. Deze programma's vragen expliciet om encryptie en certificaatvalidatie. Verbind via de hostnaam in het certificaat in plaats van een IP-adres te gebruiken dat het certificaat niet dekt.

Stel deze variabelen in in de omgeving van het PHP-proces, met je shell, ontwikkeltool of hostingconfiguratie. Commit geen wachtwoordbestand en druk de omgevingsvariabelen niet af.

Lees server- en database-instellingen uit de vertrouwde applicatieconfiguratie, niet uit webverzoekparameters. Het PDO-voorbeeld plaatst die instellingen in een DSN. Houd de verbindingszoekwoorden onder applicatiecontrole.

Sla de daadwerkelijke databasenaam, gebruikersnaam en wachtwoord op in de omgevingsvariabelen, zonder zelf beugels toe te voegen of te verdubbelen. Beide PHP-extensies vereisen ODBC-achtige escaping, zelfs voor SQLSRV-arrayopties en PDO-constructorargumenten: verdubbel elke sluitende scrace en sluit de waarde in clappes. Elk programma doet dit één keer voordat deze waarden aan de driver worden doorgegeven. De buitenste haakjes behouden letterlijke haken aan het begin en einde van een waarde en voorkomen dat puntkomma's binnen de databasenaam de PDO-DSN-instellingen scheiden. Dit ontsnappen staat los van Transact-SQL (T-SQL) parameterbinding.

Open, query, en sluit met SQLSRV

Sla dit programma op als connect-sqlsrv.php, en voer php connect-sqlsrv.php uit. Het voert een T-SQL-query uit zonder tabellen aan te maken of data te wijzigen. CharacterSet selecteert UTF-8 voor tekengegevens; het verandert de kolomtypes of sortering van de database niet.

<?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);
}

Verwachte uitvoer:

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

De verbinding en de statement zijn PHP-resources, handles die je doorgeeft aan de sqlsrv_* functies. Controleer false voordat je een van beide handvaten gebruikt. Haal sqlsrv_errors() direct op na een fout omdat een latere SQLSRV-aanroep de foutverzameling kan vervangen.

SQLSRV_FETCH_ASSOC geeft een associatieve array met kolomnamen als sleutels terug. SQLSRV_FETCH_NUMERIC geeft nul-gebaseerde numerieke sleutels terug; de standaard SQLSRV_FETCH_BOTH bevat beide vormen. Voor sqlsrv_fetch_array()betekent , null geen rijen meer en false betekent een fout. Een SQL NULL binnen een rij is PHP null; dat betekent niet dat de rij ontbreekt. Gebruik === deze bij het onderscheiden van deze waarden.

Open, zoek een query en sluit met PDO_SQLSRV

Sla dit aparte programma op als connect-pdo.php, en voer php connect-pdo.php het uit in dezelfde omgeving. sqlsrv: selecteert PDO_SQLSRV, niet de generieke PDO_ODBC driver van 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;
}

Verwachte uitvoer:

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

PDO_SQLSRV geeft deze int-kolom standaard als een PHP-string terug. Om PHP-numerieke types voor ondersteunde numerieke kolommen aan te vragen, zet PDO::SQLSRV_ATTR_FETCHES_NUMERIC_TYPE u op true. Gebruik in PHP niet lukraak een cast voor decimale waarden; een floating-point-conversie kan precisie verliezen.

PDO-attributen zijn instellingen op het verbindings- of statementobject. PDO::ATTR_ERRMODE met PDO::ERRMODE_EXCEPTION maakt database-operatiefouten die PDOException. Verbindingsconstructie genereert bij mislukking een uitzondering, ongeacht die instelling. PDO::FETCH_ASSOC geeft benoemde sleutels, PDO::FETCH_NUM geeft nul-gebaseerde numerieke sleutels, en PDO::FETCH_BOTH geeft beide. fetch() geeft aan het einde van het resultaat terug; false SQL-waarden NULL binnen een rij blijven PHP null.

Deze commandoregelprogramma's zorgen ervoor dat fouten de uitvoering stoppen. In een webapplicatie vang je uitzonderingen in de code die het verzoek afhandelt. Noteer diagnostische details in beschermde logs en geef een generieke foutrespons terug. Stuur sqlsrv_errors()geen uitzonderingstraces, verbindingsstrings of tokens naar een browser.

Een verificatiemodus kiezen

Voor SQL-authenticatie neemt UID SQLSRV en PWD in zijn verbindingsopties-array. PDO_SQLSRV neemt de gebruikersnaam en het wachtwoord als tweede en derde argument bij de aanroep van new PDO(), niet als DSN-zoekwoorden. Voor een toegangstoken neemt SQLSRV AccessToken op in de opties-array, terwijl PDO_SQLSRV deze in de DSN gebruikt.

Als je de gebruikersnaam, het wachtwoord, Authentication, en AccessTokenweglaat, vragen beide drivers om geïntegreerde authenticatie van ODBC via Trusted_Connection=Yes. Op Linux en macOS vereist dit verzoek een geldig Kerberos-ticket en ODBC integrated-authentication configuratie. Het verleent een willekeurig lokaal account geen toegang tot een externe server.

Configureer de verbinding en de bijbehorende instructies

Verbindingsinstellingen gelden voor de sessie die je opent. Statement-instellingen zijn van toepassing op een bepaalde query. Stel timeouts en resultaattypes expliciet in wanneer je applicatie andere waarden dan de standaardwaarden nodig heeft.

Voor de volledige lijst van trefwoorden, toegestane waarden en standaardinstellingen, zie Verbindingsopties. Plaats geen CharacterSet, QueryTimeout of PDO:: constante namen in een PDO DSN.

Beheer de levensduur van de verbinding

Open een verbinding wanneer voor een verzoek of taak databasewerk nodig is. Hergebruik het gedurende dat verzoek of die klus, en geef het dan vrij als het klaar is. Verbind en ontkoppel niet voor elke rij. Bij een langlopend worker-proces geef je statements vrij en rond je elke transactie af voordat je de volgende klus accepteert.

SQLSRV sluit bijbehorende statements wanneer je de verbinding sluit. Door statements eerder expliciet vrij te maken, komen resources vrij zonder de verbinding te beëindigen. Voor PDO verwijdert het toewijzen van $pdo = null alleen de referentie van die variabele. A PDOStatement of een andere variabele kan de verbinding behouden. Laat die verwijzingen ook vrij. closeCursor() geeft in afwachtende resultaten vrij zodat de verklaring hergebruikt kan worden; het is geen methode om de verbinding te sluiten.

Beide API's starten in autocommit-modus: een succesvolle instructie commit zonder een aparte applicatiecommit, tenzij je een transactie start. Voor een groep schrijfopdrachten die samen moeten slagen of falen, gebruik sqlsrv_begin_transaction() dan of $pdo->beginTransaction(), commit of rol expliciet terug. Het sluiten van een verbinding met een openstaande transactie leidt tot een rollback, geen commit. Vertrouw niet op shutdown cleanup om je transactiebeleid uit te voeren. Voor volledige voorbeelden, zie Transacties uitvoeren.

Het vrijgeven van een PHP-verbindingshandle sluit niet per se de fysieke netwerkverbinding af. ODBC-pooling kan het bewaren voor hergebruik. Pooling is geen reden om PHP-bronnen voor onbepaalde tijd te behouden, en PDO_SQLSRV ondersteunt PDO::ATTR_PERSISTENT => truedat niet. Voor platformspecifieke poolingconfiguratie, zie Connection pooling.

Pas de gids toe op je SQL-doel

De handle-, fetch- en cleanup-patronen zijn van toepassing op beide extensies op ondersteunde SQL-doelen. Verbindingseindpunten, authenticatie, netwerktoegang en SQL-mogelijkheden verschillen.

Voor service-specifieke setup, zie Azure en Fabric-verbindingen.

Problemen met de verbinding oplossen

Start met de stap die is mislukt. Een succesvolle Transmission Control Protocol (TCP)-controle bewijst niet dat authenticatie of certificaatvalidatie is geslaagd.

Andere artikelen over verbindingen

• Verbind op een gespecificeerde poort
• Verbindingsopties
• Groepsgewijze verbindingen
• Schakel meerdere actieve resultaatsets uit (MARS)
• Ondersteuning voor LocalDB
• Ondersteuning voor hoge beschikbaarheid en rampenherstel
• Verbinding maken met Microsoft Azure SQL Database
• Idle verbindingsveerkracht

Verwante onderwerpen

• Programmeergids voor de Microsoft Drivers voor PHP voor SQL Server
• Voorbeeldapplicatie (SQLSRV-driver)