Requisitos de sistema para os Microsoft Drivers for PHP para SQL Server

Descarregar o driver PHP

Este artigo lista os componentes que deve instalar no seu sistema para aceder a dados em SQL Server ou Base de Dados SQL do Azure usando o controlador SQLSRV ou PDO_SQLSRV.

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 operativo, arquitetura, segurança de threads e ODBC.

Como a pilha de drivers se encaixa

Uma aplicação PHP não se liga diretamente ao servidor da base de dados. Cada camada deve ser compatível com a camada adjacente:

SQLSRV e PDO_SQLSRV fornecem diferentes APIs PHP sobre o mesmo driver ODBC. Instala ambos quando a tua aplicação usar ambas as APIs. Instalar uma extensão não instala nem ativa automaticamente a outra.

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 descarregar ou construir um controlador, complete estas verificações:

1. Identifique todos os ambientes de execução PHP que servem a aplicação. Uma tarefa agendada, um worker de linha de comandos, um site IIS, um módulo Apache e um pool PHP-FPM podem usar diferentes executáveis PHP e ficheiros de configuração.

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 reportar um executável universal do macOS, selecione explicitamente a arquitetura pretendida, como arch -arm64 php --version ou arch -x86_64 php --version. Utilize 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, o sistema operativo e o destino da base de dados.

4. Selecione uma versão suportada do driver Microsoft ODBC a partir da tabela de compatibilidade neste artigo.

5. Associe o ficheiro de extensão ou a compilação PIE à arquitetura do PHP e ao modo de segurança de execução (thread safety). Não copie uma extensão de outra instalação PHP a menos que todos estes valores coincidam.

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

PHP

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

• Ativa o ficheiro do driver que corresponde à tua versão PHP. Para nomes de ficheiros, veja Versões dos drivers. Descarregue os ficheiros de Transferir o Microsoft Drivers for PHP for SQL Server. Para instruções de configuração, consulte Carregar os drivers Microsoft para PHP para SQL Server.

• Escolha um servidor web e um método de integração PHP suportados pelo PHP e pelo seu framework de aplicação. Siga a documentação de instalação do PHP e as instruções de implementação em produção do seu framework para configurar o servidor web para executar PHP. Verifique o carregamento das extensões no runtime do servidor web separadamente do CLI.

Segurança e arquitetura de threads

A compilação e o ficheiro de extensão PHP devem concordar em ambos os valores.

A CLI pode usar uma build PHP thread-safe ou não-thread-safe. Selecione a extensão pelo valor reportado e não assuma que todas as builds CLI não são seguras para threads.

controlador ODBC

Instale um driver Microsoft ODBC suportado para SQL Server no computador que executa PHP. Descarregue o driver em Download ODBC Driver for SQL Server.

Se estiver a descarregar a versão Windows do driver numa versão de 64 bits, o instalador ODBC de 64 bits instala tanto os drivers ODBC de 32 bits como os de 64 bits. Se usares uma versão do Windows de 32 bits, usa o instalador ODBC x86. Em plataformas não Windows, apenas versões de 64 bits do driver estão disponíveis.

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

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

Se estiver a usar o driver SQLSRV, sqlsrv_client_info devolve informações sobre qual versão do SQL Server Microsoft ODBC Driver for SQL Server está a ser usada pelos Microsoft Drivers para PHP for SQL Server. Se estiveres a usar o driver PDO_SQLSRV, podes usar PDO::getAttribute para descobrir a versão.

SQL Server

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

Avalie separadamente o suporte ao destino para 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. Os requisitos de instalação são requisitos do lado do cliente e não estabelecem que todos os métodos de autenticação, opções de ligação, funcionalidades Transact-SQL (T-SQL) ou tipos de dados estejam disponíveis em todos os alvos. Utilize a matriz de suporte e a documentação do produto alvo para o cenário que a sua aplicação utiliza.

Sistemas operacionais

Para sistemas operativos suportados, veja Sistemas operativos suportados.

Versões do driver

Cada versão dos Microsoft Drivers para PHP para SQL Server disponibiliza ficheiros dos controladores SQLSRV e 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. Faça corresponder o ficheiro do controlador à sua versão do PHP, ao modo de segurança de execução e à arquitetura. Para ativar um ficheiro de controlador após o descarregar, consulte Carregar os Controladores Microsoft para PHP para SQL Server.

No Linux e macOS, instale os drivers com o PIE, o Instalador PHP para Extensões, 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 dá à extensão instalada o nome sqlsrv.so ou pdo_sqlsrv.so. As tabelas seguintes listam os nomes dos ficheiros dos pacotes binários pré-construídos que descarrega manualmente da página Microsoft Drivers for PHP for SQL Server releases.

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

Ficheiros de controladores do Windows

O Windows_5.13.xRTW.zip pacote contém estes ficheiros.

Utilize um ficheiro driver não thread-safe com uma build PHP não thread-safe, e um ficheiro driver thread-safe com uma build PHP thread-safe. A interface de linha de comandos (CLI) pode usar qualquer uma das duas compilações. Para confirmar qual build tens, executa php -i e verifica o valor de Thread Safety .

Ficheiros de drivers para Linux e macOS

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

Os ficheiros pré-construídos também devem corresponder às bibliotecas nativas do seu sistema operativo. Os binários Linux 5.13.3 requerem glibc 2.38 e 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 o seu alvo mínimo de implementação. Estes requisitos binários são separados do suporte do sistema operativo para compilações de código-fonte.

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

Copia cada ficheiro de que precisas no teu diretório de extensões PHP. Pode manter o nome do ficheiro do pacote e escrever extension=SQLSRV_8.4_NTS.so, ou renomear o ficheiro para sqlsrv.so e escrever a forma extension=sqlsrvcurta . Aplique a mesma escolha de nome a PDO_SQLSRV. Para encontrar o diretório de extensões, execute php -i | grep extension_dir. Siga Carregar os controladores no Linux e macOS para ativar as extensões no ficheiro de configuração correto e carregue PHP Data Objects (PDO) antes de PDO_SQLSRV.

Versões anteriores

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

Verificar o ambiente selecionado

Execute estas 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 mostrar secções separadas de informação 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 ligação à base de dados.

Criar 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 PHP que serve a aplicação:

php verify-php-drivers.php

Produção esperada:

SQLSRV and PDO_SQLSRV are loaded.

Esta verificação verifica o carregamento da extensão. Não verifica a conectividade ODBC, a autenticação, a confiança de certificados, o acesso à rede ou as permissões da base de dados.

Apaga verify-php-drivers.php depois de registares o resultado.

Diagnosticar falhas de requisitos

Conteúdo relacionado

• Começar com os drivers Microsoft para PHP para SQL Server
• Guia de Programação para os Microsoft Drivers for PHP para SQL Server
• Referência da API do Driver SQLSRV
• Referência do Driver PDO_SQLSRV