Início rápido: Conectar e consultar com os Drivers da Microsoft para PHP para SQL Server

Use este guia de início rápido para instalar os drivers PHP, conectar-se ao SQL do Azure com sua identidade Microsoft Entra e executar uma consulta Transact-SQL (T-SQL) parametrizada nos dados de exemplo AdventureWorksLT. Escolha entre a API procedural SQLSRV ou a API PDO_SQLSRV. Ambos os exemplos leem as configurações de conexão das variáveis de ambiente e retornam o mesmo resultado.

A consulta lê dados de produto e não cria objetos de banco de dados.

Antes de começar

Crie ou conecte-se a um banco de dados que contenha os AdventureWorksLT dados de exemplo. Para obter instruções de configuração do Banco de Dados SQL do Azure, do SQL database no Microsoft Fabric, do SQL Server e dos contêineres do SQL Server, consulte os bancos de dados de exemplo do AdventureWorks.
Peça ao administrador do banco de dados para criar um usuário de banco de dados para sua identidade Microsoft Entra.
No Windows, faça login com a conta Windows que tem acesso ao banco de dados.
No macOS ou no Linux, obtenha um tíquete Kerberos para uma conta do Microsoft Entra federada. Para requisitos, veja Uso do Microsoft Entra ID com o Driver ODBC.

1. Instalar o PHP e os drivers

Selecione o sistema operacional. Copie o bloco de comando inteiro, cole no terminal especificado e execute.

Abra o PowerShell como administrador. Copie e execute este bloco:

winget install --exact --id PHP.PHP.8.5 --source winget --accept-package-agreements --accept-source-agreements
winget install --exact --id Microsoft.msodbcsql.18 --source winget --accept-package-agreements --accept-source-agreements

$env:Path = [Environment]::GetEnvironmentVariable("Path", "Machine") + ";" +
    [Environment]::GetEnvironmentVariable("Path", "User")
New-Item -ItemType Directory -Force C:\php-quickstart | Out-Null
Set-Location C:\php-quickstart

$phpDirectory = Split-Path (Get-Command php.exe -ErrorAction Stop).Source
$phpIni = Join-Path $phpDirectory "php.ini"
if (-not (Test-Path $phpIni)) {
    Copy-Item (Join-Path $phpDirectory "php.ini-development") $phpIni
}

$configuration = [System.IO.File]::ReadAllText($phpIni)
$configuration = $configuration -replace '(?m)^\s*;\s*extension_dir\s*=\s*"ext"\s*$', 'extension_dir = "ext"'
$configuration = $configuration -replace '(?m)^\s*;\s*extension\s*=\s*openssl\s*$', 'extension=openssl'
$configuration = $configuration -replace '(?m)^\s*;\s*extension\s*=\s*zip\s*$', 'extension=zip'
[System.IO.File]::WriteAllText($phpIni, $configuration)

Invoke-WebRequest https://github.com/php/pie/releases/latest/download/pie.phar -OutFile pie.phar
php .\pie.phar install microsoft/sqlsrv
php .\pie.phar install microsoft/pdo_sqlsrv

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

Os três últimos comandos exibem as versões instaladas do PHP e da extensão. Feche a janela de administrador depois que eles tenham sucesso.

Execute o bloco seguinte em um terminal. O Homebrew solicita confirmação antes de instalar quaisquer pré-requisitos ausentes:

brew install php@8.5 git autoconf automake libtool m4 make pkg-config
brew link --force --overwrite php@8.5
brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew trust microsoft/mssql-release
brew update
HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql18

curl -fL --output /tmp/pie.phar https://github.com/php/pie/releases/latest/download/pie.phar
sudo mkdir -p /usr/local/bin
sudo install /tmp/pie.phar /usr/local/bin/pie
export CPPFLAGS="-I$(brew --prefix unixodbc)/include"
export LDFLAGS="-L$(brew --prefix unixodbc)/lib"
pie install microsoft/sqlsrv
pie install microsoft/pdo_sqlsrv

mkdir -p ~/php-quickstart
cd ~/php-quickstart
php --version
php --ri sqlsrv
php --ri pdo_sqlsrv

Se brew não estiver instalado, instale o Homebrew, abra um novo terminal e execute o bloco novamente.

Execute o seguinte bloco em um terminal em uma versão compatível com Ubuntu:

sudo apt-get update
sudo apt-get install -y php-cli php-dev php-xml php-zip curl git autoconf automake libtool m4 make gcc g++ pkg-config unixodbc-dev

source /etc/os-release
curl -fsSLO "https://packages.microsoft.com/config/ubuntu/$VERSION_ID/packages-microsoft-prod.deb"
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb
sudo apt-get update
sudo ACCEPT_EULA=Y apt-get install -y msodbcsql18

curl -fL --output /tmp/pie.phar https://github.com/php/pie/releases/latest/download/pie.phar
sudo install /tmp/pie.phar /usr/local/bin/pie
pie install microsoft/sqlsrv
pie install microsoft/pdo_sqlsrv

mkdir -p ~/php-quickstart
cd ~/php-quickstart
php --version
php --ri sqlsrv
php --ri pdo_sqlsrv

Para outras distribuições Linux, siga o tutorial de instalação do Linux e macOS.

Se algum dos php --ri comandos indicar que a extensão não está presente, vá para Solução de Problemas da Instalação antes de continuar.

2. Definir as informações de conexão

Substitua <server> e <database> no bloco do seu sistema operacional. Copie e execute todo o bloco no mesmo terminal que você usará para rodar PHP.

Set-Location C:\php-quickstart
$env:SQL_SERVER = "tcp:<server>.database.windows.net,1433"
$env:SQL_DATABASE = "<database>"
$env:SQL_AUTHENTICATION = "ActiveDirectoryIntegrated"

export SQL_SERVER="tcp:<server>.database.windows.net,1433"
export SQL_DATABASE="<database>"
export SQL_AUTHENTICATION="ActiveDirectoryIntegrated"

export SQL_SERVER="tcp:<server>.database.windows.net,1433"
export SQL_DATABASE="<database>"
export SQL_AUTHENTICATION="ActiveDirectoryIntegrated"

Importante

Ambas as amostras permitem a criptografia e validam o certificado do servidor. Se o seu servidor usa um certificado de uma autoridade certificadora privada (CA), instale os certificados raiz e intermediários da CA emissora no repositório de confiança do sistema operacional do cliente. Defina SQL_SERVER com um nome no Nome Alternativo do Assunto ou no Nome Comum do certificado. Caso contrário, a conexão falha antes da consulta ser executada. Para mais informações, veja Cadeia de certificados não confiável e Configurar criptografia do SQL Server.

TrustServerCertificate=true Ignora a validação da identidade do servidor. Use-o apenas para diagnosticar um ambiente local de teste isolado, não como uma configuração de confiança para ambientes de produção ou compartilhados.

3. Criar e rodar uma amostra

Selecione uma API PHP. Crie o arquivo nomeado usando o código na aba selecionada e então execute o comando após o código.

SQLSRV
PDO_SQLSRV

Crie quickstart-sqlsrv.php com o seguinte código:

<?php
declare(strict_types=1);

$server = getenv('SQL_SERVER') ?: null;
$database = getenv('SQL_DATABASE') ?: null;
$authentication = getenv('SQL_AUTHENTICATION') ?: null;

if ($server === null || $database === null || $authentication === null) {
    throw new RuntimeException('Set SQL_SERVER, SQL_DATABASE, and SQL_AUTHENTICATION.');
}
if (!in_array($authentication, ['SqlPassword', 'ActiveDirectoryIntegrated', 'ActiveDirectoryMsi'], true)) {
    throw new RuntimeException(
        'Set SQL_AUTHENTICATION to SqlPassword, ActiveDirectoryIntegrated, or ActiveDirectoryMsi.'
    );
}

$user = null;
$password = null;
if ($authentication === 'SqlPassword') {
    $user = getenv('SQL_USER') ?: null;
    $password = getenv('SQL_PASSWORD') ?: null;
    if ($user === null || $password === null) {
        throw new RuntimeException('Set SQL_USER and SQL_PASSWORD for SqlPassword authentication.');
    }
}

$options = [
    'Database' => $database,
    'Authentication' => $authentication,
    'Driver' => 'ODBC Driver 18 for SQL Server',
    'Encrypt' => true,
    'TrustServerCertificate' => false,
];
if ($authentication === 'SqlPassword') {
    $options['UID'] = $user;
    $options['PWD'] = $password;
}

$connection = sqlsrv_connect($server, $options);
if ($connection === false) {
    throw new RuntimeException(print_r(sqlsrv_errors(), true));
}

$sql = <<<'SQL'
SELECT TOP (5) ProductID, Name
FROM SalesLT.Product
WHERE ProductID > ?
ORDER BY ProductID;
SQL;
$parameters = [0];
$statement = sqlsrv_query($connection, $sql, $parameters);
if ($statement === false) {
    $errors = sqlsrv_errors();
    sqlsrv_close($connection);
    throw new RuntimeException(print_r($errors, true));
}

$rows = [];
while (($row = sqlsrv_fetch_array($statement, SQLSRV_FETCH_ASSOC)) !== null) {
    if ($row === false) {
        $errors = sqlsrv_errors();
        sqlsrv_free_stmt($statement);
        sqlsrv_close($connection);
        throw new RuntimeException(print_r($errors, true));
    }
    $rows[] = $row;
}
sqlsrv_free_stmt($statement);
sqlsrv_close($connection);

if (count($rows) !== 5) {
    throw new RuntimeException('Unexpected query result.');
}
$previousProductId = 0;
foreach ($rows as $row) {
    if ($row['ProductID'] <= $previousProductId || $row['Name'] === '') {
        throw new RuntimeException('Unexpected query result.');
    }
    $previousProductId = $row['ProductID'];
}
printf("%-12s%s\n", 'Product ID', 'Name');
printf("%-12s%s\n", '----------', '----');
foreach ($rows as $row) {
    printf("%-12d%s\n", $row['ProductID'], $row['Name']);
}

Execute o exemplo:

php quickstart-sqlsrv.php

Crie quickstart-pdo.php com o seguinte código:

<?php
declare(strict_types=1);

$server = getenv('SQL_SERVER') ?: null;
$database = getenv('SQL_DATABASE') ?: null;
$authentication = getenv('SQL_AUTHENTICATION') ?: null;

if ($server === null || $database === null || $authentication === null) {
    throw new RuntimeException('Set SQL_SERVER, SQL_DATABASE, and SQL_AUTHENTICATION.');
}
if (!in_array($authentication, ['SqlPassword', 'ActiveDirectoryIntegrated', 'ActiveDirectoryMsi'], true)) {
    throw new RuntimeException(
        'Set SQL_AUTHENTICATION to SqlPassword, ActiveDirectoryIntegrated, or ActiveDirectoryMsi.'
    );
}

$user = null;
$password = null;
if ($authentication === 'SqlPassword') {
    $user = getenv('SQL_USER') ?: null;
    $password = getenv('SQL_PASSWORD') ?: null;
    if ($user === null || $password === null) {
        throw new RuntimeException('Set SQL_USER and SQL_PASSWORD for SqlPassword authentication.');
    }
}

$dsn = "sqlsrv:Driver={ODBC Driver 18 for SQL Server};"
    . "Server=$server;Database=$database;Authentication=$authentication;"
    . "Encrypt=true;TrustServerCertificate=false";
$connection = new PDO(
    $dsn,
    $user,
    $password,
    [
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
        PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
        PDO::ATTR_EMULATE_PREPARES => false,
    ]
);

$sql = <<<'SQL'
SELECT TOP (5) ProductID, Name
FROM SalesLT.Product
WHERE ProductID > ?
ORDER BY ProductID;
SQL;
$statement = $connection->prepare($sql);
$statement->execute([0]);
$rows = $statement->fetchAll();
$statement->closeCursor();
$connection = null;

if (count($rows) !== 5) {
    throw new RuntimeException('Unexpected query result.');
}
$previousProductId = 0;
foreach ($rows as $row) {
    if ($row['ProductID'] <= $previousProductId || $row['Name'] === '') {
        throw new RuntimeException('Unexpected query result.');
    }
    $previousProductId = $row['ProductID'];
}
printf("%-12s%s\n", 'Product ID', 'Name');
printf("%-12s%s\n", '----------', '----');
foreach ($rows as $row) {
    printf("%-12d%s\n", $row['ProductID'], $row['Name']);
}

Execute o exemplo:

php quickstart-pdo.php

4. Verificar o resultado

As linhas de produtos podem variar conforme a versão do AdventureWorksLT. Ambas as amostras retornam uma saída que se assemelha a este exemplo:

Product ID  Name
----------  ----
680         HL Road Frame - Black, 58
706         HL Road Frame - Red, 58
707         Sport-100 Helmet, Red
708         Sport-100 Helmet, Black
709         Mountain Bike Socks, M

Cada amostra verifica se a consulta retornou cinco produtos com nomes não vazios e IDs de produto crescentes antes de imprimir as linhas. Em seguida, libera a declaração e fecha a conexão. A consulta não deixa nenhum objeto ou dado do banco de dados para remover.

Use outro método de autenticação

Os samples também aceitam identidade gerenciada e autenticação SQL Server sem alterar os arquivos PHP.

Identidade gerenciada

Para uma aplicação hospedada no Azure, ative uma identidade gerenciada e crie seu usuário de banco de dados. Defina o servidor, banco de dados e modo de autenticação na configuração da aplicação:

SQL_SERVER=tcp:<server>.database.windows.net,1433
SQL_DATABASE=<database>
SQL_AUTHENTICATION=ActiveDirectoryMsi

Não definir SQL_USER ou SQL_PASSWORD.

Para banco de dados SQL no Microsoft Fabric, conceda permissão de leitura do item de identidade por meio de controles de acesso do Fabric. Use o endpoint de conexão SQL do item de banco de dados, não o endpoint de análise SQL. O banco de dados SQL no Fabric não suporta autenticação SQL.

Autenticação do SQL Server

Use autenticação do SQL Server apenas para uma instância do SQL Server que você controle, como um contêiner local isolado de desenvolvimento. Mantenha as credenciais na configuração do aplicativo ou em um armazenamento secreto. Não os inclua no controle de versão.

$env:SQL_SERVER = "tcp:<server>,1433"
$env:SQL_DATABASE = "<database>"
$env:SQL_AUTHENTICATION = "SqlPassword"
$env:SQL_USER = "<user_id>"
$env:SQL_PASSWORD = "<password>"

export SQL_SERVER="tcp:<server>,1433"
export SQL_DATABASE="<database>"
export SQL_AUTHENTICATION="SqlPassword"
export SQL_USER="<user_id>"
export SQL_PASSWORD="<password>"

export SQL_SERVER="tcp:<server>,1433"
export SQL_DATABASE="<database>"
export SQL_AUTHENTICATION="SqlPassword"
export SQL_USER="<user_id>"
export SQL_PASSWORD="<password>"

Para outros métodos de autenticação Microsoft Entra, veja Conecte usando autenticação Microsoft Entra.

Solução de problemas na instalação

Use essas verificações se o bloco de instalação parar ou se algum comando de verificação falhar.

Get-Command php.exe
php --ini
php --ri sqlsrv
php --ri pdo_sqlsrv
Get-OdbcDriver -Name "ODBC Driver 18 for SQL Server"

Se Get-Command não conseguir encontrar php.exe, feche todos os terminais, abra uma nova janela do PowerShell e execute as verificações novamente. Se um comando php --ri retornar Extensão não presente, execute novamente os comandos de instalação do PIE de C:\php-quickstart.

command -v php
php --ini
php --ri sqlsrv
php --ri pdo_sqlsrv
odbcinst -q -d | grep "ODBC Driver 18 for SQL Server"

Se command -v não encontrar PHP, execute brew link --force --overwrite php@8.5, abra um novo terminal e faça as verificações novamente.

command -v php
php --ini
php --ri sqlsrv
php --ri pdo_sqlsrv
odbcinst -q -d | grep "ODBC Driver 18 for SQL Server"

Se um php --ri comando reportar a ausência de Extensão, execute novamente os comandos de instalação do PIE. Use o caminho de php --ini para confirmar se o ambiente de execução da linha de comando carrega a configuração que o PIE atualizou.

Se uma conexão retornar FA001 e disser que a opção Autenticação não pode ser usada com Segurança Integrada, confirme se SQL_AUTHENTICATION é exatamente ActiveDirectoryIntegrated. Execute php --ri sqlsrv ou php --ri pdo_sqlsrv para verificar a versão do driver do PHP e atualize o driver se for anterior à versão 5.10.1.

Limpeza

Os exemplos liberam suas declarações e fecham suas conexões. Eles não criam objetos de banco de dados nem persistem dados.

As configurações de conexão se aplicam à sessão terminal atual. Feche o terminal quando terminar.

Para configurações de nova tentativa em produção, tempo limite, registro em log e alternância em caso de falha, use a configuração básica de produção em vez de estender este exemplo de execução inicial.

Comentários

Esta página foi útil?

Last updated on 2026-09-25