Visão geral dos drivers da Microsoft para PHP para SQL Server

Baixar driver 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 se ligar ao Microsoft SQL. As suas APIs PHP, opções específicas de drivers e tipos de PHP predefinidos diferem. Por exemplo, o SQLSRV devolve valores de data e hora como DateTime objetos por defeito, enquanto PDO_SQLSRV devolve strings por defeito. Para requisitos de sistema, consulte Requisitos de sistema para os drivers Microsoft para PHP para SQL Server.

Escolha SQLSRV ou PDO_SQLSRV

Se você... Use
Está a começar um novo projeto sem código PDO noutro sítio Escolha a interface que a sua aplicação irá usar de forma consistente. O SQLSRV expõe funções procedurais e descritores de parâmetros explícitos. PDO_SQLSRV adequa-se a código organizado em torno de objetos PDO e PDOStatement.
Já uso PDO com outra base de dados (MySQL, PostgreSQL, SQLite) PDO_SQLSRV, assim a camada de acesso a dados mantém-se consistente entre bases de dados.
Use uma framework ou biblioteca que espere um objeto de ligação PDO PDO_SQLSRV.
Necessidade de controlo manual, bloco a bloco, sobre quando os dados do fluxo são enviados SQLSRV, usando sqlsrv_send_stream_data(). PDO_SQLSRV também transmite valores grandes, ao ligar um recurso de stream PHP com PDO::PARAM_LOB, mas envia todo o fluxo automaticamente durante execute() em vez de em chunks controlados pelo chamador.
Manter uma aplicação que já chama sqlsrv_* funções SQLSRV, a menos que planeie reescrever o código de acesso aos dados para PDO.

Instala uma extensão ou ambas. Os downloads do Windows contêm binários de extensão separados; no Linux e macOS, instalem os pacotes sqlsrv e pdo_sqlsrv separadamente. Podes carregar ambos no mesmo processo PHP. SQLSRV retorna recursos de ligação e de instruções; 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 outra base de dados. O PDO oferece-lhe uma interface PHP comum; as 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 requer organização procedural em toda a sua aplicação: pode chamar SQLSRV a partir das suas próprias classes.

Compare o mesmo resultado em ambas as APIs

Execute estes programas antes de escolher a representação PHP que a sua aplicação espera. Selecionam o mesmo inteiro, data e SQL NULL, mas as predefinições não são idênticas. Não são necessárias tabelas nem bases 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 uma base de dados de teste SQL Server existente. O certificado do servidor deve ser confiável e corresponder ao endpoint configurado. Para alternativas de configuração e alternativas do Azure sem palavra-passe, veja Ligação ao servidor.

SQLSRV

Guarde 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);
}

Produção esperada:

int, DateTime, null

PDO_SQLSRV

Guarde este programa separado como compare-pdo.php, e execute php compare-pdo.php. Deixa deliberadamente a busca numérica e de data nos valores predefinidos do 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;
}

Produção esperada:

string, string, null

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

Ambos os programas leem o nome real da base de dados, nome de utilizador e palavra-passe das variáveis de ambiente. Escapam estes valores uma vez para a gestão de ligação ao estilo ODBC do driver PHP. Duplicar chavetas de encerramento e incluir o valor entre chavetas preserva caracteres especiais; não renomeia a base de dados nem altera a palavra-passe armazenada. Para mais informações, consulte Ligação ao servidor.

Os exemplos param quando ocorrem erros e libertam recursos em finally. O SQLSRV reporta falhas de base de dados através de false e sqlsrv_errors(); PDO_SQLSRV lança exceções em caso de falhas de ligação e utiliza exceções para falhas de consulta com o modo de erro configurado. Numa aplicação web, capture estas exceções no código que gere o pedido. Regista os dados de diagnóstico em registos protegidos em vez de os devolver a um navegador.

Depois do exercício, apaga compare-sqlsrv.php e compare-pdo.php se já não precisares deles. Elimina as variáveis do ambiente das credenciais do processo de teste quando terminares.

Escolha tipos, codificação e gestão de erros

Decida que tipos de PHP a sua aplicação espera, como lida com texto e erros, e quando liberta recursos da base de dados.

Decisão SQLSRV PDO_SQLSRV Efeito no código da aplicação
Tipos de resultado inteiros Inteiros PHP nativos para colunas SQL int. Strings por predefinição; PDO::SQLSRV_ATTR_FETCHES_NUMERIC_TYPE pedidos suportam tipos numéricos PHP. Comparações rigorosas e saída serializada podem diferir. Não assumas que todos os tipos numéricos SQL encaixam num inteiro PHP ou float.
Resultados de data e hora DateTime objetos por defeito; ReturnDatesAsStrings seleciona strings. Cadeias por defeito; 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 transfiras a opção SQLSRV para um DSN PDO.
Tratamento de erros Verifique false e capture imediatamente a coleção completa de erros do SQLSRV. Configurar PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION. Uma linha em falta e uma consulta falhada precisam de tratamento diferente.
Reutilização de parâmetros Associe variáveis por referência em descritores sqlsrv_prepare(). Utilize bindParam() para uma variável ou bindValue() para o seu valor atual. Reatribuir a variável afeta uma ligação de referência, não uma ligação de valor anterior.
Cleanup Liberte as instruções, depois feche o recurso da ligação. Referências da instrução release, depois ao objeto PDO. Uma instrução pode manter uma ligação PDO ativa após outra referência ser definida para null.

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

Para um exemplo prático de um fluxo de trabalho de escrita e leitura 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 consultas.

Sabe o que cada componente faz

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

Os programas de comparação usam autenticação SQL para o SQL Server. Para Base de Dados SQL do Azure, Azure SQL Managed Instance, Azure Synapse Analytics, base 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 requerem autenticação do Microsoft Entra ID; O Warehouse também exige desativar múltiplos conjuntos de resultados ativos (MARS). Uma comparação entre tipos bem-sucedida no SQL Server não estabelece que um destino diferente suporta todas as funcionalidades listadas nesta visão geral.

O que ambas as extensões fornecem

  • Autenticação integrada, autenticação SQL e autenticação do Microsoft Entra ID, consoante o suporte do destino. A identidade gerida não usa uma palavra-passe de aplicação; ActiveDirectoryServicePrincipal usa um ID de cliente e um segredo do cliente. Para mais informações, consulte Ligação ao servidor.
  • Consultas parametrizadas, instruções preparadas e parâmetros direcionais (entrada/saída). Para mais informações, consulte Comparar funções de execução e Usar parâmetros direcionais.
  • Transações, parâmetros de entrada de fluxo contínuo para valores grandes de caracteres e binários, e parâmetros com valor de tabela.
  • Always Encrypted, incluindo enclaves seguros onde o driver ODBC e o destino SQL Server os suportam. Para mais informações, consulte Using Always Encrypted with the Microsoft Drivers for PHP for SQL Server.
  • Ligações ao SQL Server, Base de Dados SQL do Azure, Azure SQL Managed Instance, Azure Synapse Analytics, base de dados SQL no Microsoft Fabric e Warehouse no Microsoft Fabric. As funcionalidades de autenticação e SQL variam consoante o destino; ver ligações Azure e Fabric.

Conteúdo relacionado

  • Última atualização a