mysqli

class mysqli (View source)

Represents a connection between PHP and a MySQL database.

Properties

int $affected_rows
string $client_info
int $client_version
int $connect_errno
string $connect_error
int $errno
string $error
int $field_count
string $host_info
string $info
int|string $insert_id
string $server_info
int $server_version
string $sqlstate
int $protocol_version
int $thread_id
int $warning_count
array $error_list
$stat

Methods

__construct(string $hostname = null, string $username = null, string $password = null, string $database = null, int $port = null, string $socket = null)

Open a new connection to the MySQL server

bool
autocommit(bool $enable)

Turns on or off auto-committing database modifications

bool
begin_transaction(int $flags = 0, string $name = null)

Starts a transaction

bool
change_user(string $username, string $password, string|null $database)

Changes the user of the specified database connection

string
character_set_name()

Returns the current character set of the database connection

client_encoding()

No description

bool
close()

Closes a previously opened database connection

bool
commit(int $flags = 0, string|null $name = null)

Commits the current transaction

bool
connect(string|null $hostname = null, string|null $username = null, string|null $password = null, string|null $database = null, int|null $port = null, string|null $socket = null)

No description

bool
dump_debug_info()

Dump debugging information into the log

bool
debug(string $options)

Performs debugging operations

object|null
get_charset()

Returns a character set object

mysqli_result|bool
execute_query(string $query, array|null $params = null)

Prepares the SQL query, binds parameters, and executes it. The mysqli::execute_query() method is a shortcut for mysqli::prepare(), mysqli_stmt::bind_param(), mysqli_stmt::execute(), and mysqli_stmt::get_result().

The statement template can contain zero or more question mark (?) parameter markers⁠—also called placeholders. The parameter values must be provided as an array using params parameter.

A prepared statement is created under the hood but it's never exposed outside of the function. It's impossible to access properties of the statement as one would do with the mysqli_stmt object. Due to this limitation, the status information is copied to the mysqli object and is available using its methods, e.g. mysqli_affected_rows() or mysqli_error().

string
get_client_info()

Returns the MySQL client version as a string

array
get_connection_stats()

Returns statistics about the client connection

string
get_server_info()

Returns the version of the MySQL server

mysqli_warning|false
get_warnings()

Get result of SHOW WARNINGS

bool|null
init() deprecated

Initializes MySQLi object

bool
kill(int $process_id)

Asks the server to kill a MySQL thread

bool
multi_query(string $query)

Performs one or more queries on the database

mysqli(string $host = null, string $username = null, string $password = null, string $database = null, int $port = null, string $socket = null)

No description

bool
more_results()

Check if there are any more query results from a multi query

bool
next_result()

Prepare next result from multi_query

bool
options(int $option, string|int $value)

Set options

bool
ping()

Pings a server connection, or tries to reconnect if the connection has gone down

mysqli_stmt|false
prepare(string $query)

Prepares an SQL statement for execution

mysqli_result|bool
query(string $query, int $result_mode = MYSQLI_STORE_RESULT)

Performs a query on the database

bool
real_connect(string $hostname = null, string $username = null, string $password = null, string $database = null, int $port = null, string $socket = null, int $flags = 0)

Opens a connection to a mysql server

string
real_escape_string(string $string)

Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection

static int|false
poll(array $read, array $error, array $reject, int $seconds, int $microseconds = 0)

Poll connections

mysqli_result|bool
reap_async_query()

Get result from async query

string
escape_string(string $string)

Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection

bool
real_query(string $query)

Execute an SQL query

bool
release_savepoint(string $name)

Removes the named savepoint from the set of savepoints of the current transaction

bool
rollback(int $flags = 0, string $name = null)

Rolls back current transaction

bool
savepoint(string $name)

Set a named transaction savepoint

bool
select_db(string $database)

Selects the default database for database queries

bool
set_charset(string $charset)

Sets the client character set

bool
set_opt(int $option, string|int $value)

No description

bool
ssl_set(string|null $key, string|null $certificate, string|null $ca_certificate, string|null $ca_path, string|null $cipher_algos)

Used for establishing secure connections using SSL

string|false
stat()

Gets the current system status

mysqli_stmt|false
stmt_init()

Initializes a statement and returns an object for use with mysqli_stmt_prepare

mysqli_result|false
store_result(int $mode = 0)

Transfers a result set from the last query

bool
thread_safe()

Returns whether thread safety is given or not

mysqli_result|false
use_result()

Initiate a result set retrieval

bool
refresh(int $flags)

No description

Details

at line 207
__construct(string $hostname = null, string $username = null, string $password = null, string $database = null, int $port = null, string $socket = null)

Open a new connection to the MySQL server

Parameters

string $hostname

[optional] Can be either a host name or an IP address. Passing the NULL value or the string "localhost" to this parameter, the local host is assumed. When possible, pipes will be used instead of the TCP/IP protocol. Prepending host by p: opens a persistent connection. mysqli_change_user() is automatically called on connections opened from the connection pool. Defaults to ini_get("mysqli.default_host")
string $username

[optional] The MySQL user name. Defaults to ini_get("mysqli.default_user")
string $password

[optional] If not provided or NULL, the MySQL server will attempt to authenticate the user against those user records which have no password only. This allows one username to be used with different permissions (depending on if a password as provided or not). Defaults to ini_get("mysqli.default_pw")
string $database

[optional] If provided will specify the default database to be used when performing queries. Defaults to ""
int $port

[optional] Specifies the port number to attempt to connect to the MySQL server. Defaults to ini_get("mysqli.default_port")
string $socket

[optional] Specifies the socket or named pipe that should be used. Defaults to ini_get("mysqli.default_socket")

at line 224
bool autocommit(bool $enable)

Turns on or off auto-committing database modifications

Parameters

bool $enable

Whether to turn on auto-commit or not.

Return Value

bool

true on success or false on failure.

at line 235
bool begin_transaction(int $flags = 0, string $name = null)

Since: 5.5

Starts a transaction

Parameters

int $flags [optional]
string $name [optional]

Return Value

bool

true on success or false on failure.

at line 260
bool change_user(string $username, string $password, string|null $database)

Changes the user of the specified database connection

Parameters

string $username

The MySQL user name.

string $password

The MySQL password.

string|null $database

The database to change to.

If desired, the null value may be passed resulting in only changing the user and not selecting a database. To select a database in this case use the mysqli_select_db function.

Return Value

bool

true on success or false on failure.

at line 272
string character_set_name()

Returns the current character set of the database connection

Return Value

string

The current character set of the connection

at line 278
client_encoding()

No description

at line 286
bool close()

Closes a previously opened database connection

Return Value

bool

true on success or false on failure.

at line 297
bool commit(int $flags = 0, string|null $name = null)

Commits the current transaction

Parameters

int $flags

A bitmask of MYSQLI_TRANSCOR* constants.
string|null $name

If provided then COMMIT $name is executed.

Return Value

bool

true on success or false on failure.

at line 313
bool connect(string|null $hostname = null, string|null $username = null, string|null $password = null, string|null $database = null, int|null $port = null, string|null $socket = null)

No description

Parameters

string|null $hostname [optional]
string|null $username [optional]
string|null $password [optional]
string|null $database [optional]
int|null $port [optional]
string|null $socket [optional]

Return Value

bool

at line 328
bool dump_debug_info()

Dump debugging information into the log

Return Value

bool

true on success or false on failure.

at line 339
bool debug(string $options)

Performs debugging operations

Parameters

string $options

A string representing the debugging operation to perform

Return Value

bool true.

at line 362
object|null get_charset()

Returns a character set object

Return Value

object|null

The function returns a character set object with the following properties: charset

Character set name

collation

Collation name

dir

Directory the charset description was fetched from (?) or "" for built-in character sets

min_length

Minimum character length in bytes

max_length

Maximum character length in bytes

number

Internal character set number

state

Character set status (?)

at line 401
mysqli_result|bool execute_query(string $query, array|null $params = null)

Since: 8.2

Prepares the SQL query, binds parameters, and executes it. The mysqli::execute_query() method is a shortcut for mysqli::prepare(), mysqli_stmt::bind_param(), mysqli_stmt::execute(), and mysqli_stmt::get_result().

The statement template can contain zero or more question mark (?) parameter markers⁠—also called placeholders. The parameter values must be provided as an array using params parameter.

A prepared statement is created under the hood but it's never exposed outside of the function. It's impossible to access properties of the statement as one would do with the mysqli_stmt object. Due to this limitation, the status information is copied to the mysqli object and is available using its methods, e.g. mysqli_affected_rows() or mysqli_error().

Parameters

string $query

The query, as a string. It must consist of a single SQL statement. The SQL statement may contain zero or more parameter markers represented by question mark (?) characters at the appropriate positions. Note: The markers are legal only in certain places in SQL statements. For example, they are permitted in the VALUES() list of an INSERT statement (to specify column values for a row), or in a comparison with a column in a WHERE clause to specify a comparison value. However, they are not permitted for identifiers (such as table or column names).
array|null $params

An optional list array with as many elements as there are bound parameters in the SQL statement being executed. Each value is treated as a string.

Return Value

mysqli_result|bool

Returns false on failure. For successful queries which produce a result set, such as SELECT, SHOW, DESCRIBE or EXPLAIN, returns a mysqli_result object. For other successful queries, returns true.

at line 408
string get_client_info()

Returns the MySQL client version as a string

Return Value

string

A string that represents the MySQL client library version

at line 416
array get_connection_stats()

Returns statistics about the client connection

Return Value

array

an array with connection stats.

at line 424
string get_server_info()

Returns the version of the MySQL server

Return Value

string

A character string representing the server version.

at line 432
mysqli_warning|false get_warnings()

Get result of SHOW WARNINGS

Return Value

mysqli_warning|false

at line 441
bool|null init() deprecated

deprecated 8.1

Initializes MySQLi object

Return Value

bool|null

at line 449
bool kill(int $process_id)

Asks the server to kill a MySQL thread

Parameters

int $process_id

Return Value

bool

true on success or false on failure.

at line 470
bool multi_query(string $query)

Performs one or more queries on the database

Parameters

string $query

A string containing the queries to be executed. Multiple queries must be separated by a semicolon.

If the query contains any variable input then parameterized prepared statements should be used instead. Alternatively, the data must be properly formatted and all strings must be escaped using the mysqli_real_escape_string function.

Return Value

bool

false if the first statement failed. To retrieve subsequent errors from other statements you have to call mysqli_next_result first.

at line 484
mysqli(string $host = null, string $username = null, string $password = null, string $database = null, int $port = null, string $socket = null)

No description

Parameters

string $host [optional]
string $username [optional]
string $password [optional]
string $database [optional]
int $port [optional]
string $socket [optional]

at line 491
bool more_results()

Check if there are any more query results from a multi query

Return Value

bool

true on success or false on failure.

at line 499
bool next_result()

Prepare next result from multi_query

Return Value

bool

true on success or false on failure.

at line 551
bool options(int $option, string|int $value)

Set options

Parameters

int $option

The option that you want to set. It can be one of the following values:

Valid options
Name Description
MYSQLI_OPT_CONNECT_TIMEOUT connection timeout in seconds (supported on Windows with TCP/IP since PHP 5.3.1)
MYSQLI_OPT_LOCAL_INFILE enable/disable use of LOAD LOCAL INFILE
MYSQLI_INIT_COMMAND command to execute after when connecting to MySQL server
MYSQLI_READ_DEFAULT_FILE Read options from named option file instead of my.cnf
MYSQLI_READ_DEFAULT_GROUP Read options from the named group from my.cnf or the file specified with MYSQL_READ_DEFAULT_FILE
MYSQLI_SERVER_PUBLIC_KEY RSA public key file used with the SHA-256 based authentication.

string|int $value

The value for the option.

Return Value

bool

true on success or false on failure.

at line 559
bool ping()

Pings a server connection, or tries to reconnect if the connection has gone down

Return Value

bool

true on success or false on failure.

at line 592
mysqli_stmt|false prepare(string $query)

Prepares an SQL statement for execution

Parameters

string $query

The query, as a string. It must consist of a single SQL statement.

The SQL statement may contain zero or more parameter markers represented by question mark (?) characters at the appropriate positions.

The markers are legal only in certain places in SQL statements. For example, they are permitted in the VALUES() list of an INSERT statement (to specify column values for a row), or in a comparison with a column in a WHERE clause to specify a comparison value.

However, they are not permitted for identifiers (such as table or column names), or to specify both operands of a binary operator such as the = equal sign. The latter restriction is necessary because it would be impossible to determine the parameter type. In general, parameters are legal only in Data Manipulation Language (DML) statements, and not in Data Definition Language (DDL) statements.

Return Value

mysqli_stmt|false

mysqli_prepare returns a statement object or false if an error occurred.

at line 637
mysqli_result|bool query(string $query, int $result_mode = MYSQLI_STORE_RESULT)

Performs a query on the database

Parameters

string $query

The query string.

If the query contains any variable input then parameterized prepared statements should be used instead. Alternatively, the data must be properly formatted and all strings must be escaped using the mysqli_real_escape_string function.

int $result_mode

[optional]

The result mode can be one of 3 constants indicating how the result will be returned from the MySQL server.

MYSQLI_STORE_RESULT (default) - returns a mysqli_result object with buffered result set.

MYSQLI_USE_RESULT - returns a mysqli_result object with unbuffered result set. As long as there are pending records waiting to be fetched, the connection line will be busy and all subsequent calls will return error Commands out of sync. To avoid the error all records must be fetched from the server or the result set must be discarded by calling mysqli_free_result.

MYSQLI_ASYNC (available with mysqlnd) - the query is performed asynchronously and no result set is immediately returned. mysqli_poll is then used to get results from such queries. Used in combination with either MYSQLI_STORE_RESULT or MYSQLI_USE_RESULT constant.

Return Value

mysqli_result|bool

Returns false on failure. For successful queries which produce a result set, such as SELECT, SHOW, DESCRIBE or EXPLAIN, mysqli_query will return a mysqli_result object. For other successful queries mysqli_query will return true.

at line 719
bool real_connect(string $hostname = null, string $username = null, string $password = null, string $database = null, int $port = null, string $socket = null, int $flags = 0)

Opens a connection to a mysql server

Parameters

string $hostname

[optional]

Can be either a host name or an IP address. Passing the null value or the string "localhost" to this parameter, the local host is assumed. When possible, pipes will be used instead of the TCP/IP protocol.

string $username

[optional]

The MySQL user name.

string $password

[optional]

If provided or null, the MySQL server will attempt to authenticate the user against those user records which have no password only. This allows one username to be used with different permissions (depending on if a password as provided or not).

string $database

[optional]

If provided will specify the default database to be used when performing queries.

int $port

[optional]

Specifies the port number to attempt to connect to the MySQL server.

string $socket

[optional]

Specifies the socket or named pipe that should be used.

Specifying the socket parameter will not explicitly determine the type of connection to be used when connecting to the MySQL server. How the connection is made to the MySQL database is determined by the host parameter.

int $flags

[optional]

With the parameter flags you can set different connection options:

Supported flags
Name Description
MYSQLI_CLIENT_COMPRESS Use compression protocol
MYSQLI_CLIENT_FOUND_ROWS return number of matched rows, not the number of affected rows
MYSQLI_CLIENT_IGNORE_SPACE Allow spaces after function names. Makes all function names reserved words.
MYSQLI_CLIENT_INTERACTIVE Allow interactive_timeout seconds (instead of wait_timeout seconds) of inactivity before closing the connection
MYSQLI_CLIENT_SSL Use SSL (encryption)

For security reasons the MULTI_STATEMENT flag is not supported in PHP. If you want to execute multiple queries use the mysqli_multi_query function.

Return Value

bool

true on success or false on failure.

at line 742
string real_escape_string(string $string)

Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection

Parameters

string $string

The string to be escaped.

Characters encoded are NUL (ASCII 0), \n, \r, \, ', ", and Control-Z.

Return Value

string

an escaped string.

at line 762
static int|false poll(array $read, array $error, array $reject, int $seconds, int $microseconds = 0)

Poll connections

Parameters

array $read

array $error

array $reject

int $seconds

Number of seconds to wait, must be non-negative.

int $microseconds

[optional]

Number of microseconds to wait, must be non-negative.

Return Value

int|false

number of ready connections in success, false otherwise.

at line 776
mysqli_result|bool reap_async_query()

Get result from async query

Return Value

mysqli_result|bool

mysqli_result in success, false otherwise.

at line 786
string escape_string(string $string)

Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection

Parameters

string $string

The string to be escaped. Characters encoded are NUL (ASCII 0), \n, \r, \, ', ", and Control-Z.

Return Value

string

at line 803
bool real_query(string $query)

Execute an SQL query

Parameters

string $query

The query, as a string.

If the query contains any variable input then parameterized prepared statements should be used instead. Alternatively, the data must be properly formatted and all strings must be escaped using the mysqli_real_escape_string function.

Return Value

bool

true on success or false on failure.

at line 813
bool release_savepoint(string $name)

Since: 5.5

Removes the named savepoint from the set of savepoints of the current transaction

Parameters

string $name

The identifier of the savepoint.

Return Value

bool

Returns TRUE on success or FALSE on failure.

at line 824
bool rollback(int $flags = 0, string $name = null)

Since: 5.5 Added flags and name parameters.

Rolls back current transaction

Parameters

int $flags

[optional] A bitmask of MYSQLI_TRANSCOR* constants.
string $name

[optional] If provided then ROLLBACK $name is executed.

Return Value

bool

true on success or false on failure.

at line 837
bool savepoint(string $name)

Since: 5.5

Set a named transaction savepoint

Parameters

string $name

Return Value

bool

Returns TRUE on success or FALSE on failure.

at line 848
bool select_db(string $database)

Selects the default database for database queries

Parameters

string $database

The database name.

Return Value

bool

true on success or false on failure.

at line 859
bool set_charset(string $charset)

Sets the client character set

Parameters

string $charset

The desired character set.

Return Value

bool

true on success or false on failure

at line 867
bool set_opt(int $option, string|int $value)

No description

Parameters

int $option
string|int $value

Return Value

bool

at line 890
bool ssl_set(string|null $key, string|null $certificate, string|null $ca_certificate, string|null $ca_path, string|null $cipher_algos)

Used for establishing secure connections using SSL

Parameters

string|null $key

The path name to the key file.

string|null $certificate

The path name to the certificate file.

string|null $ca_certificate

The path name to the certificate authority file.

string|null $ca_path

The pathname to a directory that contains trusted SSL CA certificates in PEM format.

string|null $cipher_algos

A list of allowable ciphers to use for SSL encryption.

Return Value

bool

This function always returns TRUE value.

at line 905
string|false stat()

Gets the current system status

Return Value

string|false

A string describing the server status. false if an error occurred.

at line 913
mysqli_stmt|false stmt_init()

Initializes a statement and returns an object for use with mysqli_stmt_prepare

Return Value

mysqli_stmt|false

an object.

at line 936
mysqli_result|false store_result(int $mode = 0)

Transfers a result set from the last query

Parameters

int $mode

[optional] The option that you want to set

Return Value

mysqli_result|false

a buffered result object or false if an error occurred.

mysqli_store_result returns false in case the query didn't return a result set (if the query was, for example an INSERT statement). This function also returns false if the reading of the result set failed. You can check if you have got an error by checking if mysqli_error doesn't return an empty string, if mysqli_errno returns a non zero value, or if mysqli_field_count returns a non zero value. Also possible reason for this function returning false after successful call to mysqli_query can be too large result set (memory for it cannot be allocated). If mysqli_field_count returns a non-zero value, the statement should have produced a non-empty result set.

at line 946
bool thread_safe()

Returns whether thread safety is given or not

Return Value

bool

true if the client library is thread-safe, otherwise false.

at line 954
mysqli_result|false use_result()

Initiate a result set retrieval

Return Value

mysqli_result|false

an unbuffered result object or false if an error occurred.

at line 963
bool refresh(int $flags)

Since: 5.3

No description

Parameters

int $flags MYSQLIREFRESH*

Return Value

bool

TRUE if the refresh was a success, otherwise FALSE