Drivers da Microsoft para PHP para SQL Server

Baixar driver PHP

Os drivers Microsoft para PHP para SQL Server são extensões PHP que você pode usar para ler e gravar dados no Microsoft SQL Mecanismo de Banco de Dados 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 driver:

  • O SQLSRV expõe uma API procedural (sqlsrv_*funções) adaptada para recursos do SQL Server.
  • PDO_SQLSRV implementa a interface PHP Data Objects (PDO ). Você pode manter as chamadas PDO no código do banco de dados existente, mas revise suas consultas e configurações específicas do driver antes de trocar de banco de dados.

Ambos os drivers se conectam ao Banco de Dados SQL do Azure, SQL Database no Microsoft Fabric, Instância Gerenciada de SQL do Azure e todas as versões e edições suportadas do SQL Server, incluindo as edições Express. Ambos os drivers aceitam fluxos PHP como parâmetros de entrada. O SQLSRV suporta a recuperação de grandes valores binários e de caracteres como fluxos. Não presuma PDO_SQLSRV tem o mesmo comportamento de streaming de saída.

Escolha o ponto de partida

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

Este PDO_SQLSRV exemplo lê o servidor e o banco de dados a partir de variáveis de ambiente e conecta-se com uma identidade gerenciada. Ele constrói um nome de fonte de dados (DSN) e habilita a Segurança da Camada de Transporte (TLS) com validação de certificados. Leia esses valores a partir da configuração confiável da aplicação, não dos parâmetros de requisição web. Execute o programa em um host com um endpoint de identidade gerenciada após conceder acesso à identidade ao banco de dados.

As funções auxiliares tentam conectar-se ou executar a consulta somente leitura em até três tentativas quando ocorre um erro listado. Eles esperam mais entre as tentativas, um padrão de retentativa chamado recuo exponencial. Se um erro de consulta exigir uma nova conexão, o assistente de consulta lança a exceção para que o código que chama seja gerenciado.

Use uma versão de PHP suportada, a extensão PDO_SQLSRV e Microsoft ODBC Driver 18 para SQL Server. Para valores de autenticação suportados, veja Connect usando autenticação Microsoft Entra. Não reutilize o auxiliar de consulta para escritas ou transações com múltiplas instruções sem projetar uma política de retentativa específica para cada aplicação: um erro nem sempre indica se uma escrita foi commitada.

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

Use estas configurações para grupos de failover do Banco de Dados SQL do Azure e Instância Gerenciada de SQL do Azure.

  • 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 rodar o exemplo.

  • Defina SQL_DATABASE para o nome real do banco de dados. O programa dobra as chaves de fechamento e envolve o nome em chaves antes de colocá-lo na DSN. Escapar impede que caracteres especiais no nome alterem a forma como o driver lê as configurações de conexão.

  • ConnectRetryCount e ConnectRetryInterval controle da resiliência da conexão ODBC em inatividade. O tempo limite da consulta do comando SQL limita a recuperação durante a execução. Com o tempo 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 conexão, não o orçamento de recuperação. O helper em nível de aplicação tenta novamente após erros selecionados do servidor; ele não tenta novamente um timeout de consulta nem reapresenta resultados parcialmente obtidos.

  • Ative o registro de motoristas junto com as chamadas do error_log() programa. Para PDO_SQLSRV, configure pdo_sqlsrv.log_severity em php.ini ou com ini_set() em tempo de execução. Para SQLSRV, configure LogSeverity e LogSubsystems com sqlsrv_configure(). Para mais informações, veja Atividade de registro.

    ; 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 gerenciada atribuída pelo usuário, passe o ID da identidade como argumento $username do PDO (new PDO($dsn, $identityId, null, $options)). Use o ID do cliente da identidade no Serviço de Aplicativo do Azure ou Instância de Contêiner do Azure; caso contrário, use seu ID do objeto. Os drivers PHP herdam esse comportamento do driver Microsoft ODBC para SQL Server; para mais informações, veja Usando o Microsoft Entra ID com o driver ODBC. Use o argumento de nome de usuário do construtor PDO em vez de incorporar o nome de usuário ao DSN. Passar null como o usuário (como o exemplo faz) seleciona a identidade gerenciada atribuída pelo sistema do host do Azure. Para SQLSRV (procedural), passe UID no array de opções de conexão.

  • Defina MultiSubnetFailover=true ao se conectar a um listener de grupo de failover, listener de grupo de disponibilidade ou ponto de extremidade de instância de cluster de failover. Definir isso melhora o desempenho da conexão para listeners de grupo de disponibilidade de sub-rede única e de várias sub-redes. Para mais informações, veja Suporte para Alta Disponibilidade, recuperação de desastres.

  • Para leitura escalonada ou um secundário legível, adicione ApplicationIntent=ReadOnly à DSN.

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

  • O ODBC adquire tokens para identidade gerenciada e autenticação de principal de serviço. Com AccessToken, seu aplicativo adquire o token e o passa para o driver; O ODBC não o adquire para você. Para obter mais informações, consulte Usar o Microsoft Entra ID com o driver ODBC.

  • Mantenha as informações de conexão fora do seu código. Armazene no sistema de configuração do seu aplicativo e use o Azure Key Vault para segredos.

  • Com SQLSRV, as opções de conexão definidas no array passaram para sqlsrv_connect(). Verifique se há um false retorno e inspecione sqlsrv_errors() antes de decidir se deve tentar novamente. Defina os tempos limite dos statements separadamente com QueryTimeout. A resiliência da conexão ociosa demonstra reconexão ODBC, não um ciclo de retentativa em nível de aplicação.

  • Os auxiliares de repetição leem $e->errorInfo[1] protegido por isset(). PDOException::$errorInfo é declarado como ?array e tem como padrão null, portanto a verificação defensiva recorre a um código do driver 0 e deixa que o prefixo SQLSTATE 08 determine se deve tentar novamente.

Para obter mais informações sobre cada parte dessa configuração, consulte:

Para o catálogo de erros transitórios do SQL do Azure, consulte Solucionar problemas de erros de conexão transitórios.

Características principais

  • Duas APIs PHP: SQLSRV fornece funções procedurais. PDO_SQLSRV implementa PDO. Instale uma das extensões ou as duas.
  • Suporte a plataforma ampla: Roda em Windows, Linux e macOS com versões PHP suportadas.
  • Conexões criptografadas: Conexões criptografadas por TLS via Encrypt=true, com validação de certificado do servidor controlada por TrustServerCertificate.
  • Autenticação Microsoft Entra ID: Identidade gerenciada, principal de serviço e tokens de acesso adquiridos externamente através do driver Microsoft ODBC para SQL Server subjacente. Identidade gerenciada dispensa senha; ActiveDirectoryServicePrincipal usa um segredo do cliente.
  • Always Encrypted: Criptografe colunas sensíveis no cliente, com enclaves seguros para operações suportadas em dados criptografados.
  • Resiliência de conexão: repetições de conexão ociosa integradas com ConnectRetryCount e ConnectRetryInterval.
  • Fluxos PHP: Envie grandes valores binários e de caracteres a partir dos parâmetros do fluxo com qualquer uma das APIs. Use SQLSRV para recuperação por streaming.
  • Amplo suporte a tipos de dados do SQL Server: datetimeoffset, parâmetros com valor de tabela, nvarchar, e Unicode com PDO::SQLSRV_ENCODING_UTF8.

Introdução

Artigo Description
Requisitos do sistema Suportava versões para PHP, sistema operacional e SQL Server.
Matriz de suporte Matriz detalhada de compatibilidade para lançamentos de drivers PHP.
Baixe os drivers da Microsoft para PHP para SQL Server Links de download e artefatos de lançamento.
Tutorial de instalação para Linux e macOS Instale o driver e seus pré-requisitos ODBC no Linux e macOS.
Carregando os drivers Ative as extensões em php.ini.
Início Rápido: Conecte-se e consulte com os drivers Microsoft para PHP Verifique as extensões, configure uma conexão e execute a mesma consulta parametrizada com SQLSRV ou PDO_SQLSRV.
Visão geral do driver PHP SQL O que está no pacote e quando escolher SQLSRV ou PDO_SQLSRV.

Configuração e conexão

Artigo Description
Conectando ao servidor Abra uma conexão para uma instância do SQL Server a partir do PHP.
Opções de conexão Referência completa para palavras-chave de conexão, padrões e como configurá-las.
Conectar-se ao Banco de Dados SQL do Microsoft Azure Conecte uma aplicação PHP ao Banco de Dados SQL do Azure.
Conecte-se em uma porta especificada Aponte uma porta TCP não padrão.
Agrupamento de conexões Reutilize conexões ODBC entre requisições PHP.
Desabilite Múltiplos Conjuntos de Resultados Ativos (MARS) Desative o MARS para compatibilidade.
Suporte ao LocalDB Conecte-se a uma instância do LocalDB do SQL Server.
Suporte para Alta Disponibilidade, recuperação de desastres Ouvintes de grupo de disponibilidade e failover de várias sub-redes.
Resiliência da conexão ociosa Reconexão automática para conexões ociosas quebradas.

Authenticate

Artigo Description
Conectar-se usando a autenticação do Microsoft Entra Fluxos de identidade gerenciada, entidade de serviço, token de acesso e senha.
Conecte-se usando autenticação SQL Server Use um login SQL com nome de usuário e senha.
Conecte-se usando autenticação do Windows Use autenticação integrada no Windows ou Kerberos no Linux e macOS.

Secure

Artigo Description
Considerações de segurança Modelo de ameaça e orientação aprofundada de defesa para aplicações PHP.
Always Encrypted com os drivers PHP Configure a criptografia do lado do cliente para colunas confidenciais.
Always Encrypted com enclaves seguros Habilite operações avançadas em colunas criptografadas com enclaves seguros.

Recuperar e atualizar dados

Artigo Description
Guia de programação Encontre tarefas de programação para ambos os controladores.
Comparando funções de execução Escolha a função de execução certa para sua carga de trabalho.
Execução direta e preparada de instruções (PDO_SQLSRV) Quando usar execução direta versus instruções preparadas.
Recuperação de dados Busque linhas, colunas e valores de streaming.
Atualização dos dados Inserir, atualizar e excluir linhas.
Realizar consultas parametrizadas Vincule parâmetros para proteger contra injeção SQL.
Enviar dados como um fluxo Transmita valores binários e de caracteres grandes para o SQL Server.
Realizar transações Faça commit ou reverta um grupo de instruções juntos.
Uso de parâmetros com valores de tabela Passe um TABLE parâmetro para um procedimento armazenado.
Especifique um tipo de cursor e selecione linhas Escolher cursores somente para frente, estáticos, dinâmicos ou de conjunto de chaves.

Tipos de dados

Artigo Description
Conversão de tipos de dados Como o driver mapeia tipos PHP para tipos SQL Server.
Tipos de dados padrão do SQL Server Tipo padrão de SQL Server para cada valor PHP.
Tipos de dados padrão PHP Tipo padrão de PHP para cada tipo de coluna do SQL Server.
Especificar tipos de dados do SQL Server (SQLSRV) Substituir o tipo do SQL Server ao vincular parâmetros.
Especificar tipos de dados PHP Substituir o tipo do PHP ao buscar dados.
Enviar e recuperar dados UTF-8 Defina a CharacterSet opção do SQLSRV ou o atributo do PDO::SQLSRV_ATTR_ENCODING PDO_SQLSRV.
Enviar e recuperar dados ASCII no Linux e macOS Lidar com viagens de ida e volta ASCII em hosts não Windows.
Formatar decimais e dinheiro (SQLSRV) Formate as colunas decimais e de dinheiro com o driver SQLSRV.
Formatar decimais e valores monetários (PDO_SQLSRV) Formate colunas decimais e monetárias com o driver PDO_SQLSRV.
Configurações de localização fora do sistema Separadores decimais localizados e outras considerações locais.

Erros e diagnóstico

Artigo Description
Tratamento de erros e avisos Tratamento de erros e avisos com ambos os drivers.
Configurar o tratamento de erros e avisos (SQLSRV) Ajuste como o driver SQLSRV reporta erros e avisos.
Gerenciar erros e avisos (SQLSRV) Inspecione os erros retornados pelas funções SQLSRV.
Atividade de registro Habilitar o registro de logs do driver para captura de diagnóstico.

Implantar e operar

Artigo Description
Otimização do desempenho Gerenciamento de conexões, processamento em lote, instruções preparadas, cursores, memória e monitoramento no lado do servidor.
Solução de problemas Diagnosticar problemas comuns de instalação, conexão, consulta, tipo de dado, transação e container.

Conteúdo de referência

Artigo Description
Referência à API do driver SQLSRV Todas sqlsrv_* as funções, parâmetros e valores de retorno.
Referência do driver PDO_SQLSRV Métodos PDO e PDOStatement suportados pelo driver PDO_SQLSRV.
Constantes Constantes expostas pelos drivers, incluindo constantes de tipo e codificação.
Artigo Description
Notas de lançamento Histórico de versões por versão com novos recursos, correções de bugs, mudanças no suporte à plataforma e links para download.
Sobre exemplos de código na documentação Convenções usadas pelos exemplos de código nesta seção.
Exemplos de código para o driver SQL PHP Exemplos de aplicações de ponta a ponta para SQLSRV e PDO_SQLSRV.
Recursos de suporte Comunidade e canais de apoio.

Solicitar um recurso

Para solicitar uma funcionalidade, abra uma questão no Microsoft Drivers for PHP para SQL Server GitHub repositório.

Conteúdo relacionado

  • Última atualização em