PHP 8.2: MySQLi can no longer be compiled with libmysqli

Version8.2
TypeRemoval

PHP historically supported two libraries to connect MySQL databases. For both mysqli extension and pdo_mysql extensions, these libraries provided underlying functionality for connectivity, querying, retrieval, and processing of retrieved data.

  • mysqlnd (MySQL Native Driver): Part of PHP project, and provides modern functionality such as returning native PHP data types (such as integers), follows same memory management as PHP core, and is generally more feature-rich.
  • libmysql: An external library provided by MySQL, and does not provide all the features of mysqlnd, and has the disadvantages of an external library, such as not being able to properly trace or control memory usage, and potential library version mismatches. Further, libmysql is not available on Windows systems.

Since PHP 5.4, mysqlnd is the default library, but it was possible to compile mysqli and pdo_mysql extensions with libmysql with a compile-time configuration flag.

Since PHP 8.2 and later, compiling mysqli extension with libmysql is no longer supported.

Note that it is still possible to compile pdo_mysql extension with libmysql, the support for libmysql might be dropped in the pdo_mysql extension in the future.

Attempting to compile mysqli with the --with-mysqli=FILE option with a value results in a configuration error at compiler configuration step:

./configure --with-mysqli=FOO
Linking mysqli against external library is no longer supported

It is unlikely that a significant number of PHP builds are affected by this change. Due to the feature-rich and more secure nature of mysqlnd, it has long been used as the default MySQL library for PHP.

The most prominent features that libmysql supported, but not provided by mysqlnd are:

  • Support for automatic reconnecting. mysqlnd intentionally avoids this feature due to the unpredictable dangerous nature of this feature.
  • Authentication via LDAP and SASL.

LDAP/SASL authentication support might be added to mysqlnd to which a pull-request exists.

It is decided that libmysql-style auto reconnect will not be added to mysqlnd. Generally, a dropped database connection results in an exception being thrown, at which point the application and either attempt to re-connect, or gracefully shut down the application. Applications that previously depended on the automatic re-connect functionality now need to handle the potential exceptions and attempt to re-connect manually.

mysqli::ping() and mysqli_ping()

mysqli::ping() and mysqli_ping() functions supported automatic re-connection if the mysqli.reconnect INI is directive enabled.

With the libmysql supported dropped, these functions no longer provide any auto-connect feature whatsoever.

mysqli.reconnect INI directive

libmysql-specific mysqli.reconnect INI directive is removed in PHP 8.2 and later. This value was used in the ping functionality that no longer auto-connects.

Setting this directive does not cause any errors or warnings, and it has no effect either.

mysqli_driver::$reconnect Property is Removed

MySQLi extension provides a mysqli_driver class to fetch the driver information (such as client version), as well as to configure certain characteristics of the driver, such as the reconnect feature only provided by the now-removed libmysql library.

The mysqli_driver::$reconnect property is similar to the mysqli.reconnect INI directive.

In PHP 8.2 and later, the mysqli_driver::$reconnect property is removed. Attempting to retrieve it results in an undefined property warning. Trying to set it has no impact on the driver behavior, and results in a deprecation notice on dynamic properties.

Backwards Compatibility Impact

It is unlikely that the removal of libmysql affects any common PHP builds.

In cPanel, the mysqli extension compiled with mysqlnd requires enabling the extensions named mysqlnd and nd_mysql from the cPanel control panel.

The most likely incompatibility occurred due to this change is the lack of auto-reconnect feature. The libmysql auto-reconnect feature is somewhat unpredictable to begin with, and the ideal upgrade path would be to catch mysqli exceptions, and re-establish the connection manually, or to gracefully quit the application.

RFC Discussion Implementation