Drivers da Microsoft para PHP para SQL Server

Descarregar o driver PHP

Os drivers Microsoft para PHP para SQL Server são extensões PHP que podem usar para ler e escrever dados no Microsoft SQL Database Engine a partir de scripts PHP. As duas extensões usam o mesmo driver Microsoft ODBC para SQL Server, mas oferecem APIs PHP diferentes e opções específicas de drivers:

• O SQLSRV expõe uma API procedural (sqlsrv_*funções) adaptada às funcionalidades do SQL Server.
• PDO_SQLSRV implementa a interface PHP Data Objects (PDO). Podes manter as chamadas PDO no código da base de dados existente, mas rever as suas consultas e definições específicas do controlador antes de mudar de base de dados.

Ambos os drivers ligam-se ao Base de Dados SQL do Azure, à base de dados SQL no Microsoft Fabric, ao Azure SQL Managed Instance e a todas as versões e edições suportadas do SQL Server, incluindo as edições Express. Ambos os drivers aceitam streams PHP como parâmetros de entrada. O SQLSRV suporta a recuperação de grandes valores binários e de caracteres como streams. Não assumas que PDO_SQLSRV tem o mesmo comportamento de streaming de saída.

Escolhe o teu ponto de partida

• Para verificar a sua instalação e executar uma consulta parametrizada usando SQLSRV ou PDO_SQLSRV, comece com Quickstart: Connect e consulte os drivers Microsoft para PHP.
• Para instalar o driver em Linux ou macOS, comece pelo tutorial de Instalação para Linux e macOS e descarregue os drivers da Microsoft para PHP para SQL Server.
• Para se ligar ao SQL do Azure com autenticação sem palavra-passe, comece pelo Connect usando as opções de autenticação Microsoft Entra e Connection.
• Para tornar uma aplicação existente resiliente a falhas transitórias, vá a Resiliência da ligação inativa.
• Para decidir entre SQLSRV e PDO_SQLSRV, consulte Visão Geral dos Microsoft Drivers para PHP para SQL Server e Comparar funções de execução.
• Para diagnosticar um problema de instalação, ligação ou consulta, vá a Resolução de Problemas, Gestão de erros e avisos, e Atividade de registo.
• Para tornar uma aplicação já existente mais rápida, vá a Performance Tuning.

Linha de base de produção para o SQL do Azure

Este PDO_SQLSRV exemplo lê o servidor e a base de dados a partir de variáveis de ambiente e liga-se com uma identidade gerida. Constrói um nome de fonte de dados (DSN) e permite a Segurança da Camada de Transporte (TLS) com validação de certificados. Leia estes valores a partir da configuração de aplicação confiável, não dos parâmetros de pedidos web. Execute o programa num host com um endpoint de identidade gerida após conceder à identidade acesso à base de dados.

As funções auxiliares fazem até três tentativas de ligação ou execução da consulta somente de leitura quando ocorre um erro listado. Esperam mais tempo entre tentativas, um padrão de retentativas chamado recuo exponencial. Se um erro de consulta exigir uma nova ligação, o assistente de consulta lança a exceção para o código de chamada tratar.

Use uma versão PHP suportada, a extensão PDO_SQLSRV e Microsoft ODBC Driver 18 para SQL Server. Para valores de autenticação suportados, consulte Ligar utilizando a autenticação do Microsoft Entra. Não reutilize o helper de consultas para escritas ou transações de múltiplas instruções sem definir uma política de retentativas específica para a aplicação: um erro nem sempre indica se uma escrita foi confirmada.

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

Utilize estas definições para grupos de failover do Base de Dados SQL do Azure e Azure SQL Managed Instance.

• Driver={ODBC Driver 18 for SQL Server} seleciona explicitamente o Driver ODBC 18 em vez de depender da descoberta do driver. Instale-o antes de executar o exemplo.

• Defina SQL_DATABASE como o nome real da base de dados. O programa duplica as chaves de fecho e envolve o nome em chaves antes de o colocar na DSN. O uso de escape impede que caracteres especiais no nome alterem a forma como o driver lê as definições de ligação.

• ConnectRetryCount e ConnectRetryInterval controlam a resiliência da ligação ODBC em inatividade. O timeout da consulta da instrução delimita a recuperação durante a execução. Com o tempo de espera de consulta de 30 segundos da amostra, o ODBC pode parar antes de esgotar todas as cinco tentativas de reconexão. LoginTimeout=90 controla o estabelecimento da ligação e não o orçamento de recuperação. O componente auxiliar ao nível da aplicação repete a operação perante determinados erros do servidor; não tenta novamente um timeout da consulta nem devolve novamente resultados obtidos parcialmente.

• Ative o registo do controlador juntamente com as chamadas do programa error_log(). Para PDO_SQLSRV, definir pdo_sqlsrv.log_severity em php.ini ou com ini_set() durante a execução. Para SQLSRV, configure LogSeverity e LogSubsystems com sqlsrv_configure(). Para mais informações, consulte Atividade de registo.

  ; 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
  

• Para uma identidade gerida atribuída pelo utilizador, passe o ID da identidade como argumento $username do PDO (new PDO($dsn, $identityId, null, $options)). Use o ID de cliente da identidade no Serviço de Aplicações do Azure ou no Azure Container Instance; caso contrário, use o respetivo ID de objeto. Os drivers PHP herdam este comportamento do driver subjacente Microsoft ODBC para SQL Server; para mais informações, consulte Usar o Microsoft Entra ID com o driver ODBC. Use o argumento de nome de utilizador do construtor PDO em vez de incorporar a identidade no DSN. Ao passar null como utilizador (como no exemplo), seleciona-se a identidade gerida atribuída pelo sistema ao anfitrião do Azure. Para SQLSRV (processual), passe UID no array de opções de ligação.

• Define MultiSubnetFailover=true quando te ligas a um ouvinte de grupo de failover, ouvinte de grupo de disponibilidade ou endpoint de instância de cluster de failover. Defini-la melhora o desempenho da ligação tanto para ouvintes de grupos de disponibilidade de sub-rede única como de várias sub-redes. Para mais informações, consulte Suporte para Alta Disponibilidade, recuperação de desastres.

• Para expansão de leitura ou um secundário legível, adicione ApplicationIntent=ReadOnly à DSN.

• Use o endpoint fornecido pelo seu serviço SQL, incluindo o seu domínio específico da cloud. Investigue incompatibilidades de nome do certificado em vez de desativar a validação de certificados. Use HostNameInCertificate apenas quando souber o nome esperado do certificado para esse endpoint.

• O ODBC adquire tokens para identidade gerida e autenticação de entidade de serviço. Com AccessToken, a sua aplicação adquire o token e passa-o para o driver; O ODBC não o adquire por si. Para obter mais informações, consulte Usando Microsoft Entra ID com o Driver ODBC.

• Mantém a informação de ligação fora do teu código. Guarde-o no sistema de configuração da sua aplicação e use o Azure Key Vault para segredos.

• Com SQLSRV, defina as opções de ligação no array passado para sqlsrv_connect(). Verifique se há um false retorno e inspecione sqlsrv_errors() antes de decidir se deve tentar novamente. Defina os tempos de espera das instruções SQL separadamente com QueryTimeout. A resiliência da ligação inativa demonstra reconexão ODBC, não um ciclo de retentativas ao nível da aplicação.

• As funções auxiliares de repetição leem $e->errorInfo[1] protegidas por isset(). PDOException::$errorInfo é declarado como ?array e tem como valor predefinido null, pelo que a verificação defensiva recorre a um código de controlador 0 e deixa que o prefixo SQLSTATE 08 determine se deve tentar novamente.

Para mais informações sobre cada parte desta configuração, veja:

• Opções de ligação
• Conectar usando a autenticação do Microsoft Entra
• Resiliência da ligação ociosa
• Connecting to Microsoft Base de Dados SQL do Azure
• Suporte para Alta Disponibilidade, recuperação de desastres

Para o catálogo de erros transientes do SQL do Azure, veja Solucionar erros de ligação transitória.

Principais características

• Duas APIs PHP: SQLSRV fornece funções procedurais. PDO_SQLSRV implementa PDO. Instala uma das extensões ou ambas.
• Suporte a plataforma ampla: Funciona em Windows, Linux e macOS com versões PHP suportadas.
• Ligações encriptadas: Ligações encriptadas por TLS via Encrypt=true, com validação de certificados do servidor controlada por TrustServerCertificate.
• Autenticação Microsoft Entra ID: Identidade gerida, principal de serviço e tokens de acesso adquiridos externamente através do driver Microsoft ODBC subjacente para SQL Server. A identidade gerida não requer palavra-passe; ActiveDirectoryServicePrincipal utiliza um segredo do cliente.
• Always Encrypted: Encripte colunas sensíveis no cliente, com enclaves seguros para operações suportadas em dados encriptados.
• Resiliência da conexão: novas tentativas incorporadas para conexões inativas com ConnectRetryCount e ConnectRetryInterval.
• Fluxos PHP: Envie valores binários e de caracteres grandes a partir dos parâmetros do fluxo com qualquer uma das APIs. Utilize SQLSRV para recuperação em streaming.
• Suporte abrangente para tipos de dados do SQL Server: datetimeoffset, parâmetros com valor de tabela, nvarchar, e Unicode com PDO::SQLSRV_ENCODING_UTF8.

Introdução

Configurar e ligar

Authenticate

Secure

Recuperar e atualizar dados

Tipos de dados

Erros e diagnósticos

Implantar e operar

Conteúdo de referência

Tarefas relacionadas

Pedir uma funcionalidade

Para solicitar uma funcionalidade, abra um issue no repositório do GitHub Microsoft Drivers for PHP for SQL Server.

Conteúdo relacionado

• Controladores da Microsoft para o PHP para o SQL Server no GitHub
• Microsoft ODBC Driver para SQL Server
• Controladores e frameworks SQL da Microsoft