Microsoft SQLSRV 5.13 no longer supports PHP 8.1, but driver 5.12 does. Tell PIE which compatible release line to install instead of asking it for the newest version. Install both extensions only if the application uses both the procedural SQLSRV API and PDO_SQLSRV.
Last updated: November 20, 2026.
php --version
php --ini
pie install "microsoft/sqlsrv:^5.12"
pie install "microsoft/pdo_sqlsrv:^5.12"
php -m | grep -Ei '^(sqlsrv|pdo_sqlsrv)$'The quoted Composer-style constraint selects the newest stable 5.12 release compatible with the target PHP installation. PIE targets the PHP used to invoke it unless you explicitly select a different PHP configuration.
Match the driver to the PHP runtime
Microsoft’s current support matrix lists PHP 8.1 under drivers 5.10 through 5.12, but not 5.13. The 5.13 release notes explicitly say that support for PHP 8.1 and 8.2 was removed. That is why an unconstrained installer rejects the newest package on PHP 8.1.
PIE’s official usage documentation accepts vendor/package:version-constraint using Composer constraint syntax. Use ^5.12 rather than pinning an old patch unless reproducibility policy requires an exact version.
Verify prerequisites and the active configuration
Install a supported Microsoft ODBC Driver for SQL Server before the PHP extensions. Microsoft’s Linux and macOS tutorial covers the native packages and PIE workflow. If several PHP versions are installed, compare php --ini, php-config --version and the web server’s PHP runtime; a command-line installation can succeed while the site loads a different php.ini.
Load PDO before pdo_sqlsrv, restart the relevant PHP-FPM or web-server service, and confirm both modules in the same runtime that serves the application. Then run a parameterized connection test and inspect sqlsrv_errors() or the PDO exception if it fails. Do not copy a binary built for a different PHP API, architecture or thread-safety mode.
Record the chosen 5.12 constraint in deployment documentation or configuration management. Without it, a future rebuild may resolve a newer driver that no longer supports the same PHP runtime. Re-evaluate the constraint when the application upgrades PHP rather than carrying it forward indefinitely.