Requisitos do sistema para os Drivers da Microsoft para PHP para SQL Server

Baixar driver PHP

Este artigo lista os componentes que você deve instalar no seu sistema para acessar os dados em SQL Server ou Banco de Dados SQL do Azure usando o SQLSRV ou PDO_SQLSRV driver.

Para mais informações sobre os ciclos de vida de suporte e os requisitos dos drivers PHP, consulte a matriz de suporte. Os drivers SQLSRV e PDO_SQLSRV em cada versão têm os mesmos requisitos de PHP, sistema operacional, arquitetura, segurança de threads e ODBC.

Como a pilha de drivers se encaixa

Um aplicativo PHP não se conecta diretamente ao servidor de banco de dados. Cada camada deve ser compatível com a camada adjacente:

Camada O que você seleciona ou configura Como é uma incompatibilidade
Application Funções SQLSRV ou classes e atributos PDO_SQLSRV Funções indefinidas, driver PDO indisponível ou erros em nível de aplicação
Extensão PHP SQLSRV e arquivos PDO_SQLSRV construídos para a versão secundária do PHP, arquitetura e modo de segurança de threads Aviso de inicialização do PHP, falha no carregamento do módulo ou travamento do processo
runtime do PHP configuração da interface de linha de comando (CLI), do módulo Apache, do PHP-FPM ou do IIS FastCGI A CLI carrega os drivers, mas a aplicação web não os carrega
Driver ODBC do Microsoft Uma versão suportada pela versão selecionada do driver PHP Falhas de conexão ou uma biblioteca ODBC ausente
Sistema operacional Um lançamento e arquitetura suportados com pacotes de execução e compilação necessários Nenhum pacote compatível, biblioteca compartilhada não resolvida ou falha na compilação do código-fonte
Produto de banco de dados Um destino SQL Server ou SQL do Azure compatível Erros específicos de versão do servidor ou de funcionalidades após o estabelecimento de uma conexão

SQLSRV e PDO_SQLSRV fornecem diferentes APIs PHP sobre o mesmo driver ODBC. Instale ambos quando seu aplicativo usar as duas APIs. Instalar uma extensão não instala ou habilita automaticamente a outra.

API Modelo de programação Verificação específica para instalação
SQLSRV Funções procedurais sqlsrv_* e constantes SQLSRV extension_loaded('sqlsrv') e function_exists('sqlsrv_connect')
PDO_SQLSRV Classes, atributos e exceções de PHP Data Objects (PDO) extension_loaded('pdo_sqlsrv') e sqlsrv em PDO::getAvailableDrivers()

As extensões podem ser instaladas de forma independente. PDO_SQLSRV também exige que o PDO carregue antes de PDO_SQLSRV.

Escolha um conjunto compatível

Antes de baixar ou construir um driver, complete estas verificações:

  1. Identifique cada runtime PHP que atende à aplicação. Uma tarefa agendada, um worker de linha de comando, um site IIS, um módulo Apache e um pool PHP-FPM podem usar executáveis e arquivos de configuração do PHP diferentes.

  2. Execute o seguinte comando com cada executável PHP:

    php -i | findstr /I "PHP Version Architecture Thread Safety extension_dir"

    No Linux ou macOS, use:

    php -i | grep -E "PHP Version|Thread Safety|extension_dir"
file "$(php -r 'echo PHP_BINARY;')"

    O file comando reporta a arquitetura do executável. Se ele reportar um executável universal do macOS, selecione explicitamente a arquitetura pretendida, como arch -arm64 php --version ou arch -x86_64 php --version. Use a mesma seleção de arquitetura ao construir, carregar e testar as extensões.

  3. Selecione uma versão de driver PHP que suporte a versão secundária do PHP, sistema operacional e destino do banco de dados.

  4. Selecione uma versão do Driver ODBC da Microsoft com suporte na tabela de compatibilidade deste artigo.

  5. Faça corresponder o arquivo de extensão ou a compilação PIE à arquitetura do PHP e ao modo de segurança de threads. Não copie uma extensão de outra instalação PHP a menos que todos esses valores coincidam.

  6. Configure e verifique separadamente a CLI e os runtimes do servidor web. Um comando bem-sucedido php -m prova apenas que o runtime CLI carregou a extensão.

PHP

Baixe binários PHP no site do PHP. Escolha uma versão PHP listada no suporte a versões PHP.

Segurança de thread e arquitetura

O arquivo de build e extensão do PHP devem concordar em ambos os valores.

Valor PHP Seleção obrigatória do driver
Thread Safety => enabled Arquivo de driver thread-safe (ts ou TS)
Thread Safety => disabled Arquivo de driver não seguro para threads (nts ou NTS)
Architecture => x64 Arquivo de driver de 64 bits e componentes ODBC de 64 bits
Architecture => x86 Arquivo de driver Windows de 32 bits e componentes ODBC de 32 bits

A CLI pode usar uma build PHP thread-safe ou não thread-safe. Selecione a extensão pelo valor reportado, não assumindo que toda build de CLI não é thread-safe.

driver ODBC

Instale um driver Microsoft ODBC suportado para SQL Server no computador que roda PHP. Baixe o driver de Download ODBC Driver for SQL Server.

Caso esteja baixando a versão Windows do driver em uma versão de 64 bits do Windows, o instalador de ODBC de 64 bits instalará os drivers de 32 bits e de 64 bits. Caso tenha uma versão de 32 bits do Windows, use o instalador ODBC x86. Em plataformas não Windows, somente as versões de 64 bits do driver estão disponíveis.

A tabela inclui combinações históricas para planejamento de atualização. Use a versão atual do driver PHP e suas versões ODBC listadas para uma nova instalação. A compatibilidade com uma versão mais antiga não estende seu ciclo de vida de suporte. Verifique tanto o ciclo de vida do suporte ao driver PHP quanto as versões suportadas pelo PHP.

Uma célula em branco não significa que o driver PHP necessariamente rejeita essa versão ODBC. Recursos individuais podem exigir versões ODBC mais recentes do que a combinação base.

Versão do driver PHP →
↓ Versão do driver ODBC		 5.13 5.12 5.11 5.10 5.9 5.8 5.6 5,3 5.2 4.3 4,0 3.2
Driver ODBC 18 Yes Yes Yes Yes
Driver ODBC 17 Yes Yes Yes Yes Yes Yes Yes Yes Yes
Driver ODBC 13.1 Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
Driver ODBC 13 Yes
Driver ODBC 11 Yes Yes Yes Yes Yes Yes Yes

Caso esteja usando o driver SQLSRV, o sqlsrv_client_info retornará informações sobre qual versão do SQL Server no Microsoft ODBC Driver for SQL Server está sendo usada pelo Drivers da Microsoft para PHP para SQL Server. Se você estiver usando o driver PDO_SQLSRV, você pode usar PDO::getAttribute para descobrir a versão.

SQL Server

Para versões suportadas do SQL Server, veja Versões suportadas do banco de dados.

Avalie o suporte ao destino separadamente para 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. Requisitos de instalação são requisitos do lado do cliente e não estabelecem que todo método de autenticação, opção de conexão, recurso do Transact-SQL (T-SQL) ou tipo de dado está disponível em todos os destinos. Use a matriz de suporte e a documentação do produto alvo para o cenário que sua aplicação utiliza.

Sistemas operacionais

Para sistemas operacionais suportados, veja Sistemas operacionais suportados.

Versões do driver

Cada versão dos Microsoft drivers para PHP para SQL Server disponibiliza SQLSRV e arquivos de drivers PDO_SQLSRV em variantes thread-safe e não thread-safe. No Windows, cada variante também é construída para PHP de 32 e 64 bits. Selecione o arquivo do driver compatível com sua versão do PHP, o modo de segurança de thread e a arquitetura. Para habilitar um arquivo de driver após baixá-lo, veja Carregando os Drivers da Microsoft para PHP para SQL Server.

No Linux e macOS, instale os drivers com o PIE, o PHP Installer for Extensions, conforme descrito nas instruções de instalação do Linux e macOS. O PIE substitui o sistema obsoleto de pacotes PHP Extension Community Library (PECL) e nomeia a extensão instalada como sqlsrv.so ou pdo_sqlsrv.so. As tabelas a seguir listam os nomes dos arquivos dos pacotes binários pré-construídos que você baixa manualmente da página de lançamentos do Microsoft Drivers for PHP for SQL Server.

As tabelas a seguir listam os arquivos nos pacotes de lançamento 5.13. Nos nomes dos arquivos, ts e TS significam thread-safe, e nts e NTS significam não-thread-safe.

Arquivos de drivers do Windows

O Windows_5.13.xRTW.zip pacote contém esses arquivos.

arquivo SQLSRV arquivo PDO_SQLSRV Versão do PHP Thread-safe? Architecture
php_sqlsrv_83_nts_x86.dll php_pdo_sqlsrv_83_nts_x86.dll 8.3 não 32-bit
php_sqlsrv_83_ts_x86.dll php_pdo_sqlsrv_83_ts_x86.dll 8.3 sim 32-bit
php_sqlsrv_83_nts_x64.dll php_pdo_sqlsrv_83_nts_x64.dll 8.3 não 64-bit
php_sqlsrv_83_ts_x64.dll php_pdo_sqlsrv_83_ts_x64.dll 8.3 sim 64-bit
php_sqlsrv_84_nts_x86.dll php_pdo_sqlsrv_84_nts_x86.dll 8.4 não 32-bit
php_sqlsrv_84_ts_x86.dll php_pdo_sqlsrv_84_ts_x86.dll 8.4 sim 32-bit
php_sqlsrv_84_nts_x64.dll php_pdo_sqlsrv_84_nts_x64.dll 8.4 não 64-bit
php_sqlsrv_84_ts_x64.dll php_pdo_sqlsrv_84_ts_x64.dll 8.4 sim 64-bit
php_sqlsrv_85_nts_x86.dll php_pdo_sqlsrv_85_nts_x86.dll 8.5 não 32-bit
php_sqlsrv_85_ts_x86.dll php_pdo_sqlsrv_85_ts_x86.dll 8.5 sim 32-bit
php_sqlsrv_85_nts_x64.dll php_pdo_sqlsrv_85_nts_x64.dll 8.5 não 64-bit
php_sqlsrv_85_ts_x64.dll php_pdo_sqlsrv_85_ts_x64.dll 8.5 sim 64-bit

Use um arquivo de driver não thread-safe com uma build PHP não thread-safe, e um arquivo driver thread-safe com uma build thread-safe em PHP. A interface de linha de comando (CLI) pode usar qualquer uma das duas compilações. Para confirmar qual build você tem, execute php -i e verifique o valor Segurança de thread.

Arquivos de drivers para Linux e macOS

Os pacotes Linux_5.13.xRTW.tar.gz e Mac_5.13.xRTW.tar.gz contêm esses arquivos. O arquivo Linux contém binários x64, e o arquivo do macOS contém binários Arm64.

Arquivos pré-compilados também devem corresponder às bibliotecas nativas do seu sistema operacional. Os binários do Linux 5.13.3 requerem glibc 2.38 ou versões posteriores e um runtime em C++ que fornece GLIBCXX_3.4.32. Os binários do macOS 5.13.3 declaram o macOS 26 como seu alvo mínimo de implantação. Esses requisitos binários são separados do suporte ao sistema operacional para builds de código-fonte.

Use o PIE quando a arquitetura do arquivo ou os requisitos da biblioteca nativa não corresponderem à sua instalação em PHP. Compilações PIE para o PHP instalado e bibliotecas nativas. Não substitua bibliotecas do sistema manualmente para carregar uma extensão pré-construída.

arquivo SQLSRV arquivo PDO_SQLSRV Versão do PHP Thread-safe?
SQLSRV_8.3_NTS.so PDO_SQLSRV_8.3_NTS.so 8.3 não
SQLSRV_8.3_TS.so PDO_SQLSRV_8.3_TS.so 8.3 sim
SQLSRV_8.4_NTS.so PDO_SQLSRV_8.4_NTS.so 8.4 não
SQLSRV_8.4_TS.so PDO_SQLSRV_8.4_TS.so 8.4 sim
SQLSRV_8.5_NTS.so PDO_SQLSRV_8.5_NTS.so 8.5 não
SQLSRV_8.5_TS.so PDO_SQLSRV_8.5_TS.so 8.5 sim

Copie cada arquivo que precisar no diretório de extensões do PHP. Você pode manter o nome do arquivo do pacote e escrever extension=SQLSRV_8.4_NTS.so, ou renomear o arquivo para sqlsrv.so e escrever a forma curta extension=sqlsrv. Aplique a mesma escolha de nome a PDO_SQLSRV. Para encontrar o diretório de extensão, execute php -i | grep extension_dir. Siga as instruções em Carregar os drivers no Linux e macOS para habilitar as extensões no arquivo de configuração correto e carregue os PHP Data Objects (PDO) antes de PDO_SQLSRV.

Versões mais recentes

Para os arquivos de driver incluídos em versões anteriores à 5.13, baixe o pacote dessa versão na página Microsoft Drivers for PHP for SQL Server releases e liste seu conteúdo. Lançamentos anteriores à 5.12 publicam um pacote separado para cada sistema operacional e versão PHP, em vez de um único pacote por plataforma.

Verifique o ambiente selecionado

Execute essas verificações após instalar as extensões PHP e o driver ODBC, mas antes de configurar um servidor web:

php --version
php --ini
php --ri sqlsrv
php --ri pdo_sqlsrv

Os dois últimos comandos devem exibir seções separadas de informações de módulo. Se algum dos comandos reportar que a extensão não está presente, termine o procedimento de instalação e carregamento da plataforma antes de testar uma conexão com banco de dados.

Crie verify-php-drivers.php para verificar ambas as APIs PHP sem exigir credenciais:

<?php
$failures = [];

if (!extension_loaded('sqlsrv') || !function_exists('sqlsrv_connect')) {
    $failures[] = 'SQLSRV is not loaded.';
}

if (!extension_loaded('pdo_sqlsrv') || !in_array('sqlsrv', PDO::getAvailableDrivers(), true)) {
    $failures[] = 'PDO_SQLSRV is not loaded.';
}

echo $failures === []
    ? "SQLSRV and PDO_SQLSRV are loaded." . PHP_EOL
    : implode(PHP_EOL, $failures) . PHP_EOL;

exit($failures === [] ? 0 : 1);

Execute-o com o executável do PHP usado pela aplicação:

php verify-php-drivers.php

Resultado esperado:

SQLSRV and PDO_SQLSRV are loaded.

Essa verificação verifica o carregamento da extensão. Ele não verifica conectividade ODBC, autenticação, confiança de certificados, acesso à rede ou permissões de banco de dados.

Apague verify-php-drivers.php depois de registrar o resultado.

Diagnosticar falhas de requisitos

Sintoma Provável dono Verificação
PHP Startup: Unable to load dynamic library Seleção do runtime do PHP ou da extensão Versão menor do PHP, arquitetura, modo de segurança de thread, extension_dire nome exato do arquivo
Call to undefined function sqlsrv_connect() Configuração da extensão SQLSRV php --ri sqlsrv, o ativo php.ini e os arquivos digitalizados .ini
PDOException: could not find driver extensão PDO_SQLSRV ou ordem de carregamento do PDO php --ri pdo_sqlsrv, PDO::getAvailableDrivers(), e se o PDO carrega primeiro
Falta a biblioteca msodbcsql ou libodbc Instalação ODBC ou carregador do sistema operacional Pacote ODBC instalado, arquitetura e dependências de bibliotecas compartilhadas
O CLI tem sucesso, mas o site falha Configuração PHP específica para SAPI Compare php --ini com uma página temporária phpinfo() após restringir o acesso à página de diagnóstico
A extensão carrega, mas a conexão falha ODBC, rede, autenticação, certificado ou destino do banco de dados Capture a coleção de erros SQLSRV ou exceção PDO e solucione o SQLSTATE reportado

Conteúdo relacionado

  • Última atualização em