Início Rápido: Ligue-se e faça consultas com os drivers Microsoft para PHP para SQL Server

Utilize este guia de início rápido para instalar os controladores do PHP, ligar-se ao SQL do Azure com a sua identidade do Microsoft Entra e executar uma consulta Transact-SQL parametrizada (T-SQL) sobre os dados de exemplo AdventureWorksLT. Escolha a API processual SQLSRV ou a API PDO_SQLSRV. Ambas as amostras leem as definições de ligação das variáveis de ambiente e devolvem o mesmo resultado.

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

Antes de começar

1. Instalar o PHP e os drivers

Selecione o seu sistema operativo. Copia o bloco de comandos inteiro, cola-o no terminal especificado e executa-o.

Abrir 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 mostram as versões instaladas do PHP e da extensão. Fecha a janela do administrador depois de terem êxito.

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

2. Definir a informação de ligação

Substitua <server> e <database> no bloco correspondente ao seu sistema operativo. Copia e executa o bloco inteiro no mesmo terminal que vais usar para correr PHP.

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

Importante

Ambas as amostras permitem a encriptação e validam o certificado do servidor. Se o seu servidor usar um certificado de uma autoridade certificadora privada (CA), instale os certificados raiz e intermédios da CA emitentes na loja de confiança do sistema operativo do cliente. Definir SQL_SERVER como um nome que conste do Nome Alternativo do Requerente ou do Nome Comum do certificado. Caso contrário, a ligação falha antes da consulta ser executada. Para mais informações, consulte Cadeia de certificados não confiável e Configurar encriptação do SQL Server.

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

3. Criar e executar uma amostra

Selecione uma API PHP. Crie o ficheiro nomeado usando o código no separador selecionado e depois execute o comando após o código.

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']);
}

Analisa a amostra:

php quickstart-sqlsrv.php

4. Verificar o resultado

As linhas de produtos podem variar consoante 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 devolveu cinco produtos com nomes não vazios e IDs de produto crescentes antes de imprimir as linhas. Depois liberta a declaração e fecha a ligação. A consulta não deixa quaisquer objetos ou dados da base de dados para remover.

Usar outro método de autenticação

Os exemplos também aceitam identidade gerida e autenticação SQL Server sem alterar os ficheiros PHP.

Identidade gerenciada

Para uma aplicação alojada no Azure, ativa uma identidade gerida e cria o utilizador da base de dados. Defina o servidor, base 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 definas SQL_USER ou SQL_PASSWORD.

Para base de dados SQL no Microsoft Fabric, conceda à identidade permissão de leitura do item através dos controlos de acesso do Fabric. Usa o endpoint de ligação SQL do item da base de dados, não o endpoint de análise SQL. A base de dados SQL no Fabric não suporta autenticação SQL.

Autenticação do SQL Server

Use a autenticação do SQL Server apenas para uma instância do SQL Server que controle, como um contentor local isolado de desenvolvimento. Mantém as credenciais na configuração da aplicação ou numa loja secreta. Não os coloquem em controlo 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>"

Para outros métodos de autenticação Microsoft Entra, veja Connect using Microsoft Entra authentication.

Resolução de problemas na instalação

Utilize estas verificações se o bloco de instalação parar ou se um 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, fecha todos os terminais, abre uma nova janela do PowerShell e executa novamente as verificações. Se um comando php --ri indicar Extensão não presente, execute novamente os comandos de instalação do PIE a partir de C:\php-quickstart.

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

Limpeza

Os samples divulgam as suas declarações e fecham as suas ligações. Eles não criam objetos de base de dados nem persistem dados.

As definições de ligação aplicam-se à sessão terminal atual. Fecha o terminal quando terminares.

Para as definições de repetição em produção, tempo limite, registo e ativação pós-falha, use a configuração de base de produção em vez de alargar este exemplo de execução inicial.

Conteúdo relacionado

  • Last updated on