22.9.3.4. Installing/Configuring

22.9.3.4.1. Requirements

In order to have these functions available, you must compile PHP with support for the mysqli extension.

Note

The mysqli extension is designed to work with MySQL version 4.1.13 or newer, or 5.0.7 or newer. For previous versions, please see the MySQL extension documentation.

22.9.3.4.2. Installation

The mysqli extension was introduced with PHP version 5.0.0. The MySQL Native Driver was included in PHP version 5.3.0.

22.9.3.4.2.1. Installation on Linux

The common Unix distributions include binary versions of PHP that can be installed. Although these binary versions are typically built with support for MySQL extensions enabled, the extension libraries themselves may need to be installed using an additional package. Check the package manager than comes with your chosen distribution for availability.

Unless your Unix distribution comes with a binary package of PHP with the mysqli extension available, you will need to build PHP from source code. Building PHP from source allows you to specify the MySQL extensions you want to use, as well as your choice of client library for each extension.

The MySQL Native Driver is the recommended option, as it results in improved performance and gives access to features not available when using the MySQL Client Library. Refer to What is PHP's MySQL Native Driver? for a brief overview of the advantages of MySQL Native Driver.

The /path/to/mysql_config represents the location of the mysql_config program that comes with MySQL Server.

Table 22.43. mysqli compile time support matrix

PHP Version	Default	Configure Options:mysqlnd	Configure Options: `libmysqlclient`	Changelog
5.0.x, 5.1.x, 5.2.x	libmysqlclient	Not Available	`--with-mysqli=/path/to/mysql_config`
5.3.x	libmysqlclient	`--with-mysqli=mysqlnd`	`--with-mysqli=/path/to/mysql_config`	mysqlnd is now supported
5.4.x	mysqlnd	`--with-mysqli`	`--with-mysqli=/path/to/mysql_config`	mysqlnd is now the default

Note that it is possible to freely mix MySQL extensions and client libraries. For example, it is possible to enable the MySQL extension to use the MySQL Client Library (libmysqlclient), while configuring the mysqli extension to use the MySQL Native Driver. However, all permutations of extension and client library are possible.

The following example builds the MySQL extension to use the MySQL Client Library, and the mysqli and PDO MYSQL extensions to use the MySQL Native Driver:

./configure --with-mysql=/usr/bin/mysql_config  \--with-mysqli=mysqlnd \--with-pdo-mysql=mysqlnd[other options]

22.9.3.4.2.2. Installation on Windows Systems

On Windows, PHP is most commonly installed using the binary installer.

22.9.3.4.2.2.1. PHP 5.0, 5.1, 5.2

Once PHP has been installed, some configuration is required to enable mysqli and specify the client library you want it to use.

The mysqli extension is not enabled by default, so the php_mysqli.dll DLL must be enabled inside of php.ini. In order to do this you need to find the php.ini file (typically located in c:\php), and make sure you remove the comment (semi-colon) from the start of the line extension=php_mysqli.dll, in the section marked [PHP_MYSQLI].

Also, if you want to use the MySQL Client Library with mysqli, you need to make sure PHP can access the client library file. The MySQL Client Library is included as a file named libmysql.dll in the Windows PHP distribution. This file needs to be available in the Windows system's PATH environment variable, so that it can be successfully loaded. See the FAQ titled "How do I add my PHP directory to the PATH on Windows" for information on how to do this. Copying libmysql.dll to the Windows system directory (typically c:\Windows\system) also works, as the system directory is by default in the system's PATH. However, this practice is strongly discouraged.

As with enabling any PHP extension (such as php_mysqli.dll), the PHP directive extension_dir should be set to the directory where the PHP extensions are located. See also the Manual Windows Installation Instructions. An example extension_dir value for PHP 5 is c:\php\ext.

Note

If when starting the web server an error similar to the following occurs: "Unable to load dynamic library './php_mysqli.dll'", this is because php_mysqli.dll and/or libmysql.dll cannot be found by the system.

22.9.3.4.2.2.2. PHP 5.3.0+

On Windows, for PHP versions 5.3 and newer, the mysqli extension is enabled and uses the MySQL Native Driver by default. This means you don't need to worry about configuring access to libmysql.dll.

22.9.3.4.3. Runtime Configuration

The behaviour of these functions is affected by settings in php.ini.

Table 22.44. MySQLi Configuration Options

Name	Default	Changeable	Changelog
mysqli.allow_local_infile	"1"	PHP_INI_SYSTEM	Available since PHP 5.2.4.
mysqli.allow_persistent	"1"	PHP_INI_SYSTEM	Available since PHP 5.3.0.
mysqli.max_persistent	"-1"	PHP_INI_SYSTEM	Available since PHP 5.3.0.
mysqli.max_links	"-1"	PHP_INI_SYSTEM	Available since PHP 5.0.0.
mysqli.default_port	"3306"	PHP_INI_ALL	Available since PHP 5.0.0.
mysqli.default_socket	NULL	PHP_INI_ALL	Available since PHP 5.0.0.
mysqli.default_host	NULL	PHP_INI_ALL	Available since PHP 5.0.0.
mysqli.default_user	NULL	PHP_INI_ALL	Available since PHP 5.0.0.
mysqli.default_pw	NULL	PHP_INI_ALL	Available since PHP 5.0.0.
mysqli.reconnect	"0"	PHP_INI_SYSTEM	Available since PHP 4.3.5.
mysqli.cache_size	"2000"	PHP_INI_SYSTEM	Available since PHP 5.3.0.

For further details and definitions of the preceding PHP_INI_* constants, see the chapter on configuration changes.

Here's a short explanation of the configuration directives.

mysqli.allow_local_infile integer: Allow accessing, from PHP's perspective, local files with LOAD DATA statements
mysqli.allow_persistent integer: Enable the ability to create persistent connections using mysqli_connect.
mysqli.max_persistent integer: Maximum of persistent connections that can be made. Set to 0 for unlimited.
mysqli.max_links integer: The maximum number of MySQL connections per process.
mysqli.default_port integer: The default TCP port number to use when connecting to the database server if no other port is specified. If no default is specified, the port will be obtained from the MYSQL_TCP_PORT environment variable, the mysql-tcp entry in /etc/services or the compile-time MYSQL_PORT constant, in that order. Win32 will only use the MYSQL_PORT constant.
mysqli.default_socket string: The default socket name to use when connecting to a local database server if no other socket name is specified.
mysqli.default_host string: The default server host to use when connecting to the database server if no other host is specified. Doesn't apply in safe mode.
mysqli.default_user string: The default user name to use when connecting to the database server if no other name is specified. Doesn't apply in safe mode.
mysqli.default_pw string: The default password to use when connecting to the database server if no other password is specified. Doesn't apply in safe mode.
mysqli.reconnect integer: Automatically reconnect if the connection was lost.
mysqli.cache_size integer: Available only with mysqlnd.

Users cannot set MYSQL_OPT_READ_TIMEOUT through an API call or runtime configuration setting. Note that if it were possible there would be differences between how libmysqlclient and streams would interpret the value of MYSQL_OPT_READ_TIMEOUT.

22.9.3.4.4. Resource Types

This extension has no resource types defined.