Controladores de Microsoft para PHP para SQL Server

Descargar controlador PHP

Los controladores Microsoft para PHP para SQL Server son extensiones de PHP que permiten leer y escribir datos en el Microsoft SQL Motor de base de datos desde scripts PHP. El paquete incluye dos controladores que encapsulan el mismo controlador Microsoft ODBC para SQL Server y comparten las mismas opciones de conexión, así que puedes elegir la API que se adapte a tu base de código:

• SQLSRV expone una API procedural (sqlsrv_*funciones) adaptada a las características de SQL Server.
• PDO_SQLSRV implementa la interfaz PHP Data Objects (PDO), por lo que el código que ya utiliza PDO para otras bases de datos puede dirigirse a SQL Server con cambios mínimos.

Ambos controladores se conectan a Azure SQL Database, SQL database en Microsoft Fabric, Azure SQL Managed Instance y todas las versiones y ediciones compatibles de SQL Server (incluidas las ediciones Express). Utilizan flujos PHP para mover grandes valores binarios y de caracteres sin cargarlos completamente en memoria.

Elija el punto de partida.

Objetivo	Comience aquí
Configura un entorno de desarrollo PHP y ejecuta tu primera consulta	Paso 1: Configurar el entorno de desarrollo, luego Paso 2: Crear una base de datos SQL y Paso 3: Prueba de concepto conectándose a SQL usando PHP.
Instala el controlador en Linux o macOS	Tutorial de instalación para Linux y macOS y descarga los controladores de Microsoft para PHP para SQL Server.
Conéctate a Azure SQL con autenticación sin contraseña	Conéctate usando las opciones de autenticación y conexión de Microsoft Entra.
Haz que una aplicación existente sea resistente a fallos transitorios	Resiliencia de conexiones inactivas y Paso 4: Conectarse de forma resiliente a SQL con PHP.
Decide entre SQLSRV y PDO_SQLSRV	Resumen de los controladores de Microsoft para PHP para SQL Server y Comparando funciones de ejecución.
Diagnosticar un problema de instalación, conexión o consulta	Resolución de problemas, gestión de errores y advertencias, y actividad de registro.
Haz que una app existente sea más rápida	Ajuste de rendimiento.

Conexión rápida

El siguiente fragmento es la conexión de extremo a extremo más corta que una instalación PHP funcional puede ejecutar contra SQL Server o Azure SQL. Úsala para confirmar que tu controlador, las dependencias ODBC y la ruta de red están conectadas antes de pasar a la línea base de producción en la siguiente sección.

<?php
$server   = getenv('SQL_SERVER')   ?: 'localhost';
$database = getenv('SQL_DATABASE') ?: 'master';
$user     = getenv('SQL_USER');
$password = getenv('SQL_PASSWORD');

$dsn = "sqlsrv:Driver={ODBC Driver 18 for SQL Server};Server=$server;Database=$database;Encrypt=true";
$pdo = new PDO($dsn, $user, $password, [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
]);

foreach ($pdo->query('SELECT @@VERSION AS version') as $row) {
    echo $row['version'], PHP_EOL;
}

Para una conexión sin contraseña contra Azure SQL, añade Authentication=ActiveDirectoryMsi (identidad gestionada) u otro Authentication valor a la DSN y elimina los $user/$password argumentos. La línea base de producción que sigue amplía el mismo patrón con repeticiones, tiempos de espera y diagnósticos.

Para un SQL Server local que utiliza un certificado autofirmado, Encrypt=true falla la validación. Añade TrustServerCertificate=true solo para desarrollo local. Consulta los errores de certificado TLS para las alternativas de producción.

Línea base de producción para Azure SQL

Utiliza este fragmento como punto de partida para una conexión de Azure SQL orientada a la producción con el controlador de PDO_SQLSRV. Lee el servidor y la base de datos a partir de variables de entorno (por ejemplo, la configuración de la app de Azure App Service), se autentica con una identidad gestionada, activa la Seguridad de la Capa de Transporte (TLS) con validación de certificados de servidor, establece un tiempo de espera de inicio de sesión que cubre un conmutamiento por error de arranque en frío y establece ConnectRetryCount y ConnectRetryInterval para la resiliencia de la conexión inactiva de SQL Server. El sistema a nivel connectWithRetry de aplicación y queryWithRetry los auxiliares envuelve tanto la conexión inicial como cada sentencia con un backoff exponencial acotado, y separan los errores de conexión transitoria (que requieren una conexión nueva) de los errores de consulta transitoria (que reutilizan la misma conexión).

Requiere PHP 8.0 y versiones posteriores, la extensión PDO_SQLSRV y Microsoft controlador ODBC para SQL Server 17.3.1.1 y versiones posteriores para Authentication=ActiveDirectoryMsi. Para la lista completa de valores soportadosAuthentication, véase Connect usando autenticación Microsoft Entra.

<?php
declare(strict_types=1);

// Transient errors that require a fresh connection to recover. SQLSTATE values
// starting with '08' cover ODBC connection-established and connection-broken
// states (for example, 08001, 08S01).
const CONNECT_RETRY_SQLSTATE_PREFIX = '08';

// SQL Server error codes that are transient regardless of when they surface:
// 1205 (deadlock victim), 1222 (lock request timeout), and the Azure SQL
// throttling, mid-query failover, and "database not currently available"
// codes that arrive with SQLSTATE HY000.
const TRANSIENT_SERVER_ERROR_CODES = [1205, 1222, 40501, 40613, 40197, 10928, 10929, 49918];

/**
 * Open a connection, retrying transient failures with exponential backoff.
 */
function connectWithRetry(string $dsn, array $options, int $maxAttempts = 3): PDO
{
    for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
        try {
            $pdo = new PDO($dsn, null, null, $options);
            error_log(sprintf('connected on attempt %d/%d', $attempt, $maxAttempts));
            return $pdo;
        } catch (PDOException $e) {
            $sqlstate = (string) $e->getCode();
            $driverCode = isset($e->errorInfo[1]) ? (int) $e->errorInfo[1] : 0;
            $isTransient = str_starts_with($sqlstate, CONNECT_RETRY_SQLSTATE_PREFIX)
                || in_array($driverCode, TRANSIENT_SERVER_ERROR_CODES, true);
            if (!$isTransient || $attempt === $maxAttempts) {
                error_log(sprintf('connect failed on attempt %d/%d: %s', $attempt, $maxAttempts, $e->getMessage()));
                throw $e;
            }
            $delay = 2 ** ($attempt - 1); // 1, 2, 4 seconds
            error_log(sprintf('connect attempt %d hit transient %s/%d; retrying in %d seconds', $attempt, $sqlstate, $driverCode, $delay));
            sleep($delay);
        }
    }
    throw new RuntimeException('connectWithRetry exhausted retries');
}

/**
 * Run a parameterized query, retrying transient statement failures on the same
 * connection. Deadlocks (1205) roll back the transaction before the driver sees
 * the error, so rerunning a single statement is safe. If the statement was part
 * of a multistatement transaction, wrap the whole transaction in your own retry
 * loop so earlier statements replay too.
 */
function queryWithRetry(PDO $pdo, string $sql, array $params = [], int $maxAttempts = 3): PDOStatement
{
    for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
        try {
            $stmt = $pdo->prepare($sql);
            $stmt->execute($params);
            return $stmt;
        } catch (PDOException $e) {
            $driverCode = isset($e->errorInfo[1]) ? (int) $e->errorInfo[1] : 0;
            $isTransient = in_array($driverCode, TRANSIENT_SERVER_ERROR_CODES, true);
            if (!$isTransient || $attempt === $maxAttempts) {
                error_log(sprintf('query failed on attempt %d/%d: %s', $attempt, $maxAttempts, $e->getMessage()));
                throw $e;
            }
            $delay = 2 ** ($attempt - 1);
            error_log(sprintf('query attempt %d hit transient code %d; retrying in %d seconds', $attempt, $driverCode, $delay));
            sleep($delay);
        }
    }
    throw new RuntimeException('queryWithRetry exhausted retries');
}

// Load endpoint details from application configuration. In Azure App Service,
// these can come from app settings or Key Vault-backed settings.
$server = getenv('SQL_SERVER') ?: null;
$database = getenv('SQL_DATABASE') ?: null;

if ($server === null || $database === null) {
    throw new RuntimeException('Set SQL_SERVER and SQL_DATABASE in your application configuration.');
}

$dsn = sprintf(
    'sqlsrv:Driver={ODBC Driver 18 for SQL Server};Server=%s;Database=%s;'
    . 'Encrypt=true;TrustServerCertificate=false;'
    . 'LoginTimeout=90;Authentication=ActiveDirectoryMsi;'
    . 'ConnectRetryCount=5;ConnectRetryInterval=15;'
    . 'MultiSubnetFailover=true;',
    $server,
    $database
);

$options = [
    PDO::ATTR_ERRMODE               => PDO::ERRMODE_EXCEPTION,
    PDO::ATTR_DEFAULT_FETCH_MODE    => PDO::FETCH_ASSOC,
    PDO::ATTR_EMULATE_PREPARES      => false,
    PDO::SQLSRV_ATTR_QUERY_TIMEOUT  => 30,
];

$pdo = connectWithRetry($dsn, $options);
$stmt = queryWithRetry($pdo, 'SELECT TOP (?) name FROM sys.databases ORDER BY name', [5]);
foreach ($stmt as $row) {
    echo $row['name'], PHP_EOL;
}

Este fragmento de código está optimizado para grupos de conmutación por error de Azure SQL Database y Azure SQL Managed Instance.

• Driver={ODBC Driver 18 for SQL Server} Pinea el controlador ODBC 18. Si el host también tiene ODBC 17 instalado, PDO_SQLSRV puede vincularse a ODBC 17. Las versiones antiguas de 17.x rechazan valores más Authentication recientes; por ejemplo, Authentication=ActiveDirectoryMsi requieren ODBC 17.3.1.1 o una versión posterior. Ver Valor inválido especificado para el atributo de cadena de conexión 'Authentication'.

• ConnectRetryCounty ConnectRetryInterval son palabras clave ODBC de cadena de conexión que permiten la resiliencia de la conexión inactiva en SQL Server: el controlador reconecta de forma transparente una conexión inactiva rota. Esto es distinto del nivel queryWithRetryde aplicación , que intenta de nuevo una sentencia que falla con un error transitorio como un bloqueo o un tiempo de espera de consulta. Los dos son complementarios, así que quédate con ambos. Asegúrate LoginTimeout de que al ConnectRetryCount * ConnectRetryInterval menos la ruta de reconexión en reposo tenga todo su presupuesto; la muestra usa 90 segundos para cubrir 5 × 15 segundos de intentos más margen para el inicio de sesión inicial en un conmutador en frío.

• Complementa las llamadas a nivel error_log() de aplicación con diagnósticos del lado del conductor. Para PDO_SQLSRV, establecer pdo_sqlsrv.log_severity ( php.ini establecible solo en la inicialización); para SQLSRV, llamar sqlsrv_configure("LogSubsystems", ...) en tiempo de ejecución. Para más información, consulte Actividad de registro.

  ; php.ini - enable PDO_SQLSRV driver diagnostics alongside the application-level
  ; error_log() calls in the sample. Use 1 (errors) in production; -1 (all) is
  ; useful during triage but very chatty.
  [pdo_sqlsrv]
  pdo_sqlsrv.log_severity = 1
  

• Para una identidad gestionada asignada por el usuario , pasa el ID de la identidad como argumento de $username PDO (new PDO($dsn, $identityId, null, $options)). Utiliza el ID de cliente de la identidad en Azure App Service o Azure Container Instance; de lo contrario, utiliza su ID de objeto. Los controladores PHP heredan este comportamiento del controlador subyacente de Microsoft ODBC para SQL Server; para más información, consulte Uso de Microsoft Entra ID con el controlador ODBC. PDO_SQLSRV rechaza UID dentro de la propia DSN, así que usa la ranura del constructor. Pasar null como usuario (como hace la muestra) selecciona la identidad gestionada asignada por el sistema del host de Azure. Para SQLSRV (procedural), pasa UID el array de opciones de conexión.

• Configura MultiSubnetFailover=true cuando te conectas a un oyente de grupo de conmutación por fallo, un oyente de grupo de disponibilidad o un extremo de instancia de clúster de conmutación por fallo. Configurarlo mejora el rendimiento de la conexión tanto para los oyentes de grupos de disponibilidad de una sola subred como de múltiples subred. Para más información, consulte Soporte para Alta Disponibilidad, recuperación ante desastres.

• Para un escalamiento de lectura o un secundario legible, añade ApplicationIntent=ReadOnly al Nombre de la Fuente de Datos (DSN).

• Para nubes soberanas donde el certificado Subject Alternative Name (SAN) no incluye el host al que te conectas, añade HostNameInCertificate al DSN (por ejemplo, *.database.usgovcloudapi.net para Azure Government).

• El controlador se basa en el controlador subyacente de Microsoft ODBC para SQL Server para la adquisición de tokens. Los flujos de identidad gestionada, principal de servicio y token-acceso pasan todos por ODBC. Para obtener más información, vea Uso de Microsoft Entra ID con ODBC Driver.

• Para mayor seguridad y portabilidad entre entornos, mantén la información de conexión fuera de tu código. Guarda la información de conexión en el sistema de configuración de tu aplicación y utiliza Azure Key Vault para valores sensibles y ajustes de conexión gestionados centralmente.

• La conexión SQLSRV equivalente utiliza sqlsrv_connect($server, ['Database' => $database, 'Encrypt' => true, 'Authentication' => 'ActiveDirectoryMsi', /* ... */]) y devuelve un recurso. El patrón de reintento es el mismo: detectar una false devolución de sqlsrv_connect, inspeccionar sqlsrv_errors() el estado SQL, y retroceder antes de intentarlo de nuevo. Para un ejemplo resuelto, véase el Paso 4: Conectarse resilientemente a SQL con PHP.

• Los ayudantes de reintento leen $e->errorInfo[1] protegidos por isset(). PDOException::$errorInfo se declara como ?array y por defecto se vuelve , nullpor lo que la comprobación defensiva vuelve a un código de controlador de 0 y deja que el prefijo SQLSTATE 08 decida si intenta de nuevo.

Para obtener más información sobre cada parte de esta configuración, consulte:

• Opciones de conexión
• Conéctate usando la autenticación de Microsoft Entra
• Resiliencia de la conexión en reposo
• Conexión a Microsoft Azure SQL Database
• Soporte para Alta Disponibilidad, recuperación ante desastres

Para consultar el catálogo de errores transitorios de Azure SQL, consulte Solucionar errores transitorios de conexión.

Características clave

• Dos APIs, un paquete de controladores: SQLSRV procedural para código SQL Server-primero, o PDO_SQLSRV para código PDO portátil.
• Soporte para plataformas amplias: Funciona en Windows, Linux y macOS con versiones compatibles con PHP.
• Conexiones cifradas: Conexiones cifradas TLS mediante Encrypt=true, con la validación del certificado del servidor controlada por TrustServerCertificate.
• Autenticación Microsoft Entra ID: Las conexiones sin contraseña con identidad gestionada, principal de servicio y token de acceso fluyen a través del controlador Microsoft ODBC subyacente para SQL Server.
• Always Encrypted: cifrado del lado cliente para columnas confidenciales, con enclaves seguros opcionales para operaciones en contexto.
• Resiliencia de conexión: La conexión inactiva incorporada se reintenta con ConnectRetryCount y ConnectRetryInterval.
• Flujos PHP: Leen y escriben grandes valores binarios y de caracteres como flujos en lugar de cargarlos en memoria.
• Soporte para tipos de datos de Rich SQL Server: datetimeoffset, parámetros de valoración en tabla, nvarchar y Unicode con PDO::SQLSRV_ENCODING_UTF8.

Primeros pasos

Artículo	Descripción
Requisitos del sistema	Compatibles con PHP, sistemas operativos y versiones de SQL Server.
Matriz de compatibilidad	Matriz detallada de compatibilidad para las versiones de controladores PHP.
Descarga los controladores de Microsoft para PHP para SQL Server	Enlaces de descarga y libera artefactos.
Tutorial de instalación para Linux y macOS	Instala el controlador y sus requisitos previos de ODBC en Linux y macOS.
Carga de los drivers	Activa las extensiones en php.ini.
Empezando con el controlador SQL de PHP	Guía de principio a fin que une los cuatro pasos de inicio.
Visión general del controlador SQL PHP	¿Qué contiene el paquete y cuándo elegir SQLSRV o PDO_SQLSRV.

Configuración y conexión

Artículo	Descripción
Conexión al servidor	Abre una conexión a una instancia de SQL Server desde PHP.
Opciones de conexión	Referencia completa para palabras clave de conexión, valores predeterminados y cómo configurarlos.
Conexión a Microsoft Azure SQL Database	Conecta una aplicación PHP a Azure SQL Database.
Conéctate en un puerto especificado	Apunta a un puerto TCP no predeterminado.
Agrupación de conexiones	Reutiliza conexiones ODBC entre peticiones PHP.
Desactivar múltiples conjuntos activos de resultados (MARS)	Desactiva MARS para compatibilidad.
Compatibilidad con LocalDB	Conéctate a una instancia de SQL Server LocalDB.
Soporte para Alta Disponibilidad, recuperación ante desastres	Escuchas de grupos de disponibilidad y conmutación por error entre varias subredes.
Resiliencia de la conexión en reposo	Reconexión automática por conexiones rotas en reposo.

Authenticate

Artículo	Descripción
Conéctate usando la autenticación de Microsoft Entra	Identidad gestionada, principal de servicio, token de acceso y flujos de contraseña.
Conéctate usando autenticación SQL Server	Usa un inicio de sesión SQL con nombre de usuario y contraseña.
Conéctate usando autenticación de Windows	Utiliza autenticación integrada de Windows en hosts unidos al dominio.

Secure

Artículo	Descripción
Consideraciones de seguridad	Modelo de amenazas y orientación en profundidad de defensa para aplicaciones PHP.
Siempre cifrado con los controladores PHP	Configure el cifrado del lado cliente para columnas confidenciales.
Always Encrypted con enclaves seguros	Habilitar operaciones enriquecidas en columnas cifradas con enclaves seguros.

Recuperar y actualizar datos

Artículo	Descripción
Guía de programación	Guía de programación de extremo a extremo para ambos controladores.
Comparando funciones de ejecución	Elige la función de ejecución adecuada para tu carga de trabajo.
Ejecución directa y preparada de sentencias (PDO_SQLSRV)	Cuándo usar ejecución directa frente a declaraciones preparadas.
Recuperación de datos	Busca filas, columnas y valores de streaming.
Actualización de datos	Inserta, actualiza y elimina filas.
Realizar consultas parametrizadas	Vincula parámetros para protegerte contra la inyección SQL.
Enviar datos como flujo	Transmite valores binarios y de caracteres grandes a SQL Server.
Ejecutar transacciones	Agrupar estados en transacciones atómicas.
Utiliza parámetros con valores de tabla	Pasa un TABLE parámetro a un procedimiento almacenado.
Especifica un tipo de cursor y selecciona filas	Elige cursores solo hacia adelante, estáticos, dinámicos o de conjunto de teclas.

Tipos de datos

Artículo	Descripción
Conversión de tipos de datos	Cómo el controlador asigna los tipos PHP a los tipos de SQL Server.
Tipos de datos predeterminados de SQL Server	Tipo de SQL Server por defecto para cada valor PHP.
Tipos de datos PHP por defecto	Tipo de PHP predeterminado para cada tipo de columna de SQL Server.
Especificar tipos de datos de SQL Server (SQLSRV)	Anula el tipo de SQL Server al vincular parámetros.
Especificar tipos de datos PHP	Anula el tipo PHP al buscar el dispositivo.
Enviar y recuperar datos UTF-8	Úsalo PDO::SQLSRV_ENCODING_UTF8 para viajes de ida y vuelta Unicode.
Enviar y recuperar datos ASCII en Linux y macOS	Gestiona los viajes de ida y vuelta ASCII en hosts que no sean Windows.
Formatear decimales y dinero (SQLSRV)	Formatea las columnas decimales y de dinero con el controlador SQLSRV.
Formato decimales y dinero (PDO_SQLSRV)	Formatea las columnas decimal y de dinero con el controlador PDO_SQLSRV.
Configuración de localidades no del sistema	Separadores decimales localizados y otras consideraciones locales.

Errores y diagnósticos

Artículo	Descripción
Errores de manejo y advertencias	Manejo de errores y advertencias en ambos pilotos.
Configurar la gestión de errores y advertencias (SQLSRV)	Ajusta cómo el controlador SQLSRV informa de errores y advertencias.
Gestionar errores y advertencias (SQLSRV)	Inspecciona los errores devueltos por las funciones SQLSRV.
Actividad forestal	Activa el registro de controladores para la captura de diagnóstico.

Despliegue y operación

Artículo	Descripción
Ajuste del rendimiento	Gestión de conexiones, agrupación, sentencias preparadas, cursores, memoria y monitorización en el lado del servidor.
Solución de problemas	Diagnostica problemas comunes de instalación, conexión, consulta, tipo de datos, transacción y contenedor.

Reference

Artículo	Descripción
Referencia de la API de controladores SQLSRV	Todas las sqlsrv_* funciones, parámetros y valores de retorno.
PDO_SQLSRV referencia del piloto	Métodos PDO y PDOStatement soportados por el controlador PDO_SQLSRV.
Constantes	Constantes expuestas por los controladores, incluyendo constantes de tipo y codificación.

Tareas relacionadas

Artículo	Descripción
Notas de lanzamiento	Historial de versiones por versión con nuevas funciones, correcciones de errores, cambios de soporte en la plataforma y enlaces de descarga.
Sobre ejemplos de código en la documentación	Convenciones utilizadas por los ejemplos de código de esta sección.
Ejemplos de código para el controlador SQL PHP	Ejemplos de aplicaciones de extremo a extremo para SQLSRV y PDO_SQLSRV.
Recursos de soporte técnico	Comunidad y canales de apoyo.

Contenido relacionado

• Controladores de Microsoft para PHP para SQL Server en GitHub
• controlador ODBC de Microsoft para SQL Server
• Controladores de SQL Server