Installing SQL Server Drivers for PHP 8.1 on Ubuntu 20.04
Migrating from PHP 7.4 to PHP 8.1 on Ubuntu often reveals friction when dealing with Microsoft-specific extensions like sqlsrv and pdo_sqlsrv. If you are following the official Microsoft installation tutorial for Linux, you might expect a straightforward process, yet the extension frequently fails to appear in phpinfo() or php -m despite the files seemingly being present.
The core issue usually stems from how Ubuntu's package manager handles dependencies versus how the Microsoft documentation assumes they are resolved. While the official guide suggests downloading .deb packages directly from Azure, these packages often pull in specific versions of the ODBC driver or the C runtime that may conflict with the system libraries provided by Ubuntu 20.04.
Verifying the Installation State
Before attempting to fix the issue, confirm exactly what is happening on your filesystem. The fact that sqlsrv works for PHP 7.4 but not PHP 8.1 suggests the binaries are installed, but the linker or loader cannot find them for the newer version.
Run the following command to locate the compiled shared object files:
find /usr -name "sqlsrv.so" 2>/dev/null
find /usr -name "pdo_sqlsrv.so" 2>/dev/null
If these files exist, check your PHP configuration file for version 8.1. On Ubuntu, this is typically located at /etc/php/8.1/apache2/php.ini for Apache or /etc/php/8.1/cli/php.ini for the command-line interface. Ensure the lines are uncommented:
extension=sqlsrv.so
extension=pdo_sqlsrv.so
If the files exist but the extension is missing from phpinfo(), the problem is almost certainly a missing system dependency required to link against the shared library.
Resolving Dependency Conflicts
The Microsoft installation tutorial explicitly states that you must install the ODBC driver and C++ runtime libraries. However, on Ubuntu 20.04, these dependencies are often not installed by default when using the Azure-provided .deb files alone. You may encounter errors regarding libmsodbcsql18 or missing ucrt.dll.
The most robust solution is to ensure the system has the necessary Microsoft C++ redistributables and ODBC drivers installed via the package manager, rather than relying solely on the Azure installer which might skip them in a non-interactive environment.
First, update your package lists:
sudo apt-get update
Then, install the required dependencies that the SQL Server driver relies on. The specific versions depend on whether you are using the legacy ODBC driver or the newer Microsoft ODBC Driver 17/18. For Ubuntu 20.04, the unixodbc package is essential:
sudo apt-get install unixodbc
If your installation script provided a .deb file (e.g., php8.1-dev, libsybdb-dev, or specific SQL Server driver packages), ensure you run:
sudo dpkg -i <package-name>.deb
sudo apt-get install -f
The -f flag attempts to fix any broken dependencies that the initial install might have missed. If apt-get install -f fails because it cannot find a specific Microsoft library, you may need to download the specific redistributable package from Microsoft's GitHub releases or the Azure portal and run dpkg on those explicitly.
The "Missing Library" Error Pattern
A common symptom of this issue is an error message like libmsodbcsql18.so: cannot open shared object file: No such file or directory. This confirms that while the PHP extension code is loaded, it fails at runtime because the underlying C library it depends on is absent.
In these cases, simply adding the extension line to php.ini is insufficient. You must verify that the shared library paths are correct. Check if the library exists in a non-standard location:
ldconfig -p | grep sqlsrv
If nothing returns, the dynamic linker cannot find the dependency. Ensure that any custom directories where you dropped the .deb contents are added to LD_LIBRARY_PATH or linked into /etc/ld.so.conf.d/.
Apache vs. CLI Configuration
Another frequent oversight is configuring only one SAPI (Server API). If you installed the driver for the CLI but not Apache, phpinfo() might show the extension in a CLI test script but not when viewed through your web browser. Conversely, if you are checking via php -m and seeing nothing, verify that the correct php.ini is active for that specific interpreter version.
You can force PHP to load all extensions from the default directory by running:
php --ini
Compare this with the path of your custom configuration file. If you have separate configuration files (e.g., /etc/php/8.1/apache2/conf.d/), ensure the extension file is present in the conf.d directory and not just the main php.ini.
Final Verification
Once dependencies are resolved and the .so files are linked correctly, restart your web server:
sudo systemctl restart apache2
Then, create a new PHP file to test again. If the extension loads, you will see the SQL Server section in the output. If it still fails, check php_error_log or the Apache error log (/var/log/apache2/error.log) for specific messages about unresolved symbols or permission issues preventing the dynamic linker from loading the shared object.
The migration path from PHP 7.4 to 8.1 with SQL Server connectivity requires careful attention to system-level dependencies rather than just PHP configuration flags.