Microsoft meghajtók PHP-hez SQL Serverhez

PHP-illesztőprogram letöltése

A Microsoft Drivers for PHP for SQL Server PHP kiterjesztések, amelyek lehetővé teszik adatok olvasását és írását a Microsoft SQL Database Engine-ben PHP szkriptekből történő felhasználásával. A csomag két meghajtót tartalmaz, amelyek ugyanazt a Microsoft ODBC Driver for SQL Server-t csomagolják, és ugyanazokat a csatlakozási lehetőségeket használják, így kiválaszthatod az API-t, ami illik a kódbázisodhoz:

  • Az SQLSRV egy eljárási API-t (sqlsrv_*függvényeket) tár ki, amely az SQL Server funkcióira szabott.
  • PDO_SQLSRV megvalósítja a PHP Data Objects (PDO) interfészt, így a kód, amely már más adatbázisokban használja a PDO-t, minimális változtatással célozhatja SQL Server.

Mindkét meghajtó csatlakozik az Azure SQL Database-hez, az Microsoft Fabric-ben található SQL adatbázishoz, Azure SQL Managed Instance-hoz, valamint az összes támogatott SQL Server verzióhoz és kiadáshoz (beleértve az Express kiadásokat is). PHP folyamokat használnak nagy bináris és karakterértékek átmozgatására anélkül, hogy teljesen memóriába töltődnének.

Válassza ki a kiindulási pontot

Azure SQL üzemi alapkonfigurációja

Ezt a snippetet használd kiindulópontként egy gyártásorientált Azure SQL kapcsolathoz a PDO_SQLSRV meghajtóval. A szervert és az adatbázist környezeti változókból olvassa (például Azure App Service alkalmazásbeállításokból), menedzselt identitással autentikál, engedélyezi a Transport Layer Security (TLS) rendszert szervertanúsítvány ellenőrzéssel, beállítja a bejelentkezési időkorlátot, amely lefedi a hidegindítási failovert, valamint beállítja ConnectRetryCount az ConnectRetryInterval SQL Server tétlen kapcsolati rezisztenszibilitását. Az alkalmazásszintű connectWithRetry és queryWithRetry segédfüggvények mind a kezdeti kapcsolódást, mind az egyes lekérdezéseket korlátos exponenciális visszalépéssel kezelik, és elkülönítik az átmeneti kapcsolati hibákat (amelyek új kapcsolatot igényelnek) az átmeneti lekérdezési hibáktól (amelyek ugyanazt a kapcsolatot használják újra).

Szükséges PHP 8.0 és újabb verziók, az PDO_SQLSRV kiterjesztés, valamint Microsoft ODBC drivert SQL Server 17.3.1.1 és újabb verziókhoz .Authentication=ActiveDirectoryMsi A támogatott Authentication értékek teljes listájáért lásd: Kapcsolódj Microsoft Entra hitelesítéssel.

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

/**
 * 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); // 1, 2, 4 seconds
            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');
}

/**
 * Run a parameterized query, retrying transient statement failures on the same
 * connection. Deadlocks (1205) roll back the transaction before the driver sees
 * the error, so rerunning a single statement is safe. If the statement was part
 * of a multistatement transaction, wrap the whole transaction in your own retry
 * loop so earlier statements replay too.
 */
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, TRANSIENT_SERVER_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.');
}

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

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

Ez a kódrészlet az Azure SQL Database feladatátvételi csoportjaihoz és az Azure SQL Managed Instance-hez lett hangolva.

  • Driver={ODBC Driver 18 for SQL Server} rögzíti az ODBC 18-illesztőprogramot. Ha a hostnak ODBC 17 is van telepítve, PDO_SQLSRV köthető ODBC 17-hez. A régebbi 17.x verziók elutasítják az Authentication újabb értékeket; például Authentication=ActiveDirectoryMsi az ODBC 17.3.1.1 vagy egy újabb verzió szükséges. Lásd: Érvénytelen érték a kapcsolati karakterlánc attribútumához 'Authentication'.

  • ConnectRetryCount és ConnectRetryInterval az ODBC-kapcsolatkarakterlánc kulcsszavai, amelyek lehetővé teszik az SQL Server a tétlen kapcsolatokkal szembeni rugalmasságát: az illesztőprogram automatikusan újracsatlakoztat egy megszakadt tétlen kapcsolatot. Ez eltér az alkalmazásszintű queryWithRetry, amely újrapróbál egy olyan utasítást , amely átmeneti hibával, például holtpont vagy lekérdezési időkorlát esetén meghibásodik. A kettő kiegészítő jellegű, szóval mindkettőt tartsd meg. Győződjön meg arról, hogy a(z) LoginTimeout legalább ConnectRetryCount * ConnectRetryInterval, hogy a tétlenségi újracsatlakozási folyamat megkapja a teljes időkeretét; a minta 90 másodpercet használ az 5 × 15 másodperces újrapróbálkozásokra, plusz némi ráhagyást a kezdeti bejelentkezéshez egy hideg feladatátvétel esetén.

  • Egészítse ki az alkalmazásszintű error_log() hívásokat vezetőoldali diagnosztikával. PDO_SQLSRV esetén állítsa be a(z) pdo_sqlsrv.log_severity értéket a(z) php.ini elemben (csak inicializáláskor állítható be); SQLSRV esetén futásidőben hívja meg a(z) sqlsrv_configure("LogSubsystems", ...) függvényt. További információért lásd: Naplózás tevékenység.

    ; 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

  • Egy felhasználó által hozzárendelt felügyelt identitás esetén adja meg az identitás azonosítóját a PDO $username argumentumaként (new PDO($dsn, $identityId, null, $options)). Használja az identitás kliensazonosítójátaz Azure App Service-en vagy az Azure Container Instance-on; egyébként használja az objektumazonosítóját. A PHP illesztőprogramok ezt a viselkedést az alapul szolgáló Microsoft ODBC Driver for SQL Server-től öröklik; további információért lásd: Microsoft Entra ID használata az ODBC Driverrel. A PDO_SQLSRV elutasítja a(z) UID elemet magában a DSN-ben, ezért használd inkább a konstruktor paraméterét. Ha a(z) null értéket adja át felhasználóként (ahogyan a mintában is), az Azure-gazdagép rendszer által hozzárendelt felügyelt identitását választja ki. SQLSRV (eljárásos) esetén adja át a(z) UID értéket a kapcsolati beállításokat tartalmazó tömbben.

  • Állítsd be, MultiSubnetFailover=true mikor csatlakozol failover-csoporthallgatóhoz, elérhetőségi csoporthallgatóhoz vagy failover klaszter instance végponthoz. Beállítása javítja a kapcsolati teljesítményt mind az egyalnetes, mind a többalnevetes elérhetőségi csoport hallgatói számára. További információkért lásd: A magas rendelkezésre állás és a vészhelyreállítás támogatása.

  • Kiolvasási horizontális skálázáshoz vagy olvasható másodlagos replikához add hozzá a ApplicationIntent=ReadOnly elemet az adatforrás nevéhez (DSN-hez).

  • Olyan szuverén felhőknél, ahol a tanúsítvány Subject Alternative Name (SAN) nem tartalmazza azt a hosztot, amelyhez csatlakozol, adj HostNameInCertificate hozzá a DSN-hez (például *.database.usgovcloudapi.net Azure Government esetén).

  • Az illesztőprogram a token lekéréséhez az alapul szolgáló Microsoft ODBC Driver for SQL Server illesztőprogramra támaszkodik. A kezelt identitás, a szolgáltatási alap és a hozzáférési token áramlások mind ODBC-n keresztül haladnak. További információ: A Microsoft Entra ID használata az ODBC-illesztővel.

  • A nagyobb biztonság és a környezetek közötti hordozhatóság érdekében tartsd a kapcsolati információkat a kódon kívül. Tárold a kapcsolati információkat az alkalmazásod konfigurációs rendszerében, és használd az Azure Key Vault-t az érzékeny értékekhez és központilag menedzselt kapcsolódási beállításokhoz.

  • Az egyenértékű SQLSRV kapcsolat a(z) sqlsrv_connect($server, ['Database' => $database, 'Encrypt' => true, 'Authentication' => 'ActiveDirectoryMsi', /* ... */]) elemet használja, és egy erőforrást ad vissza. Az újrapróbálkozási minta ugyanaz: kezeljük a sqlsrv_connect által visszaadott false értéket, ellenőrizzük az SQLSTATE-et a sqlsrv_errors() segítségével, majd várjunk egy ideig az újrapróbálkozás előtt. Egy megdolgozott példáért lásd: 4. lépés: Rugalmasan csatlakozz az SQL-hez PHP-vel.

  • Az újrapróbálkozási segédfüggvények a $e->errorInfo[1] elemet a isset() által védve olvassák. PDOException::$errorInfo deklarálva van mint ?array, és alapértelmezett értéke null, ezért a védelmi ellenőrzés egy 0 illesztőprogram-kódra tér vissza, és az SQLSTATE 08 előtagja dönti el, hogy újrapróbálkozik-e.

A konfiguráció egyes részeivel kapcsolatos további információkért lásd:

Az átmeneti Azure SQL hibakatalógusát az átmeneti csatlakozási hibák hibaelhárítása című témakörben találja.

Legfontosabb funkciók

  • Két API, egy közös illesztőprogram-csomag: az eljárásalapú SQLSRV az elsősorban SQL Serverhez készült kódhoz, vagy a PDO_SQLSRV a hordozható PDO-kódhoz.
  • Széles platformtámogatás: Windows-on, Linuxon és macOS-en fut, támogatott PHP verziókkal.
  • Titkosított kapcsolatok: TLS-sel titkosított kapcsolatok Encrypt=true használatával, a szervertanúsítvány ellenőrzését pedig a TrustServerCertificate vezérli.
  • Microsoft Entra ID-hitelesítés: Jelszó nélküli kapcsolatok menedzselt identitással, szolgáltatásnévvel és hozzáférési tokenes folyamatokkal a mögöttes Microsoft ODBC Driver for SQL Server segítségével.
  • Always Encrypted: Ügyféloldali titkosítás bizalmas oszlopokhoz, opcionális biztonságos enklávékkal a helyszíni műveletekhez.
  • Kapcsolat rugalmassága: beépített újrapróbálkozások üresjárati kapcsolatokhoz ConnectRetryCount és ConnectRetryInterval használatával.
  • PHP folyamok: Olvasd és írd ki a nagy bináris és karakter értékeket streamként ahelyett, hogy betöltenéd őket a memóriába.
  • Az SQL Server adattípusainak széles körű támogatása: datetimeoffset, táblázatértékű paraméterek, nvarchar és Unicode PDO::SQLSRV_ENCODING_UTF8.

Első lépések

Cikk Description
Rendszer követelmények Támogatta a PHP, operációs rendszer és SQL Server verziókat.
Támogatási mátrix Részletes kompatibilitási mátrix PHP driver kiadásokhoz.
Töltse le a Microsoft Drivers for PHP for SQL Server Letöltési hivatkozások és kiadási összetevők.
Telepítési útmutató Linux és macOS számára Telepítsd a drivert és annak ODBC előfeltételeit Linuxon és macOS-en.
A meghajtók betöltése Engedélyezd a kiterjesztéseket itt: php.ini.
Ismerkedés a PHP SQL-illesztőprogrammal Részletes útmutató, amely egységbe foglalja a bevezetés négy lépését.
A PHP SQL illezőprogramjának áttekintése Mi van a csomagban, és mikor válasszuk SQLSRV-t vagy PDO_SQLSRV-t.

Konfigurálás és csatlakoztatás

Cikk Description
Csatlakozás a szerverhez Nyiss kapcsolatot egy SQL Server példányhoz a PHP-ből.
Kapcsolati beállítások Teljes hivatkozás a kapcsolati kulcsszavakhoz, alapértelmezetekhez és azok beállításához.
Csatlakozás a Microsoft Azure SQL Database-hez Kapcsold egy PHP alkalmazást Azure SQL Database-be.
Csatlakozz egy meghatározott porthoz Célozz meg egy nem alapértelmezett TCP portot.
Kapcsolatkészletezés Használd újra az ODBC kapcsolatokat a PHP kérések során.
A több aktív eredményhalmaz (MARS) letiltása Kapcsold ki a MARS-t a kompatibilitás miatt.
A LocalDB támogatása Csatlakozz egy SQL Server LocalDB instance-hoz.
Magas rendelkezésre állás támogatása, katasztrófa utáni helyreállítás A rendelkezésre állási csoport figyelői és a többalhálózatos feladatátvétel.
Inaktív kapcsolat rugalmassága Automatikus újracsatlakozás a hibás alapjárati kapcsolatok esetén.

Authenticate

Cikk Description
Csatlakozás Microsoft Entra-hitelesítéssel Menedzselt identitás, szolgáltatási alap, hozzáférési token és jelszóáramlások.
Csatlakozz SQL Server hitelesítéssel Használj SQL bejelentkezést felhasználónévvel és jelszóval.
Csatlakozz Windows authentication használatával Használj Windows integrált hitelesítést domainhez tartozó hosztokon.

Secure

Cikk Description
Biztonsági szempontok Fenyegetési modell és mélyreható védelmi útmutató PHP alkalmazásokhoz.
Mindig titkosítva a PHP illesztőprogramokkal Ügyféloldali titkosítás konfigurálása bizalmas oszlopokhoz.
Mindig titkosított, biztonságos enklávékkal Összetett műveletek engedélyezése titkosított oszlopokon biztonságos enklávék használatával.

Adatok lekérése és frissítése

Cikk Description
Műsorvezetés Végpontig programozási útmutató mindkét meghajtóhoz.
Végrehajtási függvények összehasonlítása Válaszd ki a megfelelő végrehajtási függvényt a munkaterhelésedhez.
Közvetlen és előkészített utasítások végrehajtása (PDO_SQLSRV) Mikor kell közvetlen végrehajtást használni a előre készített utasítások helyett?
Adatok visszakeresése Hívd be sorokat, oszlopokat és streaming értékeket.
Adatok frissítése Sorok beépítése, frissítése és törlése.
Paraméterezett lekérdezések végrehajtása Bind paraméterek az SQL injekció elleni védelem érdekében.
Adatküldés streamként Streamelj nagy bináris és karakterértékeket az SQL Server-be.
Tranzakciók végrehajtása Csoportosítani az állításokat atomi tranzakciókba.
Táblázatértékű paraméterek használata Átadj egy TABLE paramétert egy tárolt eljárásnak.
Határozz meg kurzortípust, és válaszd ki a sorokat Válassz csak előre irányuló, statikus, dinamikus vagy keyset kurzorokat.

Adattípusok

Cikk Description
Adattípusok átalakítása Hogyan felelteti meg a meghajtó a PHP-típusokat az SQL Server-típusoknak.
Alapértelmezett SQL Server adattípusok Minden PHP értékhez alapértelmezett SQL Server típus.
Alapértelmezett PHP adattípusok Minden SQL Server oszloptípushoz alapértelmezett PHP típus.
Adja meg az SQL Server adattípusait (SQLSRV) Felülírd az SQL Server típust paraméterkötéskor.
Határozd meg a PHP adattípusokat Felülírd a PHP típust a lekéréskor.
UTF-8 adatok küldése és letöltése A(z) PDO::SQLSRV_ENCODING_UTF8 használata Unicode oda-vissza konverziókhoz.
ASCII adatok küldése és letöltése Linuxon és macOS-en Kezeld az ASCII oda-vissza utazásokat nem Windows hasztokon.
Tizedesértékek és pénzösszegek formázása (SQLSRV) Formázd a decimális és pénz oszlopokat az SQLSRV driverrel.
Decimális számok és pénzösszegek formázása (PDO_SQLSRV) Formázd a tizedes és pénzoszlopokat a PDO_SQLSRV meghajtóval.
Nem rendszerszintű helyszínbeállítások Lokalizált tizedesválasztók és egyéb helyi szempontok.

Hibák és diagnosztikák

Cikk Description
Kezelési hibák és figyelmeztetések A hibák és figyelmeztetések kezelése mindkét illesztőprogram esetén.
Hiba- és figyelmeztetéskezelés konfigurálása (SQLSRV) Beállíthatja, hogyan jelezze az SQLSRV illesztőprogram a hibákat és figyelmeztetéseket.
Hibák és figyelmeztetések kezelése (SQLSRV) Az SQLSRV függvények által visszaküldött hibák ellenőrzése.
Naplózási tevékenység Engedélyezd az illesztőprogram-naplózást a diagnosztikai adatok rögzítéséhez.

Üzembe helyezés és üzemeltetés

Cikk Description
Teljesítmény finomhangolása Kapcsolatkezelés, kötegelt feldolgozás, előkészített lekérdezések, kurzorok, memória és szerveroldali monitorozás.
Troubleshooting Diagnosztizálni a gyakori telepítési, kapcsolati, lekérdezési, adattípust, tranzakciót és konténerproblémákat.

Hivatkozási tartalom

Cikk Description
SQLSRV-illesztőprogram API-referenciája Minden sqlsrv_* függvény, paraméter és visszaadó érték.
PDO_SQLSRV vezetői referencia A PDO és PDOStatement módszereket a PDO_SQLSRV driver támogatja.
állandók A meghajtók által felfedett állandók, beleértve a típus- és kódolási állandókat.
Cikk Description
Kiadási megjegyzések Verziónkénti előzmények új funkciókkal, hibajavításokkal, platformtámogatási változásokkal és letöltési linkekkel.
A dokumentációban található kódmintákról A kódminták által használt konvenciók ebben a szakaszban.
Kódminták a PHP SQL driverhez Végponttól végpontig példa alkalmazások SQLSRV és PDO_SQLSRV számára.
Támogató források Közösségi és támogató csatornák.

Kapcsolódó tartalom

  • Last updated on