Tutorial de instalación de los controladores de Microsoft en Linux y macOS de PHP para SQL Server

En las instrucciones siguientes se supone que existe un entorno limpio y se explica cómo instalar PHP 8.1, Microsoft ODBC Driver, el servidor web de Apache y los controladores de Microsoft para PHP para SQL Server en Ubuntu, Red Hat, Debian, SUSE, Alpine y macOS. Estas instrucciones aconsejan instalar los controladores con PECL, pero también puede descargar los archivos binarios creados previamente de la página de proyecto de GitHub Controladores de Microsoft para PHP para SQL Server e instalarlos siguiendo las instrucciones de Carga de los controladores de Microsoft para PHP para SQL Server. Para obtener una explicación de la carga de la extensión y por qué no agregar las extensiones en php.ini, vea la sección sobre la carga de los controladores.

Las siguientes instrucciones instalan PHP 8.1 de forma predeterminada mediante pecl install si los paquetes de PHP 8.1 están disponibles. Puede que primero deba ejecutar pecl channel-update pecl.php.net. Algunas distribuciones de Linux admitidas tienen como valor predeterminado PHP 7.1 o versiones anteriores, una opción no admitida para la última versión de los controladores de PHP para SQL Server. Consulte las notas al principio de cada sección para instalar PHP 8.2 o 8.3 en su lugar.

También se incluyen instrucciones para instalar el Administrador de procesos FastCGI para PHP, PHP-FPM, en Ubuntu. PHP-FPM es necesario si se usa el servidor web nginx en lugar de Apache.

Aunque estas instrucciones contienen comandos para instalar los controladores SQLSRV y PDO_SQLSRV, estos también se pueden instalar y funcionar independientemente. Los usuarios familiarizados con la personalización de la configuración pueden ajustar estas instrucciones para que sean específicas para SQLSRV o PDO_SQLSRV. Ambos controladores tienen las mismas dependencias, excepto donde se indica a continuación.

Consulte Matriz de compatibilidad para obtener la versión más reciente de los sistemas operativos compatibles.

Nota

Asegúrese de que ha instalado la versión más reciente del controlador ODBC para garantizar un rendimiento y una seguridad óptimos. Para obtener instrucciones de instalación, consulte Instalación del controlador ODBC de Microsoft para SQL Server (Linux) o Instalación del controlador ODBC de Microsoft para SQL Server (macOS).

Instalación en Ubuntu

Nota:

Para instalar PHP 8.2 o 8.3, reemplace 8.1 por 8.2 o 8.3 en los comandos siguientes.

Paso 1. Instalación de PHP (Ubuntu)

sudo su
add-apt-repository ppa:ondrej/php -y
apt-get update
apt-get install php8.1 php8.1-dev php8.1-xml -y --allow-unauthenticated

Paso 2. Requisitos previos de instalación (Ubuntu)

Para instalar el controlador ODBC para Ubuntu, siga las instrucciones del artículo Instalación de Microsoft ODBC Driver for SQL Server (Linux). Asegúrese de instalar también el paquete unixodbc-dev. Lo usa el comando pecl para instalar los controladores de PHP.

sudo apt-get install unixodbc-dev

Paso 3. Instalación de los controladores de PHP para Microsoft SQL Server (Ubuntu)

sudo pecl install sqlsrv
sudo pecl install pdo_sqlsrv
sudo su
printf "; priority=20\nextension=sqlsrv.so\n" > /etc/php/8.1/mods-available/sqlsrv.ini
printf "; priority=30\nextension=pdo_sqlsrv.so\n" > /etc/php/8.1/mods-available/pdo_sqlsrv.ini
exit
sudo phpenmod -v 8.1 sqlsrv pdo_sqlsrv

Si solo hay una versión de PHP en el sistema, el último paso se puede simplificar a phpenmod sqlsrv pdo_sqlsrv.

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

sudo su
apt-get install libapache2-mod-php8.1 apache2
a2dismod mpm_event
a2enmod mpm_prefork
a2enmod php8.1
exit

Paso 5. Reinicio de Apache y prueba del script de ejemplo (Ubuntu)

sudo service apache2 restart

Para probar la instalación, vea Probar la instalación al final de este documento.

Instalación en Ubuntu con PHP-FPM

Nota:

Para instalar PHP 8.2 o 8.3, reemplace 8.1 por 8.2 o 8.3 en los comandos siguientes.

Paso 1. Instalación de PHP (Ubuntu con PHP-FPM)

sudo su
add-apt-repository ppa:ondrej/php -y
apt-get update
apt-get install php8.1 php8.1-dev php8.1-fpm php8.1-xml -y --allow-unauthenticated

Compruebe el estado del servicio PHP-FPM ejecutando lo siguiente:

systemctl status php8.1-fpm

Paso 2. Requisitos previos de instalación (Ubuntu con PHP-FPM)

Para instalar el controlador ODBC para Ubuntu, siga las instrucciones del artículo Instalación de Microsoft ODBC Driver for SQL Server (Linux). Asegúrese de instalar también el paquete unixodbc-dev. Lo usa el comando pecl para instalar los controladores de PHP.

Paso 3. Instalación de los controladores de PHP para Microsoft SQL Server (Ubuntu con PHP-FPM)

sudo pecl config-set php_ini /etc/php/8.1/fpm/php.ini
sudo pecl install sqlsrv
sudo pecl install pdo_sqlsrv
sudo su
printf "; priority=20\nextension=sqlsrv.so\n" > /etc/php/8.1/mods-available/sqlsrv.ini
printf "; priority=30\nextension=pdo_sqlsrv.so\n" > /etc/php/8.1/mods-available/pdo_sqlsrv.ini
exit
sudo phpenmod -v 8.1 sqlsrv pdo_sqlsrv

Si solo hay una versión de PHP en el sistema, el último paso se puede simplificar a phpenmod sqlsrv pdo_sqlsrv.

Compruebe que sqlsrv.ini y pdo_sqlsrv.ini se encuentran en /etc/php/8.1/fpm/conf.d/:

ls /etc/php/8.1/fpm/conf.d/*sqlsrv.ini

Reinicie el servicio PHP-FPM:

sudo systemctl restart php8.1-fpm

Paso 4. Instalación y configuración de nginx (Ubuntu con PHP-FPM)

sudo apt-get update
sudo apt-get install nginx
sudo systemctl status nginx

Para configurar nginx, debe editar el archivo /etc/nginx/sites-available/default. Agregue index.php a la lista que se encuentra debajo de la sección que indica # Add index.php to the list if you are using PHP:

# Add index.php to the list if you are using PHP
index index.html index.htm index.nginx-debian.html index.php;

Después, quite la marca de comentario y modifique la sección que sigue a # pass PHP scripts to FastCGI server como se indica a continuación:

# pass PHP scripts to FastCGI server
#
location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.1-fpm.sock;
}

Paso 5. Reinicio de nginx y prueba del script de ejemplo (Ubuntu con PHP-FPM)

sudo systemctl restart nginx.service

Para probar la instalación, vea Probar la instalación al final de este documento.

Instalación en Red Hat

Paso 1. Instalación de PHP (Red Hat)

Para instalar PHP en Red Hat 7, ejecute los siguientes comandos:

Nota:

Para instalar PHP 8.2 o 8.3, reemplace remi-php81 por remi-php82 o remi-php83, respectivamente, en los comandos siguientes.

sudo su
yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
yum install https://rpms.remirepo.net/enterprise/remi-release-7.rpm
subscription-manager repos --enable=rhel-7-server-optional-rpms
yum install yum-utils
yum-config-manager --enable remi-php81
yum update
# Note: The php-pdo package is required only for the PDO_SQLSRV driver
yum install php php-pdo php-pear php-devel

Para instalar PHP en Red Hat 8, ejecute los siguientes comandos:

Nota:

Para instalar PHP 8.2 o 8.3, reemplace remi-8.1 por remi-8.2 o remi-8.3, respectivamente, en los comandos siguientes.

sudo su
dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
dnf install https://rpms.remirepo.net/enterprise/remi-release-8.rpm
dnf install yum-utils
dnf module reset php
dnf module install php:remi-8.1
subscription-manager repos --enable codeready-builder-for-rhel-8-x86_64-rpms
dnf update
# Note: The php-pdo package is required only for the PDO_SQLSRV driver
dnf install php-pdo php-pear php-devel

Paso 2. Requisitos previos de instalación (Red Hat)

Para instalar el controlador ODBC para Red Hat 7 u 8, siga las instrucciones del artículo Instalación de Microsoft ODBC Driver for SQL Server (Linux). Asegúrese de instalar también el paquete unixodbc-dev. Lo usa el comando pecl para instalar los controladores de PHP.

Paso 3. Instalación de los controladores de PHP para Microsoft SQL Server (Red Hat)

sudo pecl install sqlsrv
sudo pecl install pdo_sqlsrv
sudo su
echo extension=pdo_sqlsrv.so >> `php --ini | grep "Scan for additional .ini files" | sed -e "s|.*:\s*||"`/30-pdo_sqlsrv.ini
echo extension=sqlsrv.so >> `php --ini | grep "Scan for additional .ini files" | sed -e "s|.*:\s*||"`/20-sqlsrv.ini
exit

También puede instalar desde el repositorio Remi:

sudo yum install php-sqlsrv

Paso 4. Instalación de Apache (Red Hat)

sudo yum install httpd

SELinux está instalado de forma predeterminada y se ejecuta en modo de aplicación. Para que Apache pueda conectarse a las bases de datos mediante SELinux, ejecute el siguiente comando:

sudo setsebool -P httpd_can_network_connect_db 1

Paso 5. Reinicio de Apache y prueba del script de ejemplo (Red Hat)

sudo apachectl restart

Para probar la instalación, vea Probar la instalación al final de este documento.

Instalación en Debian

Nota:

Para instalar PHP 8.2 o 8.3, reemplace 8.1 en los comandos siguientes por 8.2 o 8.3.

Paso 1. Instalación de PHP (Debian)

sudo su
apt-get install curl apt-transport-https
wget -O /etc/apt/trusted.gpg.d/php.gpg https://packages.sury.org/php/apt.gpg
echo "deb https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list
apt-get update
apt-get install -y php8.1 php8.1-dev php8.1-xml php8.1-intl

Paso 2. Requisitos previos de instalación (Debian)

Para instalar el controlador ODBC para Debian, siga las instrucciones del artículo Instalación de Microsoft ODBC Driver for SQL Server (Linux). Asegúrese de instalar también el paquete unixodbc-dev. Lo usa el comando pecl para instalar los controladores de PHP.

También es posible que deba generar la configuración regional correcta para que el resultado de PHP se muestre correctamente en un explorador. Por ejemplo, para la configuración regional UTF-8 en_US, ejecute los siguientes comandos:

sudo su
sed -i 's/# en_US.UTF-8 UTF-8/en_US.UTF-8 UTF-8/g' /etc/locale.gen
locale-gen

Es posible que tenga que agregar /usr/sbin a su $PATH, ya que el ejecutable locale-gen se encuentra allí.

Paso 3. Instalación de los controladores de PHP para Microsoft SQL Server (Debian)

sudo pecl install sqlsrv
sudo pecl install pdo_sqlsrv
sudo su
printf "; priority=20\nextension=sqlsrv.so\n" > /etc/php/8.1/mods-available/sqlsrv.ini
printf "; priority=30\nextension=pdo_sqlsrv.so\n" > /etc/php/8.1/mods-available/pdo_sqlsrv.ini
exit
sudo phpenmod -v 8.1 sqlsrv pdo_sqlsrv

Si solo hay una versión de PHP en el sistema, el último paso se puede simplificar a phpenmod sqlsrv pdo_sqlsrv. Al igual que con locale-gen, phpenmod se encuentra en /usr/sbin, por lo que es posible que tenga que agregar este directorio a su $PATH.

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

sudo su
apt-get install libapache2-mod-php8.1 apache2
a2dismod mpm_event
a2enmod mpm_prefork
a2enmod php8.1

Paso 5. Reinicio de Apache y prueba del script de ejemplo (Debian)

sudo service apache2 restart

Para probar la instalación, vea Probar la instalación al final de este documento.

Instalación en SUSE

Nota:

En las instrucciones siguientes, reemplaza <SuseVersion> por tu versión de SUSE; si usas SUSE Linux Enterprise Server 15, será SLE_15_SP3 o SLE_15_SP4 (o una versión superior). Para SUSE 12, usa SLE_12_SP5 (o una versión superior). No todas las versiones de PHP están disponibles para todas las versiones de SUSE Linux; consulta http://download.opensuse.org/repositories/devel:/languages:/php para ver qué versiones de Suse tienen la versión predeterminada de PHP disponible, o consulta http://download.opensuse.org/repositories/devel:/languages:/php:/ para ver qué otras versiones de PHP están disponibles para las versiones de SUSE.

Nota:

Los paquetes para PHP 7.4 o versiones posteriores no están disponibles para SUSE 12, a partir de hoy.

Paso 1. Instalación de PHP (SUSE)

sudo su
zypper -n ar -f https://download.opensuse.org/repositories/devel:languages:php/<SuseVersion>/devel:languages:php.repo
zypper --gpg-auto-import-keys refresh
zypper -n install php8 php8-pdo php8-devel php8-openssl

Paso 2. Requisitos previos de instalación (SUSE)

Para instalar el controlador ODBC para SUSE, siga las instrucciones del artículo Instalación de Microsoft ODBC Driver for SQL Server (Linux). Asegúrese de instalar también el paquete unixodbc-dev. Lo usa el comando pecl para instalar los controladores de PHP.

Paso 3. Instalación de los controladores de PHP para Microsoft SQL Server (SUSE)

sudo pecl install sqlsrv
sudo pecl install pdo_sqlsrv
sudo su
echo extension=pdo_sqlsrv.so >> `php --ini | grep "Scan for additional .ini files" | sed -e "s|.*:\s*||"`/pdo_sqlsrv.ini
echo extension=sqlsrv.so >> `php --ini | grep "Scan for additional .ini files" | sed -e "s|.*:\s*||"`/sqlsrv.ini
exit

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

sudo su
zypper install apache2 apache2-mod_php8
a2enmod php8
echo "extension=sqlsrv.so" >> /etc/php8/apache2/php.ini
echo "extension=pdo_sqlsrv.so" >> /etc/php8/apache2/php.ini
exit

Paso 5. Reinicio de Apache y prueba del script de ejemplo (SUSE)

sudo systemctl restart apache2

Para probar la instalación, vea Probar la instalación al final de este documento.

Instalación en Alpine

Nota:

La versión 8.1 o versiones posteriores de PHP pueden estar disponibles en los repositorios perimetrales o de prueba para Alpine. En su lugar, puede compilar PHP desde el origen.

Paso 1. Instalación de PHP (Alpine)

Los paquetes PHP para Alpine se pueden encontrar en el repositorio de edge/community. Consulte Habilitación del repositorio de la comunidad en su wiki. Agregue la línea siguiente a /etc/apk/repositories, reemplazando <mirror> por la dirección URL de un reflejo del repositorio de Alpine:

http://<mirror>/alpine/edge/community

A continuación, ejecute:

sudo su
apk update
# Note: The php*-pdo package is required only for the PDO_SQLSRV driver
# For PHP 7.*
apk add php7 php7-dev php7-pear php7-pdo php7-openssl autoconf make g++
# For PHP 8.*
apk add php8 php8-dev php8-pear php8-pdo php8-openssl autoconf make g++
# The following symbolic links are optional but useful
ln -s /usr/bin/php8 /usr/bin/php
ln -s /usr/bin/phpize8 /usr/bin/phpize
ln -s /usr/bin/pecl8 /usr/bin/pecl
ln -s /usr/bin/php-config8 /usr/bin/php-config

Paso 2. Requisitos previos de instalación (Alpine)

Para instalar el controlador ODBC para Alpine, siga las instrucciones del artículo Instalación de Microsoft ODBC Driver for SQL Server (Linux). Asegúrese de instalar también el paquete unixodbc-dev (sudo apk add unixodbc-dev). Lo usa el comando pecl para instalar los controladores de PHP.

Paso 3. Instalación de los controladores de PHP para Microsoft SQL Server (Alpine)

sudo pecl install sqlsrv
sudo pecl install pdo_sqlsrv
sudo su
echo extension=pdo_sqlsrv.so >> `php --ini | grep "Scan for additional .ini files" | sed -e "s|.*:\s*||"`/10_pdo_sqlsrv.ini
echo extension=sqlsrv.so >> `php --ini | grep "Scan for additional .ini files" | sed -e "s|.*:\s*||"`/20_sqlsrv.ini

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

# For PHP 7.*
sudo apk add php7-apache2 apache2
# For PHP 8.*
sudo apk add php8-apache2 apache2

Paso 5. Reinicio de Apache y prueba del script de ejemplo (Alpine)

sudo rc-service apache2 restart

Para probar la instalación, vea Probar la instalación al final de este documento.

Instalación en macOS

Si no lo tiene, instale brew como sigue:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Nota:

Para instalar PHP 8.2 o 8.3, reemplace php@8.1 por php@8.2 o php@8.3, respectivamente, en los comandos siguientes.

Paso 1. Instalación de PHP (macOS)

brew tap
brew tap homebrew/core
brew install php@8.1

Ahora, PHP debe estar en su ruta de acceso. Ejecute php -v para comprobar que está ejecutando la versión de PHP correcta. Si PHP no está en la ruta de acceso o no tiene la versión correcta, ejecute los siguientes comandos:

brew link --force --overwrite php@8.1

Si usa un procesador ARM64 Apple M1, es posible que tenga que establecer la ruta de acceso:

export PATH="/opt/homebrew/bin:$PATH"

Paso 2. Requisitos previos de instalación (macOS)

Para instalar el controlador ODBC para macOS, siga las instrucciones del artículo Instalación de Microsoft ODBC Driver for SQL Server (macOS).

Nota:

Si usa hardware AMR64 Apple M1, instale el Controlador ODBC de Microsoft 17.8 o una versión superior directamente sin usar el emulador Rosetta 2.

Además, puede que deba instalar las herramientas de creación de GNU:

brew install autoconf automake libtool

Paso 3. Instalación de los controladores de PHP para Microsoft SQL Server (macOS)

sudo pecl install sqlsrv
sudo pecl install pdo_sqlsrv

Si usa un procesador ARM64 Apple M1, haga lo siguiente:

sudo CXXFLAGS="-I/opt/homebrew/opt/unixodbc/include/" LDFLAGS="-L/opt/homebrew/lib/" pecl install sqlsrv
sudo CXXFLAGS="-I/opt/homebrew/opt/unixodbc/include/" LDFLAGS="-L/opt/homebrew/lib/" pecl install pdo_sqlsrv

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

Nota:

La versión más reciente de macOS 11.0 Big Sur incluye Apache 2.4 preinstalado, pero Apple también ha eliminado algunos scripts necesarios. La solución es instalar Apache 2.4 mediante Homebrew y configurarlo, pero esto está fuera del ámbito de esta guía de instalación, así que consulte Apache o Homebrew para obtener instrucciones detalladas.

brew install apache2

Para buscar el archivo de configuración de Apache, httpd.conf, para la instalación de Apache, ejecute:

/usr/local/bin/apachectl -V | grep SERVER_CONFIG_FILE

Los comandos siguientes anexan la configuración requerida a httpd.conf. Asegúrese de sustituir la ruta de acceso devuelta por el comando anterior en lugar de /usr/local/etc/httpd/httpd.conf:

echo "LoadModule php7_module /usr/local/opt/php@8.1/lib/httpd/modules/libphp7.so" >> /usr/local/etc/httpd/httpd.conf
(echo "<FilesMatch .php$>"; echo "SetHandler application/x-httpd-php"; echo "</FilesMatch>";) >> /usr/local/etc/httpd/httpd.conf

Paso 5. Reinicio de Apache y prueba del script de ejemplo (macOS)

sudo apachectl restart

Para probar la instalación, vea Probar la instalación al final de este documento.

Probar la instalación

Para probar este script de ejemplo, cree un archivo llamado testsql.php en la raíz del documento del sistema. Esta ruta de acceso es /var/www/html/ en Ubuntu, Debian y Red Hat, /srv/www/htdocs en SUSE, /var/www/localhost/htdocs en Alpine y /usr/local/var/www en macOS. Copie el script siguiente y reemplace el servidor, la base de datos, el nombre de usuario y la contraseña según proceda.

Ejemplo de SQLSRV

<?php
$serverName = "yourServername";
$connectionOptions = array(
    "database" => "yourDatabase",
    "uid" => "yourUsername",
    "pwd" => "yourPassword"
);

function exception_handler($exception) {
    echo "<h1>Failure</h1>";
    echo "Uncaught exception: " , $exception->getMessage();
    echo "<h1>PHP Info for troubleshooting</h1>";
    phpinfo();
}

set_exception_handler('exception_handler');

// Establishes the connection
$conn = sqlsrv_connect($serverName, $connectionOptions);
if ($conn === false) {
    die(formatErrors(sqlsrv_errors()));
}

// Select Query
$tsql = "SELECT @@Version AS SQL_VERSION";

// Executes the query
$stmt = sqlsrv_query($conn, $tsql);

// Error handling
if ($stmt === false) {
    die(formatErrors(sqlsrv_errors()));
}
?>

<h1> Success Results : </h1>

<?php
while ($row = sqlsrv_fetch_array($stmt, SQLSRV_FETCH_ASSOC)) {
    echo $row['SQL_VERSION'] . PHP_EOL;
}

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

function formatErrors($errors)
{
    // Display errors
    echo "<h1>SQL Error:</h1>";
    echo "Error information: <br/>";
    foreach ($errors as $error) {
        echo "SQLSTATE: ". $error['SQLSTATE'] . "<br/>";
        echo "Code: ". $error['code'] . "<br/>";
        echo "Message: ". $error['message'] . "<br/>";
    }
}
?>

Ejemplo de PDO_SQLSRV

<?php
try {
    $serverName = "yourServername";
    $databaseName = "yourDatabase";
    $uid = "yourUsername";
    $pwd = "yourPassword";
    
    $conn = new PDO("sqlsrv:server = $serverName; Database = $databaseName;", $uid, $pwd);

    // Select Query
    $tsql = "SELECT @@Version AS SQL_VERSION";

    // Executes the query
    $stmt = $conn->query($tsql);
} catch (PDOException $exception1) {
    echo "<h1>Caught PDO exception:</h1>";
    echo $exception1->getMessage() . PHP_EOL;
    echo "<h1>PHP Info for troubleshooting</h1>";
    phpinfo();
}

?>

<h1> Success Results : </h1>

<?php
try {
    while ($row = $stmt->fetch(PDO::FETCH_ASSOC)) {
        echo $row['SQL_VERSION'] . PHP_EOL;
    }
} catch (PDOException $exception2) {
    // Display errors
    echo "<h1>Caught PDO exception:</h1>";
    echo $exception2->getMessage() . PHP_EOL;
}

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

Dirija el explorador a https://localhost/testsql.php (https://localhost:8080/testsql.php en macOS). Ahora podrá conectarse a la base de datos de SQL Server o Azure SQL. Si no ve un mensaje de confirmación que muestre información de la versión de SQL, puede seguir algunos pasos básicos para solucionar problemas mediante la ejecución del script desde la línea de comandos:

php testsql.php

Si la ejecución desde la línea de comandos se realiza correctamente pero no se muestra nada en el explorador, compruebe los archivos de registro de Apache. Si necesita más ayuda, consulte Recursos de soporte técnico para conocer los recursos que pueden serle de ayuda.

Consulte también

Introducción a los controladores de Microsoft para PHP para SQL Server

Carga de los controladores de Microsoft para PHP para SQL Server

Requisitos del sistema para los controladores de Microsoft para PHP para SQL Server