Instala los controladores de Microsoft para PHP en Linux y macOS

Estas instrucciones instalan PHP, el controlador ODBC Microsoft para SQL Server y las extensiones SQLSRV y PDO_SQLSRV. Cada pestaña utiliza el paquete PHP proporcionado por el repositorio del que instala esa pestaña, por lo que la versión de los comandos varía de una pestaña a otra. Sustituyela por otra versión de PHP listada en la matriz de soporte si ese repositorio ofrece una diferente.

Los controladores SQLSRV y PDO_SQLSRV utilizan la misma dependencia ODBC y pueden instalarse de forma independiente. Instala ambas extensiones si tu aplicación usa ambos controladores.

Al final del procedimiento, la CLI y el runtime seleccionado del servidor web deben cargar ambas extensiones, ambas APIs PHP deberían estar disponibles y la muestra de cada API debería devolver la versión del servidor de base de datos.

Antes de comenzar

  1. Elige una versión de PHP soportada por la versión actual del controlador y disponible para tu versión del sistema operativo.

  2. Elige qué versiones de PHP necesitas:

    • CLI para scripts, tareas programadas o workers.
    • Módulo Apache para PHP alojado en Apache.
    • PHP-FPM para nginx o una configuración Apache FastCGI.

  3. Confirma la arquitectura del sistema operativo. Los archivos de Linux publicados contienen binarios x64 y los archivos liberados de macOS contienen binarios Arm64. PIE compila para la instalación de PHP del ordenador y es el método principal de instalación en este artículo.

  4. Instala el controlador Microsoft ODBC y el paquete de desarrollo unixODBC. El paquete de Microsoft gestiona la comunicación con la base de datos. El paquete unixODBC suministra los encabezados necesarios para compilar SQLSRV y PDO_SQLSRV.

  5. Planea reiniciar todos los servidores web, PHP-FPM pool y trabajadores de larga duración tras instalar o cambiar una extensión.

El gestor de paquetes de la plataforma instala PHP y prerrequisitos nativos. PIE construye e instala las extensiones de PHP. La configuración de PHP controla si cada entorno de ejecución los carga. El controlador ODBC gestiona la comunicación y el cifrado de la base de datos tras la carga de la extensión.

Instala los controladores con PIE

PIE, el Instalador PHP para Extensiones, es el instalador de extensiones compatible oficialmente con las versiones actuales de controladores. Sustituye al flujo de trabajo obsoleto de la Biblioteca Comunitaria de Extensión PHP (PECL).

Completa los requisitos previos de la plataforma en las siguientes secciones antes de instalar los controladores. Luego instala PIE y cada controlador por separado:

Instalar PIE

PIE funciona en PHP 8.1 y versiones posteriores. Puede instalar una extensión en otra instalación PHP cuando seleccionas las herramientas de desarrollo de esa instalación.

Instala curl y la CLI de GitHub antes de continuar. Las secciones de la plataforma incluyen curl, que una instalación mínima podría no proporcionarlo.

Descarga el archivo PIE PHP (PHAR) y verifica con la interfaz de línea de comandos (CLI) de GitHub antes de instalarlo o ejecutarlo:

pie_tmp=$(mktemp -d)
curl -fL --output "$pie_tmp/pie.phar" https://github.com/php/pie/releases/latest/download/pie.phar
gh attestation verify --owner php "$pie_tmp/pie.phar"

Continúa solo si la verificación tiene éxito:

sudo install -m 755 "$pie_tmp/pie.phar" /usr/local/bin/pie
rm "$pie_tmp/pie.phar"
rmdir "$pie_tmp"
unset pie_tmp

El directorio temporal es privado para tu cuenta. Si falla la descarga o la verificación, no instales ni ejecutes el PHAR. Elimina el archivo y el directorio temporales antes de intentarlo de nuevo.

Confirma que el PHAR instalado funciona con el ejecutable PHP que piensas usar:

php /usr/local/bin/pie --version

Instala los controladores SQLSRV y PDO_SQLSRV

En Linux y macOS, PIE comprueba si están presentes el compilador y las herramientas de desarrollo de PHP que necesita. Instala el paquete de desarrollo ODBC de la plataforma y un compilador C++ antes de ejecutar PIE. Ejecuta PIE desde un terminal interactivo. Puede pedir tu sudo contraseña cuando necesite permiso para instalar archivos en directorios del sistema.

PIE apunta a la instalación PHP utilizada para invocarlo. Para una instalación versionada, añade --with-php-config a cada comando de instalación para seleccionar las herramientas de desarrollo correspondientes. Por ejemplo, usa pie install --with-php-config=/usr/bin/php-config8.4 microsoft/sqlsrv cuando la herramienta prevista es /usr/bin/php-config8.4. Aplica la misma opción a microsoft/pdo_sqlsrv. Alpine utiliza nombres ejecutables versionados; sigue los comandos Alpine en lugar de los comandos no versionados de esta sección.

Ejecuta un comando para cada extensión. Estos comandos utilizan la instalación predeterminada de PHP de PIE:

pie install microsoft/sqlsrv
pie install microsoft/pdo_sqlsrv

PIE intenta habilitar cada extensión a través de las herramientas de configuración PHP de la plataforma o una entrada extension=, y avisa si no puede. PHP utiliza una interfaz de programación de aplicaciones del servidor (SAPI) para cada entorno de ejecución. En Debian, Ubuntu y SUSE, las configuraciones de línea de comandos, Apache y PHP FastCGI Process Manager (PHP-FPM) pueden variar. Una instalación exitosa en línea de comandos no confirma que un servidor web cargue los controladores.

Consulta php --ini para la línea de comandos. Antes de crear una página temporal phpinfo() para el servidor web, restringe el acceso a la página de diagnóstico. Revisa el archivo de configuración cargado y los archivos analizados .ini de cada entorno de ejecución. Si faltan las entradas, sigue Cargar los controladores en Linux y macOS para añadirlos en el orden de carga correcto. Reinicia el servidor web o PHP-FPM tras cambios de configuración. Red Hat suele compartir php.ini entre SAPIs, pero verifica la configuración activa antes de confiar en una única ejecución de PIE.

Instala en tu plataforma

Selecciona tu sistema operativo y configuración del servidor web. Completa los pasos de instalación en esa pestaña y luego sigue Comprobación de la instalación.

Instalación en Ubuntu

Nota:

Los siguientes comandos utilizan el repositorio PHP packages.sury.org para que puedas seleccionar una versión de PHP compatible. Utiliza las instrucciones oficiales de Microsoft para instalar el controlador ODBC en tu versión de Ubuntu.

Paso 1. Instalación de PHP (Ubuntu)

sudo apt-get update
sudo apt-get install ca-certificates apt-transport-https curl gnupg2 lsb-release -y
sudo install -d -m 755 /etc/apt/keyrings
sudo curl -fsSL https://packages.sury.org/php/apt.gpg -o /etc/apt/keyrings/php.gpg
sudo chmod 644 /etc/apt/keyrings/php.gpg
echo "deb [signed-by=/etc/apt/keyrings/php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/php.list
sudo apt-get update
sudo apt-get install php8.4 php8.4-dev php8.4-xml -y

Paso 2. Instalación de requisitos previos (Ubuntu)

Sigue la instalación del controlador Microsoft ODBC para SQL Server en Linux y luego instala los encabezados de desarrollo.

sudo apt-get install unixodbc-dev g++ make git -y

Paso 3. Instala los controladores PHP para Microsoft SQL Server con PIE (Ubuntu)

Sigue el procedimiento de Instalar los controladores con PIE, añadiendo --with-php-config=/usr/bin/php-config8.4 a ambos comandos de instalación. Revisa los archivos de configuración de línea de comandos con php8.4 --ini.

/usr/local/bin/pie install --with-php-config=/usr/bin/php-config8.4 microsoft/sqlsrv
/usr/local/bin/pie install --with-php-config=/usr/bin/php-config8.4 microsoft/pdo_sqlsrv

Paso 4. Instalación de Apache y configuración de la carga de controladores (Ubuntu)

sudo apt-get install apache2 libapache2-mod-php8.4 -y
sudo a2enmod php8.4

Paso 5. Reinicie Apache y pruebe el script de ejemplo (Ubuntu)

sudo systemctl restart apache2

Para probar la instalación, consulte Prueba de la instalación al final de este documento.

Instalación heredada de PECL

PECL está obsoleto para las versiones actuales del controlador. Usa PIE para nuevas instalaciones y actualizaciones. Si un despliegue existente está fijado a PECL, mantén sus versiones de paquetes alineadas con el tiempo de ejecución de PHP y planifica un cambio a PIE.

Prueba tu instalación

Verifica el entorno de ejecución de línea de comandos. En Alpine, sustituye php por php84. Para una instalación PHP versionada en otra distribución, utiliza su ejecutable correspondiente.

php --ri sqlsrv
php --ri pdo_sqlsrv
php -m | grep -E "sqlsrv|pdo_sqlsrv"

Ambos --ri comandos deben imprimir información del módulo que incluya ExtensionVer. La lista de módulos debe contener líneas separadas para sqlsrv y pdo_sqlsrv.

Antes de probar una conexión, verifica ambas interfaces de la API de PHP con verify-php-drivers.php:

<?php
$checks = [
    'SQLSRV' => extension_loaded('sqlsrv') && function_exists('sqlsrv_connect'),
    'PDO_SQLSRV' => extension_loaded('pdo_sqlsrv')
        && in_array('sqlsrv', PDO::getAvailableDrivers(), true),
];

$failed = false;
foreach ($checks as $name => $loaded) {
    echo "$name: " . ($loaded ? 'loaded' : 'missing') . PHP_EOL;
    $failed = $failed || !$loaded;
}

exit($failed ? 1 : 0);

Resultado esperado:

SQLSRV: loaded
PDO_SQLSRV: loaded

Para PHP-FPM o un servidor web, restringe el acceso a la página de diagnóstico antes de crear una página temporal phpinfo(). Confirma el archivo de configuración cargado, extension_dir y ambas secciones del controlador. Reinicia PHP-FPM o el servidor web después de cambiar la configuración o reemplazar una extensión. Elimina la página tras la verificación.

Para probar una conexión en vivo, crea un archivo llamado testsql.php en el directorio raíz de documentos de tu sistema. Esta ruta de acceso está /var/www/html en Ubuntu, Debian y Red Hat, /srv/www/htdocs en SUSE, /var/www/localhost/htdocs en Alpine o $(brew --prefix)/var/www en macOS. Establezca las SQL_SERVER_NAMEvariables , SQL_DATABASE, SQL_UID, y SQL_PWD de entorno para el proceso PHP antes de ejecutar el script. No codifiques las credenciales en un archivo bajo la raíz del documento.

Para una prueba de línea de comandos, utiliza las solicitudes interactivas para establecer las variables de entorno sin introducir una contraseña en el historial del shell.

Para una prueba de módulo Apache, mantén las credenciales fuera del archivo de configuración generalmente legible del sitio:

  1. Crea un archivo privado fuera de la raíz del documento. Usa un nombre de archivo no utilizado en el directorio de configuración de Apache. En Linux:

    sudo install -o root -g root -m 600 /dev/null /etc/apache2/php-sql-driver-test.conf

    En Red Hat, sustituye /etc/apache2 por /etc/httpd. En macOS, crea el archivo como la cuenta que inicia el Apache de Homebrew:

    install -m 600 /dev/null "$(brew --prefix)/etc/httpd/php-sql-driver-test.conf"

    Solo el propietario del archivo y root pueden leer estas configuraciones. La cuenta que inicia Apache debe ser capaz de leer el archivo.

  2. Edita el archivo privado en un editor de texto y añade estas entradas:

    SetEnv SQL_SERVER_NAME "tcp:<server>,1433"
SetEnv SQL_DATABASE "<database>"
SetEnv SQL_UID "<user_id>"
SetEnv SQL_PWD "<password>"

    Dentro de los argumentos con doble comilla, escribe \\ para cada barra invertida literal y \" para cada doble comilla literal. Conserva los espacios de inicio y de final dentro de las comillas. Apache también sustituye las referencias ${NAME}. Si un valor contiene esa secuencia o un salto de línea, usa la prueba en la línea de comandos en su lugar. Para más información, consulta configuración de Apache: comillas y escape.

  3. Dentro del host virtual del sitio, añade un Files bloque que incluya el archivo privado solo para testsql.php. Si no hay un host virtual configurado, coloca el bloque en la configuración principal del servidor. Sustituye el marcador por la ruta absoluta de la clave privada:

    <Files "testsql.php">
    Include "<absolute-path-to-private-file>"
</Files>

  4. Reinicia Apache. Después de probar, elimina el Files bloque que añadiste, elimina el archivo privado y reinicia Apache. Mantén configuraciones de sitios no relacionadas.

PHP-FPM borra por defecto las variables de entorno heredadas, y nginx no pasa su entorno a PHP-FPM. Utiliza el siguiente procedimiento de Ubuntu o Red Hat solo con un servicio y pool de PHP-FPM de prueba aislados. No añadas credenciales de prueba a un servicio o pool que ejecute otras aplicaciones: todos los scripts de ese pool pueden leerlas. Si usas alojamiento compartido, usa la prueba desde la línea de comandos.

  1. Crea un archivo propiedad de la raíz fuera de la raíz del documento, como /etc/php-sql-driver-test.env, y restringe el acceso a él:

    sudo touch /etc/php-sql-driver-test.env
sudo chmod 600 /etc/php-sql-driver-test.env

    Añade la configuración de conexión al archivo:

    SQL_SERVER_NAME="tcp:<server>,1433"
SQL_DATABASE="<database>"
SQL_UID="<user_id>"
SQL_PWD="<password>"

    Mantén cada ajuste en una sola línea. Dentro de las comillas dobles, escribe \\ para cada barra invertida literal y \" para cada comilla doble literal. Los signos de dólar y las comillas invertidas no se evalúan como expresiones del shell. Edita el archivo directamente en lugar de ejecutarlo o cargarlo en un shell. Para más información, consulta la sintaxis de systemd EnvironmentFile.

  2. Ejecuta sudo systemctl edit php8.4-fpm en Ubuntu o sudo systemctl edit php-fpm en Red Hat. Añade esta configuración de reemplazo de systemd:

    [Service]
EnvironmentFile=/etc/php-sql-driver-test.env

  3. Añade estas entradas a la configuración activa del pool de PHP-FPM. Las ubicaciones más comunes son /etc/php/8.4/fpm/pool.d/www.conf en Ubuntu y /etc/php-fpm.d/www.conf en Red Hat:

    env[SQL_SERVER_NAME] = $SQL_SERVER_NAME
env[SQL_DATABASE] = $SQL_DATABASE
env[SQL_UID] = $SQL_UID
env[SQL_PWD] = $SQL_PWD

  4. Recarga systemd y reinicia el servicio de PHP-FPM correspondiente:

    sudo systemctl daemon-reload
sudo systemctl restart php8.4-fpm

    En Red Hat, sustituye php8.4-fpm por php-fpm.

Después de las pruebas, elimina el archivo temporal de entorno, la EnvironmentFile= entrada que añadiste, las entradas del grupo de pruebas, y testsql.php. Elimina el archivo de anulación del servicio solo si lo creaste para esta prueba y no contiene ninguna otra configuración. Mantén todas las sobrescrituras y configuraciones del grupo preexistentes. Recarga systemd y reinicia PHP-FPM de nuevo después de eliminar la configuración de prueba.

Ejemplo de SQLSRV

Mantén los valores del entorno sin cambios. Cada ejemplo rechaza la configuración ausente o vacía antes de conectarse. Cada ejemplo duplica las llaves de cierre y añade las llaves exteriores antes de pasar el nombre de la base de datos, nombre de usuario y contraseña al controlador. Esta codificación preserva las llaves literales y evita que los puntos y coma separen las opciones de conexión.

<?php
$serverName = getenv('SQL_SERVER_NAME');
$databaseName = getenv('SQL_DATABASE');
$uid = getenv('SQL_UID');
$pwd = getenv('SQL_PWD');

if ($serverName === false || $serverName === ''
    || $databaseName === false || $databaseName === ''
    || $uid === false || $uid === ''
    || $pwd === false || $pwd === '') {
    handle_failure("Set SQL_SERVER_NAME, SQL_DATABASE, SQL_UID, and SQL_PWD.");
}

$databaseName = '{' . str_replace('}', '}}', $databaseName) . '}';
$uid = '{' . str_replace('}', '}}', $uid) . '}';
$pwd = '{' . str_replace('}', '}}', $pwd) . '}';
$connectionOptions = array(
    "Database" => $databaseName,
    "UID" => $uid,
    "PWD" => $pwd,
    "Encrypt" => 1,
    "TrustServerCertificate" => 0
);

function handle_failure($message) {
    error_log($message);
    http_response_code(500);
    echo "<h1>Failure</h1>";
    echo "An error occurred. Check the server error log for details.";
    exit(1);
}

function format_errors($errors) {
    $lines = [];
    foreach ($errors as $error) {
        $lines[] = "SQLSTATE: {$error['SQLSTATE']}, code: {$error['code']}, message: {$error['message']}";
    }
    return implode(PHP_EOL, $lines);
}

$conn = sqlsrv_connect($serverName, $connectionOptions);
if ($conn === false) {
    handle_failure(format_errors(sqlsrv_errors()));
}

$tsql = "SELECT @@Version AS SQL_VERSION";

$stmt = sqlsrv_query($conn, $tsql);
if ($stmt === false) {
    handle_failure(format_errors(sqlsrv_errors()));
}

$row = sqlsrv_fetch_array($stmt, SQLSRV_FETCH_ASSOC);
if ($row === null || $row === false) {
    handle_failure("Query returned no rows.");
}

echo "<h1>Success</h1>";
echo htmlspecialchars($row['SQL_VERSION']);

sqlsrv_free_stmt($stmt);
sqlsrv_close($conn);
?>

Ejemplo de PDO_SQLSRV

<?php
$serverName = getenv('SQL_SERVER_NAME');
$databaseName = getenv('SQL_DATABASE');
$uid = getenv('SQL_UID');
$pwd = getenv('SQL_PWD');

if ($serverName === false || $serverName === ''
    || $databaseName === false || $databaseName === ''
    || $uid === false || $uid === ''
    || $pwd === false || $pwd === '') {
    handle_failure(new RuntimeException("Set SQL_SERVER_NAME, SQL_DATABASE, SQL_UID, and SQL_PWD."));
}

$databaseName = '{' . str_replace('}', '}}', $databaseName) . '}';
$uid = '{' . str_replace('}', '}}', $uid) . '}';
$pwd = '{' . str_replace('}', '}}', $pwd) . '}';

function handle_failure($exception) {
    error_log($exception->getMessage());
    http_response_code(500);
    echo "<h1>Failure</h1>";
    echo "An error occurred. Check the server error log for details.";
    exit(1);
}

try {
    $conn = new PDO(
        "sqlsrv:server=$serverName;Database=$databaseName;Encrypt=1;TrustServerCertificate=0",
        $uid,
        $pwd
    );
    $conn->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

    $tsql = "SELECT @@Version AS SQL_VERSION";

    $stmt = $conn->query($tsql);
    $row = $stmt->fetch(PDO::FETCH_ASSOC);
    if ($row === false) {
        throw new RuntimeException("Query returned no rows.");
    }

    echo "<h1>Success</h1>";
    echo htmlspecialchars($row['SQL_VERSION']);
} catch (Throwable $exception) {
    handle_failure($exception);
}

unset($stmt);
unset($conn);
?>

Apunte el explorador a http://localhost/testsql.php (http://localhost:8080/testsql.php en macOS). Una conexión exitosa muestra la cadena de versión del servidor de base de datos. Ambos ejemplos escriben los detalles del error en el registro de errores de PHP. Si la página muestra un fallo, revisa ese registro.

Para comparar el comportamiento de la línea de comandos y del servidor web, establece las mismas variables de entorno para tu terminal y ejecuta:

php testsql.php

Si ejecutar desde la línea de comandos tiene éxito pero no aparece nada en tu navegador, revisa los archivos de registro de Apache. Para más ayuda, consulta recursos de soporte para el controlador SQL PHP.

Evalúa los programas de conexión por separado para SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics, base de datos SQL en Microsoft Fabric y Warehouse en Microsoft Fabric. El método de autenticación seleccionado, las opciones de conexión y la consulta deben ser admitidos por el destino. La instalación se realiza en el cliente. Una comprobación exitosa de extensiones no demuestra que un destino acepte las credenciales, confíe en el cliente o soporte todas las funciones de la base de datos.

Solucionar problemas de instalación

Síntoma Capa propietaria Acción correctiva
PIE no puede encontrar phpize, php-config, ni encabezados Paquetes de desarrollo PHP Instala el paquete de desarrollo para la versión de PHP objetivo y pasa la opción correspondiente --with-php-config
La compilación falla porque falta un compilador de C++ Herramientas de compilación del sistema operativo Instala el paquete compilador de C++ de la plataforma, como g++ o gcc-c++
La compilación no puede encontrar sql.h Rutas del paquete de desarrollo de ODBC o del compilador Instala unixodbc-dev o unixODBC-devel; en Apple silicon, configura las flags de include y de library de Homebrew
php --ri dice que la extensión no está presente Configuración de PHP Inspecciona el php.ini cargado y el directorio analizado, añade la entrada correcta y reinicia el proceso
Informes de PDO could not find driver Carga de PDO_SQLSRV o orden de carga de PDO Confirma que el PDO carga primero y PDO_SQLSRV usa un archivo de configuración escaneado posteriormente
CLI funciona, pero apache, nginx o PHP-FPM fallan Configuración específica de SAPI Compara la salida de la CLI con phpinfo(), configura el SAPI web y reinícialo
El navegador devuelve HTTP 502 a través de nginx enrutamiento de nginx a PHP-FPM Compara el fastcgi_pass socket con la versión PHP-FPM instalada y confirma que el servicio está funcionando
El ejemplo del navegador informa de la falta de valores de entorno Entorno de servidor web o PHP-FPM Configura las variables para el runtime web seleccionado y luego reinícialo
Las extensiones cargan pero la conexión falla ODBC, red, certificado, autenticación o producto SQL Lee el SQLSTATE y el error nativo del registro del servidor; no reconstruyas la extensión a menos que el error indique un problema de carga o de compatibilidad binaria

Eliminar la configuración temporal de prueba

Tras la verificación:

  1. Elimina testsql.php, verify-php-drivers.php, y cualquier página temporal phpinfo() de la raíz del documento.

  2. Elimina credenciales temporales y entradas de reenvío de entorno.

  3. Recarga el gestor de servicios cuando cambies un override de systemd, luego reinicia PHP-FPM o el servidor web.

  4. Conserva las entradas de extensión y los paquetes instalados que la aplicación requiera.

Contenido relacionado

  • Se actualizó por última vez el