PHP mysqli options() Function
The options() / mysqli_options() function is used to set extra connect options and affect behavior for a connection.
Note: This function should be called after init() and before real_connect().
Syntax
Object oriented style:
Procedural style:
Parameter Values
- MYSQLI_OPT_CONNECT_TIMEOUT — Set connection timeout in seconds
- MYSQLI_OPT_LOCAL_INFILE — Enable/Disable use of LOAD LOCAL INFILE
- MYSQLI_INIT_COMMAND — Set a command to execute after connecting to MySQL server
- MYSQLI_READ_DEFAULT_FILE — Set read options from named file instead of my.cnf
- MYSQLI_READ_DEFAULT_GROUP — Set read options from named group from my.cnf or the file specified in MYSQLI_READ_DEFAULT_FILE
- MYSQLI_SERVER_PUBLIC_KEY — Set RSA public key file used with SHA-256 based authentication
- MYSQLI_OPT_NET_CMD_BUFFER_SIZE — only for mysqlnd
- MYSQLI_OPT_NET_READ_BUFFER_SIZE — only for mysqlnd
- MYSQLI_OPT_INT_AND_FLOAT_NATIVE — only for mysqlnd
- MYSQLI_OPT_SSL_VERIFY_SERVER_CERT — only for mysqlnd
Technical Details
| Return Value: | TRUE on success. FALSE on failure |
|---|---|
| PHP Version: | 5+ |
| PHP Changelog: | PHP 5.5: Added MYSQLI_SERVER_PUBLIC_KEY option PHP 5.3: Added MYSQLI_OPT_INT_AND_FLOAT_NATIVE, MYSQLI_OPT_NET_CMD_BUFFER_SIZE, MYSQLI_OPT_NET_READ_BUFFER_SIZE, and MYSQLI_OPT_SSL_VERIFY_SERVER_CERT options |
Example — Procedural style
Set extra connect options:
// Specify connection timeout
mysqli_options($con, MYSQLI_OPT_CONNECT_TIMEOUT, 10);
// Specify read options from named file instead of my.cnf
mysqli_options($con, MYSQLI_READ_DEFAULT_FILE, «myfile.cnf»);
mysqli_options
Used to set extra connect options and affect behavior for a connection.
This function may be called multiple times to set several options.
mysqli_options() should be called after mysqli_init() and before mysqli_real_connect() .
Parameters
Procedural style only: A mysqli object returned by mysqli_connect() or mysqli_init()
The option that you want to set. It can be one of the following values:
| Name | Description |
|---|---|
| MYSQLI_OPT_CONNECT_TIMEOUT | Connection timeout in seconds |
| MYSQLI_OPT_READ_TIMEOUT | Command execution result timeout in seconds. Available as of PHP 7.2.0. |
| MYSQLI_OPT_LOCAL_INFILE | Enable/disable use of LOAD LOCAL INFILE |
| MYSQLI_INIT_COMMAND | Command to execute after when connecting to MySQL server |
| MYSQLI_SET_CHARSET_NAME | The charset to be set as default. |
| MYSQLI_READ_DEFAULT_FILE | Read options from named option file instead of my.cnf Not supported by mysqlnd. |
| MYSQLI_READ_DEFAULT_GROUP | Read options from the named group from my.cnf or the file specified with MYSQL_READ_DEFAULT_FILE . Not supported by mysqlnd. |
| MYSQLI_SERVER_PUBLIC_KEY | RSA public key file used with the SHA-256 based authentication. |
| MYSQLI_OPT_NET_CMD_BUFFER_SIZE | The size of the internal command/network buffer. Only valid for mysqlnd. |
| MYSQLI_OPT_NET_READ_BUFFER_SIZE | Maximum read chunk size in bytes when reading the body of a MySQL command packet. Only valid for mysqlnd. |
| MYSQLI_OPT_INT_AND_FLOAT_NATIVE | Convert integer and float columns back to PHP numbers. Only valid for mysqlnd. |
| MYSQLI_OPT_SSL_VERIFY_SERVER_CERT | Whether to verify server certificate or not. |
Return Values
Returns true on success or false on failure.
Errors/Exceptions
If mysqli error reporting is enabled ( MYSQLI_REPORT_ERROR ) and the requested operation fails, a warning is generated. If, in addition, the mode is set to MYSQLI_REPORT_STRICT , a mysqli_sql_exception is thrown instead.
Examples
Notes
Note:
MySQLnd always assumes the server default charset. This charset is sent during connection hand-shake/authentication, which mysqlnd will use.
Libmysqlclient uses the default charset set in the my.cnf or by an explicit call to mysqli_options() prior to calling mysqli_real_connect() , but after mysqli_init() .
See Also
- mysqli_init() — Initializes MySQLi and returns an object for use with mysqli_real_connect()
- mysqli_real_connect() — Opens a connection to a mysql server
User Contributed Notes 6 notes
There is an undocumented option: MYSQLI_OPT_READ_TIMEOUT. This is similar to MYSQLI_OPT_CONNECT_TIMEOUT in theory, but has a slightly different application. Connection timeout only specifies the wait time for the initial TCP connection. Once that is created, the timeout no longer applies. Read timeout, however, is from the time the TCP connection is created until the first packet of actual data is received. There are instances where a TCP connection can be established, but the MySQL server stalls indefinitely, preventing execution from ever returning to PHP. Specifying a read timeout alleviates this condition, whereas connect timeout wouldn’t.
If the MYSQLI_OPT_READ_TIMEOUT constant isn’t defined, it is still supported on versions where that isn’t the case. You can define it yourself in older PHP versions with the following code.
if (! defined ( ‘MYSQLI_OPT_READ_TIMEOUT’ )) define ( ‘MYSQLI_OPT_READ_TIMEOUT’ , 11 );
>
?>
You can then use read timeout the same way you could a connect timeout as follows. Please note that since these are two different timeout values for two different parts of the entire connection process, the timeouts do stack (eg: 10 seconds connect timeout + 10 seconds read timeout = maximum possible timeout of 20 seconds)
//create the object
$connection = mysqli_init ();
//specify the connection timeout
$connection -> options ( MYSQLI_OPT_CONNECT_TIMEOUT , 10 );
//specify the read timeout
$connection -> options ( MYSQLI_OPT_READ_TIMEOUT , 10 );
//initiate the connection to the server, using both previously specified timeouts
$connection -> real_connect ( ‘server’ , ‘user’ , ‘pass’ , ‘database’ );
?>
Предопределённые константы
Перечисленные ниже константы определены данным модулем и могут быть доступны только в том случае, если PHP был собран с поддержкой этого модуля или же в том случае, если данный модуль был динамически загружен во время выполнения.
MYSQLI_READ_DEFAULT_GROUP
Читать опции из указанной группы в файле my.cnf или файле, указанном с помощью MYSQLI_READ_DEFAULT_FILE
MYSQLI_READ_DEFAULT_FILE
Читать опции из указанного файла, вместо my.cnf
MYSQLI_OPT_CONNECT_TIMEOUT
Время ожидания подключения в секундах.
MYSQLI_OPT_READ_TIMEOUT
Время ожидания результата выполнения команды в секундах. Доступно с PHP 7.2.0.
MYSQLI_OPT_LOCAL_INFILE
Включает команду LOAD LOCAL INFILE .
MYSQLI_OPT_INT_AND_FLOAT_NATIVE
Преобразует целые и плавающие столбцы обратно в числа PHP. Корректно работает только с mysqlnd.
MYSQLI_OPT_NET_CMD_BUFFER_SIZE
Размер внутреннего буфера команды/сети. Корректно работает только с mysqlnd.
MYSQLI_OPT_NET_READ_BUFFER_SIZE
Максимальный размер блока чтения в байтах при чтении тела пакета команд MySQL. Only valid for mysqlnd.
MYSQLI_OPT_SSL_VERIFY_SERVER_CERT
Требуется MySQL 5.1.10 и выше
MYSQLI_INIT_COMMAND
Команда, которая будет выполнена при подключении к серверу MySQL. Эта команда будет повторно вызвана при переподключении.
MYSQLI_CLIENT_SSL
Использовать SSL (шифрованный протокол). Эта опция не может быть установлена приложениями; она устанавливается внутри библиотеки клиента MySQL.
MYSQLI_CLIENT_COMPRESS
MYSQLI_CLIENT_INTERACTIVE
Ждать interactive_timeout секунд (вместо wait_timeout ) бездействия перед закрытием соединения. Переменная сессии клиента wait_timeout будет установлена в значение переменной сессии interactive_timeout .
MYSQLI_CLIENT_IGNORE_SPACE
Разрешить пробелы после имён функций. Делает все имена функций зарезервированными словами.
MYSQLI_CLIENT_NO_SCHEMA
Запретить синтаксис db_name.tbl_name.col_name .
MYSQLI_CLIENT_MULTI_QUERIES
Разрешить выполнение в одном вызове функции mysqli_query() нескольких запросов, разделённых точкой с запятой.
MYSQLI_STORE_RESULT
Для использования буферизации наборов данных. Значение равно 0 .
MYSQLI_USE_RESULT
Для использования небуферизированных наборов данных. Значение равно 1 .
MYSQLI_ASSOC
Результат возвращается в виде ассоциативного массива с именами полей в качестве индексов.
Результат возвращается в виде индексного массива.
MYSQLI_BOTH
Результат возвращается в виде массива, который содержит как числовой, так и ассоциативный индексы.
MYSQLI_NOT_NULL_FLAG
Информирует о том, что поле определено как NOT NULL .
MYSQLI_PRI_KEY_FLAG
Поле является частью первичного индекса.
MYSQLI_UNIQUE_KEY_FLAG
Поле является частью уникального индекса.
MYSQLI_MULTIPLE_KEY_FLAG
Поле является частью индекса.
MYSQLI_BLOB_FLAG
MYSQLI_UNSIGNED_FLAG
Поле определено как UNSIGNED .
MYSQLI_ZEROFILL_FLAG
Поле определено как ZEROFILL .
MYSQLI_AUTO_INCREMENT_FLAG
Поле определено как AUTO_INCREMENT .
MYSQLI_TIMESTAMP_FLAG
Поле определено как TIMESTAMP .
MYSQLI_SET_FLAG
MYSQLI_NUM_FLAG
Поле определено как NUMERIC .
MYSQLI_PART_KEY_FLAG
Поле является частью мульти-индекса.
MYSQLI_GROUP_FLAG
Поле является частью GROUP BY .
MYSQLI_TYPE_DECIMAL
Поле определено как DECIMAL .
MYSQLI_TYPE_NEWDECIMAL
Математическая точность полей DECIMAL или NUMERIC (MySQL 5.0.3 и выше).
MYSQLI_TYPE_BIT
Поле определено как BIT (MySQL 5.0.3 и выше).
MYSQLI_TYPE_TINY
Поле определено как TINYINT .
MYSQLI_TYPE_SHORT
Поле определено как SMALLINT .
MYSQLI_TYPE_LONG
MYSQLI_TYPE_FLOAT
Поле определено как FLOAT .
MYSQLI_TYPE_DOUBLE
Поле определено как DOUBLE .
MYSQLI_TYPE_NULL
Поле определено как DEFAULT NULL .
MYSQLI_TYPE_TIMESTAMP
Поле определено как TIMESTAMP .
MYSQLI_TYPE_LONGLONG
Поле определено как BIGINT .
MYSQLI_TYPE_INT24
Поле определено как MEDIUMINT .
MYSQLI_TYPE_DATE
MYSQLI_TYPE_TIME
MYSQLI_TYPE_DATETIME
Поле определено как DATETIME .
MYSQLI_TYPE_YEAR
MYSQLI_TYPE_NEWDATE
MYSQLI_TYPE_INTERVAL
Поле определено как INTERVAL
MYSQLI_TYPE_ENUM
MYSQLI_TYPE_SET
MYSQLI_TYPE_TINY_BLOB
Поле определено как TINYBLOB .
MYSQLI_TYPE_MEDIUM_BLOB
Поле определено как MEDIUMBLOB .
MYSQLI_TYPE_LONG_BLOB
Поле определено как LONGBLOB .
MYSQLI_TYPE_BLOB
MYSQLI_TYPE_VAR_STRING
Поле определено как VARCHAR .
MYSQLI_TYPE_STRING
Поле определено как CHAR или BINARY
MYSQLI_TYPE_CHAR
Поле определено как TINYINT . Для CHAR смотрите MYSQLI_TYPE_STRING
MYSQLI_TYPE_GEOMETRY
Поле определено как GEOMETRY .
MYSQLI_TYPE_JSON
Поле определено как JSON . Действительно только для mysqlnd и MySQL 5.7.8 и выше.
MYSQLI_NEED_DATA
Имеются ещё данные, доступные для связанных переменных.
MYSQLI_NO_DATA
Больше нет доступных данных для связанных переменных.
MYSQLI_DATA_TRUNCATED
Произошло усечение данных. Доступно начиная с MySQL 5.0.5.
MYSQLI_ENUM_FLAG
MYSQLI_BINARY_FLAG
Поле определено как BINARY .
MYSQLI_CURSOR_TYPE_FOR_UPDATE
MYSQLI_CURSOR_TYPE_NO_CURSOR
MYSQLI_CURSOR_TYPE_READ_ONLY
MYSQLI_CURSOR_TYPE_SCROLLABLE
MYSQLI_STMT_ATTR_CURSOR_TYPE
MYSQLI_STMT_ATTR_PREFETCH_ROWS
MYSQLI_STMT_ATTR_UPDATE_MAX_LENGTH
MYSQLI_SET_CHARSET_NAME
MYSQLI_REPORT_INDEX
Уведомлять, если индекс, используемый в запросе, не указан либо превышает максимум.
MYSQLI_REPORT_ERROR
Уведомлять об ошибках вызова функций mysqli.
MYSQLI_REPORT_STRICT
Обрабатывать mysqli_sql_exception как ошибки, а не как предупреждения.
MYSQLI_REPORT_ALL
MYSQLI_REPORT_OFF
MYSQLI_DEBUG_TRACE_ENABLED
Установлено в 1, если используется функция mysqli_debug() .
MYSQLI_SERVER_QUERY_NO_GOOD_INDEX_USED
MYSQLI_SERVER_QUERY_NO_INDEX_USED
MYSQLI_SERVER_PUBLIC_KEY
MYSQLI_REFRESH_GRANT
Обновляет таблицу прав доступа.
MYSQLI_REFRESH_LOG
Сбрасывает логи, точно так же, как и SQL выражение FLUSH LOGS .
MYSQLI_REFRESH_TABLES
Очищает кеш таблицы, точно так же, как и SQL выражение FLUSH TABLES .
MYSQLI_REFRESH_HOSTS
Очищает кеш хоста, точно так же, как и SQL выражение FLUSH HOSTS .
MYSQLI_REFRESH_REPLICA
Алиас константы MYSQLI_REFRESH_SLAVE . Доступна, начиная с PHP 8.1.0.
MYSQLI_REFRESH_STATUS
Сбрасывает переменные состояния, точно так же, как и SQL выражение FLUSH STATUS .
MYSQLI_REFRESH_THREADS
MYSQLI_REFRESH_SLAVE
На ведомом реплицируемом сервере (slave): сбросить информацию ведущего сервера (master) и перезапустить ведомый сервер. Аналогично выполнению SQL выражения RESET SLAVE .
MYSQLI_REFRESH_MASTER
На ведущем реплицируемом сервере (master): удалить бинарные файлы логов в бинарном индексе логов, и обрезать файл индекса. Аналогично выполнению SQL выражения RESET MASTER .
MYSQLI_TRANS_COR_AND_CHAIN
MYSQLI_TRANS_COR_AND_NO_CHAIN
MYSQLI_TRANS_COR_RELEASE
MYSQLI_TRANS_COR_NO_RELEASE
MYSQLI_TRANS_START_READ_ONLY
Начинает транзакцию как «START TRANSACTION READ ONLY» с mysqli_begin_transaction() .
MYSQLI_TRANS_START_READ_WRITE
Начинает транзакцию как «START TRANSACTION READ WRITE» с mysqli_begin_transaction() .
MYSQLI_TRANS_START_CONSISTENT_SNAPSHOT
Начинает транзакцию как «START TRANSACTION WITH CONSISTENT SNAPSHOT» с mysqli_begin_transaction() .
MYSQLI_CLIENT_SSL_DONT_VERIFY_SERVER_CERT
Требуется MySQL 5.6.5 и выше
MYSQLI_IS_MARIADB
Определяет, собран ли модуль mysqli с клиентской библиотекой MariaDB. Доступно, начиная с PHP 8.1.2.