Visão geral dos Microsoft Drivers para PHP para SQL Server

Baixar driver do PHP

Os Microsoft drivers para PHP para SQL Server incluem duas extensões PHP, SQLSRV e PDO_SQLSRV. PDO_SQLSRV implementa a interface PHP Data Objects (PDO). Ambas as extensões utilizam o Microsoft ODBC Driver for SQL Server para conectar ao Microsoft SQL. Suas APIs PHP, opções específicas de driver e tipos padrão de PHP diferem. Por exemplo, SQLSRV retorna valores de data e hora como DateTime objetos por padrão, enquanto PDO_SQLSRV retorna strings por padrão. Para requisitos de sistema, veja Requisitos de Sistema para os drivers Microsoft para PHP para SQL Server.

Escolha SQLSRV ou PDO_SQLSRV

Se você... Usar
Está começando um novo projeto sem código PDO em outro local Escolha a interface que sua aplicação usará de forma consistente. SQLSRV expõe funções procedurais e descritores de parâmetros explícitos. PDO_SQLSRV se adapta a código organizado em torno de PDO e PDOStatement objetos.
Já uso PDO com outro banco de dados (MySQL, PostgreSQL, SQLite) PDO_SQLSRV, assim sua camada de acesso a dados permanece consistente entre bancos de dados.
Use uma framework ou biblioteca que espere um objeto de conexão PDO PDO_SQLSRV.
Preciso de controle manual, bloco por bloco, sobre quando dados do fluxo são enviados SQLSRV, usando sqlsrv_send_stream_data(). PDO_SQLSRV também transmite valores grandes, vinculando um recurso de fluxo PHP com PDO::PARAM_LOB, mas envia todo o fluxo automaticamente durante execute(), em vez de em blocos controlados pelo chamador.
Manter uma aplicação que já chama sqlsrv_* funções SQLSRV, a menos que você planeje reescrever o código de acesso a dados para PDO.

Instale uma das extensões ou as duas. Downloads para Windows contêm binários de extensão separados; no Linux e macOS, instale os pacotes sqlsrv e pdo_sqlsrv separadamente. Você pode carregar os dois no mesmo processo PHP. SQLSRV retorna recursos de conexão e recursos de instrução; PDO_SQLSRV retorna objetos PDO e PDOStatement. Não passe um recurso de uma API para outra.

Usar PDO não torna a sintaxe Transact-SQL (T-SQL) portátil para outro banco de dados. O PDO oferece uma interface PHP comum; suas consultas, esquema, autenticação e atributos específicos do driver ainda podem depender do Microsoft SQL. Da mesma forma, usar a extensão procedural não exige organização procedural em toda a sua aplicação: você pode chamar SQLSRV a partir das suas próprias classes.

Compare o mesmo resultado em ambas as APIs

Execute esses programas antes de escolher a representação PHP que sua aplicação espera. Eles selecionam o mesmo inteiro, data e SQL NULL, mas os valores padrão não são idênticos. Não são necessárias tabelas ou bancos de dados de exemplo.

Instale e carregue a extensão selecionada. Defina SQL_SERVER, SQL_DATABASE, SQL_USER e SQL_PASSWORD no ambiente do processo para um banco de dados de teste SQL Server existente. O certificado do servidor deve ser confiável e corresponder ao endpoint configurado. Para configuração e alternativas ao Azure sem senha, veja Conectando-se ao servidor.

SQLSRV

Salve este programa completo como compare-sqlsrv.php, e execute php compare-sqlsrv.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]) . '}';
}
$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 {
    $stmt = sqlsrv_query($conn, "SELECT CAST(42 AS int) AS CountValue, "
        . "CAST('2026-10-19' AS date) AS DayValue, CAST(NULL AS int) AS Missing");
    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 (!is_array($row) || $row['CountValue'] !== 42
        || !($row['DayValue'] instanceof DateTime)
        || $row['DayValue']->format('Y-m-d') !== '2026-10-19'
        || $row['Missing'] !== null) {
        throw new RuntimeException('Unexpected SQLSRV values or default types.');
    }
    echo get_debug_type($row['CountValue']), ', ',
        get_debug_type($row['DayValue']), ', ', get_debug_type($row['Missing']), PHP_EOL;
} finally {
    if (is_resource($stmt)) {
        sqlsrv_free_stmt($stmt);
    }
    sqlsrv_close($conn);
}

Resultado esperado:

int, DateTime, null

PDO_SQLSRV

Salve esse programa separado como compare-pdo.php, e execute php compare-pdo.php. Ele intencionalmente deixa a obtenção de valores numéricos e de datas nos padrões PDO_SQLSRV.

<?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::SQLSRV_ATTR_ENCODING => PDO::SQLSRV_ENCODING_UTF8,
    ]
);
$stmt = null;
try {
    $stmt = $pdo->query("SELECT CAST(42 AS int) AS CountValue, "
        . "CAST('2026-10-19' AS date) AS DayValue, CAST(NULL AS int) AS Missing");
    $row = $stmt->fetch(PDO::FETCH_ASSOC);
    if ($row !== ['CountValue' => '42', 'DayValue' => '2026-10-19', 'Missing' => null]) {
        throw new RuntimeException('Unexpected PDO_SQLSRV values or default types.');
    }
    echo get_debug_type($row['CountValue']), ', ',
        get_debug_type($row['DayValue']), ', ', get_debug_type($row['Missing']), PHP_EOL;
} finally {
    $stmt = null;
    $pdo = null;
}

Resultado esperado:

string, string, null

Ambos os programas solicitam explicitamente chaves de resultado nomeadas. Esses arrays PHP usam nomes de colunas como CountValue, em vez de índices numéricos baseados em zero. Um SQL NULL se torna PHP null em qualquer uma das APIs. Não é a sequência vazia ou uma linha de resultados faltando.

Ambos os programas leem o nome real do banco de dados, nome de usuário e senha do ambiente. Eles escapam desses valores uma vez para o tratamento de conexão no estilo ODBC do driver PHP. Dobrar chaves de fechamento e incluir o valor entre chaves preserva caracteres especiais; não renomeia o banco de dados nem altera a senha armazenada. Para mais informações, veja Conectando ao servidor.

Os exemplos interrompem em caso de erro e liberam recursos em finally. O SQLSRV reporta falhas de banco de dados através de false e sqlsrv_errors(); PDO_SQLSRV lança exceções em caso de falhas de conexão e usa exceções para falhas de consulta com o modo de erro configurado. Em uma aplicação web, capture essas exceções no código que lida com a solicitação. Registre detalhes de diagnóstico em logs protegidos em vez de devolvê-los ao navegador.

Depois do exercício, exclua compare-sqlsrv.php e compare-pdo.php se não precisar mais. Elimine as variáveis do ambiente de credenciais do processo de teste quando terminar.

Escolha tipos, codificação e tratamento de erros

Decida quais tipos de PHP sua aplicação espera, como ela lida com texto e erros, e quando libera recursos do banco de dados.

Decisão SQLSRV PDO_SQLSRV Efeito no código da aplicação
Tipos de resultados inteiros Inteiros nativos PHP para colunas SQL int. Cadeias de caracteres por padrão; PDO::SQLSRV_ATTR_FETCHES_NUMERIC_TYPE solicitações dão suporte a tipos numéricos de PHP. Comparações rigorosas e saídas serializadas podem variar. Não presuma que todo tipo numérico SQL se encaixa em um inteiro ou float em PHP.
Resultados de data e hora DateTime objetos por padrão; ReturnDatesAsStrings seleciona strings. Strings por padrão; PDO::SQLSRV_ATTR_FETCHES_DATETIME_TYPE seleciona objetos. Normalize a representação antes de serializar ou passar para o código da aplicação.
Codificação de caracteres Defina CharacterSet => 'UTF-8' explicitamente. UTF-8 é o padrão; configure-o com PDO::SQLSRV_ATTR_ENCODING. Não transfira a opção SQLSRV para a string DSN do PDO.
Tratamento de erros Verifique false e capture imediatamente toda a coleção de erros do SQLSRV. Configurar PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION. Uma linha faltando e uma consulta falhada precisam de tratamento diferente.
Reutilização de parâmetros Vincule variáveis por referência em descritores sqlsrv_prepare(). Use bindParam() para uma variável ou bindValue() para o valor atual. Reatribuir a variável afeta uma ligação de referência, não uma vinculação de valor anterior.
Cleanup Libere instruções e, depois, feche o recurso de conexão. Libere referências à instrução, depois, o objeto PDO. Uma instrução pode manter uma conexão PDO ativa após outra referência ser definida para null.

Se você migrar uma aplicação existente, teste esses comportamentos com valores representativos antes de alterar o código do banco de dados. Inclua texto não ASCII, SQL NULL, datas, valores decimais exatos e parâmetros de saída de procedimentos armazenados. Também compare como seu framework configura atributos PDO. Substituir nomes de funções sozinho não migra o tratamento de erros, o binding de referências ou os tipos PHP retornados.

Para um fluxo de trabalho de gravação e leitura exemplificado com ambas as APIs, use o guia de programação. Para execuções repetidas e entradas digitadas, use Comparar funções de execução de consulta.

Saiba o que cada componente faz

Sua escolha de extensão altera a API PHP e suas conversões de tipos. Ambas as extensões usam ODBC para se comunicar com o servidor, criptografar conexões e se autenticar. O sistema operacional fornece certificados confiáveis e serviços, como autenticação do Windows ou Kerberos. O destino SQL controla permissões, esquema e instruções T-SQL suportadas.

Os programas de comparação usam autenticação SQL para SQL Server. Para Banco de Dados SQL do Azure, Instância Gerenciada de SQL do Azure, Azure Synapse Analytics, banco de dados SQL no Fabric ou Warehouse no Fabric, configure o endpoint de serviço e a autenticação suportada antes de reutilizar o padrão de busca. Ambos os produtos Fabric exigem autenticação do Microsoft Entra ID; O Warehouse também exige desabilitar múltiplos conjuntos de resultados ativos (MARS). Uma comparação de tipos bem-sucedida no SQL Server não estabelece que um alvo diferente suporta todos os recursos listados nesta visão geral.

O que ambas as extensões oferecem

  • Autenticação integrada, autenticação SQL e autenticação do Microsoft Entra ID, dependendo do suporte do destino. Identidade gerenciada não usa uma senha de aplicativo; ActiveDirectoryServicePrincipal usa um ID de cliente e um segredo do cliente. Para mais informações, veja Conectando ao servidor.
  • Consultas parametrizadas, instruções preparadas e parâmetros direcionais (entrada/saída). Para mais informações, veja Comparando funções de execução e Usando parâmetros direcionais.
  • Transações, parâmetros de entrada de fluxo para valores grandes de caracteres e binários, e parâmetros com valor de tabela.
  • Always Encrypted, incluindo enclaves seguros onde há suporte do driver ODBC e do destino do SQL Server. Para mais informações, veja Usando Always Encrypted com os drivers da Microsoft para PHP para SQL Server.
  • Conexões com SQL Server, Banco de Dados SQL do Azure, Instância Gerenciada de SQL do Azure, Azure Synapse Analytics, banco de dados SQL no Microsoft Fabric e Warehouse no Microsoft Fabric. As funcionalidades de autenticação e SQL variam conforme o destino; veja conexões Azure e Fabric.

Conteúdo relacionado

  • Última atualização em