Microsoft meghajtók PHP-hez SQL Serverhez

PHP-illesztőprogram letöltése

A Microsoft Drivers for PHP for SQL Server olyan PHP-kiterjesztések, amelyekkel PHP-szkriptekből adatokat olvashat és írhat a Microsoft SQL Database Engine rendszerben. A két bővítmény ugyanazt a Microsoft ODBC Driver for SQL Server-t használja, de eltérő PHP API-kat és illesztő-specifikus lehetőségeket kínálnak:

  • 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. A PDO hívásokat megtarthatod a meglévő adatbáziskódban, de mielőtt adatbázist váltasz, nézd át a lekérdezéseit és az illesztőprogram-specifikus beállításokat.

Mindkét illesztőprogram csatlakozik az Azure SQL Database-hez, a Microsoft Fabric SQL-adatbázisához, az Azure SQL Managed Instance-hez, valamint a SQL Server összes támogatott verziójához és kiadásához, beleértve az Express kiadásokat is. Mindkét meghajtó elfogadja a PHP streameket bemeneti paraméterként. Az SQLSRV támogatja a nagy bináris és karakterértékek streamként történő lekérését. Ne feltételezd, hogy PDO_SQLSRV ugyanazt a kimeneti streaming viselkedést mutatná.

Válassza ki a kiindulási pontot

Azure SQL üzemi alapkonfigurációja

Ez a PDO_SQLSRV példa a szervert és az adatbázist a környezeti változókból olvassa, és egy menedzselt identitással csatlakozik. Adatforrásnevet (DSN) épít, és engedélyezi a Transport Layer Securityt (TLS) tanúsítvány-ellenőrzéssel. Ezeket az értékeket az alkalmazás konfigurációjából olvassa ki, nem webes kérelmek paramétereiből. Futtassa a programot egy hoszton, amelynek menedzseltidentitás-végpontja van, miután hozzáférést adott az identitásnak az adatbázishoz.

A segédfunkciók legfeljebb három próbálkozást tesznek a kapcsolódásra vagy a csak olvasható lekérdezés futtatására, amikor felsorolt hiba jelentkezik. Hosszabb ideig várnak a próbálkozások között, ezt az újrapróbálkozási mintázatot exponenciális visszavonulásnak nevezik. Ha egy lekérdezési hiba új kapcsolatot igényel, a lekérdezéssegítő kivételt dob, amelyet a hívó kód kezel.

Használj támogatott PHP verziót, az PDO_SQLSRV kiterjesztést és Microsoft ODBC Driver 18-at SQL Server eléréséhez. A támogatott hitelesítési értékekről lásd: Kapcsolódás Microsoft Entra-hitelesítéssel. Ne használd újra a lekérdezési segítőt írásokhoz vagy több utasításból álló tranzakciókhoz anélkül, hogy alkalmazásspecifikus újrapróbálási szabályzatot terveznél: a hiba nem mindig mondja meg, hogy az írás véglegesítésre került-e.

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

// This read helper retries only the listed errors on the same connection.
// Other errors propagate; the caller must decide whether to reconnect.
const RETRYABLE_READ_ERROR_CODES = [1205, 1222, 40501, 10928, 10929];

/**
 * 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);
            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');
}

/**
 * Retry the standalone read-only query for errors that allow connection reuse.
 */
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, RETRYABLE_READ_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.');
}
$databaseValue = '{' . str_replace('}', '}}', $database) . '}';

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

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

Használd ezeket a beállításokat Azure SQL Database failover csoportokhoz és Azure SQL Managed Instance-hoz.

  • Driver={ODBC Driver 18 for SQL Server} kifejezetten kiválasztja az ODBC Driver 18-at, nem pedig az illesztőprogram-felfedezésre hagyatkozik. Telepítsd ezt a példa futtatása előtt.

  • Állítsd SQL_DATABASE be a tényleges adatbázis névre. A program megduplázza a záró kapcsos zárójeleket, és a nevet kapcsos zárójelek közé teszi, mielőtt behelyezi a DSN-be. Az escaping megakadályozza, hogy a név speciális karakterei megváltoztassanak, hogyan olvassa a driver a kapcsolati beállításokat.

  • ConnectRetryCount valamint ConnectRetryInterval az ODBC alaplati kapcsolat ellenállóképességének szabályozása. Az utasítás lekérdezési időtúllépése a végrehajtás során korlátozza a helyreállítást. A minta 30 másodperces lekérdezési időkorlátával az ODBC megállhat, mielőtt mind az öt újrakapcsolási kísérletet kimerítené. LoginTimeout=90 A kapcsolat létrehozását szabályozza, nem a helyreállítási keretet. Az alkalmazásszintű segítő újra megpróbálja a kiválasztott szerverhibákat; nem próbálja újra a lekérdezés időtúllépését, és nem játszik vissza részben lehozott eredményeket.

  • Engedélyezd a driver logolást a program error_log() hívásai mellett. PDO_SQLSRV esetén állítsa be pdo_sqlsrv.log_severity értékét a(z) php.ini fájlban, vagy futásidőben a(z) ini_set() használatával. SQLSRV esetén konfiguráld LogSeverity és LogSubsystems .sqlsrv_configure() 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. Használd a PDO konstruktor felhasználónév argumentumát ahelyett, hogy a felhasználóazonosítót a DSN-be ágyaznád. 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.

  • Olvasási skálázáshoz vagy olvasható másodlagos replikához add hozzá a ApplicationIntent=ReadOnly elemet a DSN-hez.

  • Használd az SQL szolgáltatásod által biztosított végpontot, beleértve annak felhőspecifikus domainjét is. Vizsgáld meg a tanúsítvány-név eltéréseket, ahelyett, hogy kikapcsolnád a tanúsítvány validálását. Csak akkor használd HostNameInCertificate, ha ismered az adott végpont várható tanúsítványnevét.

  • Az ODBC tokeneket szerz be menedzselt identitáshoz és szolgáltatási alaphitelesítéshez. A AccessTokenhasználatával az alkalmazásod megszerzi a tokent, és átadja a meghajtónak; Az ODBC nem szerzi meg helyetted. További információ: A Microsoft Entra ID használata az ODBC-illesztővel.

  • Tartsd a kapcsolati információkat a kódodon kívül. Tárold az alkalmazásod konfigurációs rendszerében, és használd az Azure Key Vault-t titkokhoz.

  • Az SQLSRV esetében állítsa be a kapcsolati beállításokat a sqlsrv_connect() elemnek átadott tömbben. Ellenőrizd a false visszatérési értéket, és ellenőrizd a sqlsrv_errors() elemet, mielőtt eldöntöd, hogy újra próbálkozol-e. Állítsuk be az utasítás időtúllépéseit külön a(z) QueryTimeout használatával. Az inaktív kapcsolat helyreállítása ODBC-újracsatlakozást mutat be, nem pedig alkalmazásszintű újrapróbálási hurkot.

  • 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 PHP API: az SQLSRV procedurális funkciókat biztosít. PDO_SQLSRV PDO-t valósít meg. Telepíts egy bővítményt vagy mindkettőt.
  • 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: Menedzselt identitás, szolgáltatási alap és külső hozzáférési tokenek az alapul szolgáló Microsoft ODBC Driver for SQL Server segítségével. A felügyelt identitás jelszó nélküli; a ActiveDirectoryServicePrincipal ügyféltitkot használ.
  • Always Encrypted: Titkosítsd az ügyféloldalon az érzékeny oszlopokat, biztonságos enklávékkal a titkosított adatokon végzett támogatott műveletekhez.
  • Kapcsolat rugalmassága: beépített újrapróbálkozások üresjárati kapcsolatokhoz ConnectRetryCount és ConnectRetryInterval használatával.
  • PHP adatfolyamok: Küldj nagy bináris és karakterértékeket streamparaméterek használatával bármelyik API-val. Használj SQLSRV-t streamelt lekérdezéshez.
  • 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.
Gyorsindítás: Csatlakozz és kérdezz a Microsoft PHP Driverekkel Ellenőrizd a bővítményeket, konfiguráld a kapcsolatot, és futtasd le ugyanazt a paraméterezett lekérdezést SQLSRV-vel vagy PDO_SQLSRV-vel.
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.
Az 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 integrált hitelesítést Windowson vagy Kerberost Linuxon és macOS-en.

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 Találj programozási feladatokat mindkét járművezető számára.
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 Egy utasításcsoportot együtt véglegesíts vagy vond vissza.
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 Állítsd be az CharacterSet SQLSRV opcióját vagy a PDO_SQLSRV PDO::SQLSRV_ATTR_ENCODING attribútumját.
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.

Szolgáltatás igénylése

Funkció kéréséhez nyiss meg egy problémát a Microsoft Drivers for PHP for SQL Server GitHub repozióriumban.

Kapcsolódó tartalom

  • Utolsó frissítés időpontja: