PHP mysqli

La clase PHP mysqli es la clase principal de la extensión MySQLi de PHP , esta clase representa una conexión a la base de datos creada con un DBMS MySQL.

La siguiente sinopsis es la misma que la dada en PHP.net

class mysqli {
/* Propiedades */
int $affected_rows;
int $connect_errno;
string $connect_error;
int $errno;
array $error_list;
string $error;
int $field_count;
int $client_version;
string $host_info;
string $protocol_version;
string $server_info;
int $server_version;
string $info;
mixed $insert_id;
string $sqlstate;
int $thread_id;
int $warning_count;
/* Métodos */
__construct(
    string $host = ini_get("mysqli.default_host"),
    string $username = ini_get("mysqli.default_user"),
    string $passwd = ini_get("mysqli.default_pw"),
    string $dbname = "",
    int $port = ini_get("mysqli.default_port"),
    string $socket = ini_get("mysqli.default_socket")
)
autocommit(bool $mode): bool
change_user(string $user, string $password, string $database): bool
character_set_name(): string
close(): bool
commit(int $flags = ?, string $name = ?): bool
debug(string $message): bool
dump_debug_info(): bool
get_charset(): object
get_client_info(): string
get_connection_stats(): bool
mysqli_stmt::get_server_info(): string
get_warnings(): mysqli_warning
init(): mysqli
kill(int $processid): bool
more_results(): bool
multi_query(string $query): bool
next_result(): bool
options(int $option, mixed $value): bool
ping(): bool
public static poll(
    array &$read,
    array &$error,
    array &$reject,
    int $sec,
    int $usec = ?
): int
prepare(string $query): mysqli_stmt
query(string $query, int $resultmode = MYSQLI_STORE_RESULT): mixed
real_connect(
    string $host = ?,
    string $username = ?,
    string $passwd = ?,
    string $dbname = ?,
    int $port = ?,
    string $socket = ?,
    int $flags = ?
): bool
escape_string(string $escapestr): string
real_query(string $query): bool
public reap_async_query(): mysqli_result
public refresh(int $options): bool
rollback(int $flags = ?, string $name = ?): bool
select_db(string $dbname): bool
set_charset(string $charset): bool
ssl_set(
    string $key,
    string $cert,
    string $ca,
    string $capath,
    string $cipher
): bool
stat(): string
stmt_init(): mysqli_stmt
store_result(int $option = ?): mysqli_result
use_result(): mysqli_result
}

• Propiedades
  • affected_rows
  • connect_errno
  • connect_error
  • errno
  • error_list
  • error
  • field_count
  • client_version
  • host_info
  • protocol_version
  • server_info
  • server_version
  • info
  • insert_id
  • sqlstate
  • thread_id
  • warning_count
• Métodos
  • __construct
  • autocommit
  • change_user
  • character_set_name
  • close
  • commit
  • debug
  • dump_debug_info
  • get_charset
  • get_client_info(En desuso desde PHP 8.1
  • get_connection_stats
  • get_warnings
  • init(en des-uso vea __construct)
  • kill
  • more_results
  • multi_query
  • next_result
  • options
  • ping
  • prepare
  • query
  • real_connect
  • real_escape_string / escape_string
  • real_query
  • reap_async_query
  • refresh(Deprecated by MySQL)
  • rollback
  • select_db
  • set_charset
  • ssl_set
  • stat
  • stmt_init
  • store_result
  • use_result

Puedes cerrar o abrir este menú cliqueando sobre el boton contenido

Propiedades de PHP mysqli

En las propiedades usaremos la variable $dbconnection, esta será la conexión obtenida tras hacer una instancia de la clase

$dbconnection = new mysqli('localhost', 'mi_usuario', 'mi_contraseña', 'mi_bd');

affected_rows

Devuelve el número de filas afectadas en la última consulta

$dbconnection->affected_rows;

connect_errno

código de error de la última llamada

$dbconnection->connect_errno;

connect_error

Devuelve una string con la descripción del último error de conexión

$dbconnection->connect_error;

errno

código del error de la última función llamada

$dbconnection->errno;

error_list

lista de errores desde el último comando ejecutado

$dbconnection->error_list;

error

string que describe el último error

$dbconnection->error;

field_count

número de columnas para la consulta más reciente

$dbconnection->field_count;

client_version

Versión cliente de MySQL como valor de tipo integer, esta es la versión que tiene como librería, de esta manera podemos determinar si podemos o no utilizar ciertas características, funcionalidades de MySQL.

$dbconnection->client_version;

host_info

String representando el tipo de conexión usada

$dbconnection->host_info;

protocol_version

Retorna la versión de protocolo utilizado

$dbconnection->protocol_version;

server_info

Versión de MySQL server retornada como un string

$dbconnection->server_info;

server_version

Versión de MySQL server como un entero

$dbconnection->server_version;

info

Información acerca de la consulta más reciente ejecutada.

$dbconnection->info;

insert_id

Este es el valor generado por un AUTO_INCREMENT perteneciente a una columna de nuestra base de datos creado por la última consulta.

Está claro que para que la última consulta nos dé este número la tabla debe tener un id AUTO_INCREMENT

$dbconnection->insert_id;

sqlstate

El SQLSTATE error proveniente de una operación(consula) previa en MySQL

$dbconnection->sqlstate;

thread_id

La ID del hilo (thread id) de la conexión actual. Probablemente, esta propiedad no la utilices nunca, deberías de tener una gran cantidad de usuarios para tener que preocuparte por los hilos que conectan con la base de datos.

$dbconnection->thread_id;

warning_count

nos devolverá la cantidad de warnings desde la última consulta para el link dado

$dbconnection->warning_count;

Métodos de PHP mysqli

Aquí veremos los diferentes métodos pertenecientes a nuestra clase mysqli, esta es la clase principal de la extension mysqli y, por lo tanto, tiene la mayor cantidad de métodos.

__construct

Abre una nueva conexión a nuestro server MySQL, creando nuestro objeto mysqli que representara esta conexión.

public mysqli::__construct(
    string $host = ini_get("mysqli.default_host"),
    string $username = ini_get("mysqli.default_user"),
    string $passwd = ini_get("mysqli.default_pw"),
    string $dbname = "",
    int $port = ini_get("mysqli.default_port"),
    string $socket = ini_get("mysqli.default_socket")
)

$db = new mysqli($host, $username, $passwd, $dbname, $port, $socket);

Por lo general se usa de nombre para la variable que contiene el objeto mysqli uno de los siguientes: $conn, $db, $dbconn, $dbconnection, $database

Parametros

$host – el valor dado debe ser un string por ejemplo el nombre del host "localhost" o ip del host "127.0.0.1".

$username – El nombre de usuario que utilizara nuestra base de datos

$passwd – password del usuario que utilizará la base de datos

$dbname – El nombre de la base de datos

$port – puerto

$socket – socket(combinacion de ip + puerto)

Retornos

mysqli[obj] – retorna un objeto mysqli en caso de poder realizar la coneccion con la base de datos

false – este metodo retorna false en caso de error

autocommit

Este método determina si queremos que las consultas(querys) hagan autocommit o no, lo que tengo que destacar de esto es: debemos de tener el cuidado suficiente al utilizarlo, ya que si queremos hacer una transacción no tiene sentido utilizar autocommit.

Por ejemplo tenemos varias tablas para cambiar haciendo un insert que pasaria si falla en el medio de estos insert debería poder hacer rollback, pero lamentablemente ya hemos hecho commit y esto no tiene sentido.

public mysqli::autocommit(bool $mode): bool

Su parámetro $mode es de tipo bool he indicará si está habilitado o no

Por lo general, se asegura que autocommit no este habilitado cuando se hace una transacción y se utiliza habilitado en consultas(querys) simples.

change_user

Cambia el usuario a la conexión de base de datos.

Hay algunas ocasiones en que podemos querer cambiar el usuario con el que realizamos la conexión a la base de datos, ya que estos pueden tener distintos permisos.

public mysqli::change_user(string $user, string $password, string $database): bool

$dbconnection->change_user($user, $password, $database);

Parametros

$user – es el nombre del usuario de la base de datos nuevo que se conectara

$password – password del usuario que se conectara

$database – base de datos, en caso de no querer cambiar la base de datos puedes pasar null

Retorno

true o false dependiendo de si se pudo cambiar el usuario

character_set_name

Devuelve el chararacter set de la conexión a base de datos vea https://dev.mysql.com/doc/refman/8.0/en/charset.html para entender mejor el charset.

public mysqli::character_set_name(): string

$dbconnection->character_set_name();

Retorno

Este metodo devolvera un string

Un ejemplo de retorno de lo que obtendrás "latin1_swedish_ci"

close

Con este método se dará como finalizado la conexión.

public mysqli::close(): bool

Retorno

Retornará true o false dependiendo de si no pudo cerrar la conexión. En caso de que la conexión sea persistente, la conexión no se cerrara.

commit

Realiza el commit de la transacción en curso.

public mysqli::commit(int $flags = ?, string $name = ?): bool

Devuelve true o false dependiendo de si se pudo realizar la transacción o no

debug

Realiza una operación de debug

Talvez veamos esto en profundidad en un futuro proximo. Retorna como valor true

public mysqli::debug(string $options): bool

$option es un string que representa las diferentes operaciones que se realizaran, cada operación debe ser separada por : de la siguiente.

PHP. net nos da el siguiente ejemplo el cual utiliza una funcion alias, de todas formas analizaremos este ejemplo.

mysqli_debug("d:t:o,/tmp/client.trace");

Vea que nuestro string es "d:t:o,/tmp/client.trace" por tanto, usara la opción d, la opción t y o la cual también pose ,/tmp/client.trace este es el archivo donde guardara los datos de la opción d y t. Por otra parte, o significa output sin especificar la operación o no crearía este archivo.

¿Y como sería la utilización del método al utilizar POO(OOP)?

Supongamos que ya tenemos una conexión $dbconnection

$dbconnection->debug("d:t:o,/tmp/client.trace");

En esta tabla no se encuentra lo que hace d, pero me he encontrado otro lugar donde saber lo que hacen estas opciones, ya que estas son las mismas que se usan en c/c++ debug

este blog -> http://tiebing.blogspot.com/2011/10/cc-dbug-library.html

d :Enable output from DBUG_ macros for
for the current state. May be followed
by a list of keywords which selects output
only for the DBUG macros with that keyword.
A null list of keywords implies output for
all macros.

dump_debug_info

Hace un dump de la información cuando se está haciendo el debugging en el log. En pocas palabras hace un volcado(copia si asi lo queire ver) de lo que esta pasando en un archivo log.

El usuario a usar este metodo deberia ser SUPERUSER o con los maximos privilegios para esa base de datos.

public mysqli::dump_debug_info(): bool

Nos retorna true en caso de poder hacer el volcado, en caso contrario devolverá false(error)

get_charset

Devuelve el character set en forma de objecto(stdClass), este provee varias propiedades del charset:

public mysqli::get_charset(): ?object

Devuelve un objeto de tipo stdClass con los siguientes datos:

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 (?)

get_client_info(En desuso desde PHP 8.1, use $client_info)

Obtiene información del cliente MySQL, al correr este método obtendremos un string representando la bibliteca(library) del cliente MySQL

public mysqli::get_client_info(): string

Retorna la información del cliente MySQL

get_connection_stats

Retorna estadísticas de la conexión cliente MySQL. Estos datos son muy técnicos y probablemente no utilicé este método nunca.

public mysqli::get_connection_stats(): array

Retorna un array con los stats de la conexión.

get_warnings

Obtiene el resultado de correr la consulta SHOW WARNINGS en MySQL. El resultado es devuelto como un objeto mysqli_warning

SHOW WARNINGS is a diagnostic statement that displays information about the conditions (errors, warnings, and notes) resulting from executing a statement in the current session.

mysql.com

Devolvera un objeto mysqli_warning o false en caso de error

public mysqli::get_warnings(): mysqli_warning|false

init(en des-uso vea __construct)

no veremos esta función/ metodo

kill

pide al servidor MySQL terminar con el proceso de un hilo(thread), este método está relacionado con thread_id ya que la id del proceso es esta id.

public mysqli::kill(int $process_id): bool

Parametro

$process_id – es la misma id que podemos obtener con thread_id

Retorno

true o false dependiendo de si se pudo finalizar el proceso o no

more_results

Chequea si hay más resultados de una muti_query

public mysqli::more_results(): bool

multi_query

Realiza una o mas consultas a la base de datos

public mysqli::multi_query(string $query): bool

next_result

Es el próximo resultado si se ha utilizado multi_query. Debe ser utilizada en conjunto con multi_query

public mysqli::next_result(): bool

options

Con este método, podemos establecer opciones que cambian el comportamiento para una conexión. Por ejemplo, podemos decirle que la conexión dure un cierto tiempo después de todo, talvez no queramos tener una conexión siempre abierta, estamos gastando recursos.

public mysqli::options(int $option, mixed $value): bool

$dbconnection->options($option,$value);

ping

Hace ping a la conexión del servidor MySQL, en caso de que la conexión este caída trata de reconectar

 public mysqli::ping(): bool

en caso de poder hacer ping o reconectar el retorno será true, en caso contrario será false

prepare

Este metodo nos permite crear un prepare statement para su ejecución. Devuelve un objeto mysqli_stmt o false en caso de error.

public mysqli::prepare(string $query): mysqli_stmt|false

query

Permite realizar una consulta en nuestra base de datos, la consulta será pasada por parámetro como un string.

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

Parámetros

$query -será la consulta que le pasaremos para ser realizada en nuestra base de datos y debe ser un string, por ejemplo: "SELECT * FROM usuarios"

$result_mode – MYSQLI_USE_RESULT o MYSQLI_STORE_RESULT

Retorno

Este método nos devolverá un objeto mysqli_result en caso de poder realizar la consulta con exito y false en caso contrario.

real_connect

Abre una conexión al servidor MySQL, esta conexión utiliza la conexión creada con el constructor __construct.

 
public mysqli::real_connect(
    string $host = ?,
    string $username = ?,
    string $passwd = ?,
    string $dbname = ?,
    int $port = ?,
    string $socket = ?,
    int $flags = ?
): bool

Parámetros

$host – puede ser una ip o el hostname pasado como un string. En caso de especificar null o "localhost" su valor sera el de local host.

$username – nombre de usuarios

$passwd – password

$dbname – nombre de la base de datos

$port -puerto

$socket -socket

$flag – flag es alguno de las siguientes

Retorno

true o false dependiendo si se pudo realizar la conexión o no

real_escape_string / escape_string

Escapa los caracteres especiales en un string para su uso en una sentencia SQL, tomando en cuenta el conjunto de caracteres actual de la conexión

public mysqli::real_escape_string(string $string): string

Parámetros

$string – es el string que se quiere escapar

Retorno

Retorna un string ya escapado

Vea con atención el siguiente ejemplo de php.net

<?php
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
$city = "'s-Hertogenbosch";
/* this query with escaped $city will work */
$query = sprintf("SELECT CountryCode FROM City WHERE name='%s'",
    $mysqli->real_escape_string($city));
$result = $mysqli->query($query);
printf("Select returned %d rows.\n", $result->num_rows);
/* this query will fail, because we didn't escape $city */
$query = sprintf("SELECT CountryCode FROM City WHERE name='%s'", $city);
$result = $mysqli->query($query);

En el ejemplo se está usando mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT); para que si o si se tenga que utilizar la función de escapado, pero que pasaría si no usáramos esté escapado, pues podrían borrarnos todos los datos de nuestra tabla fácilmente.

Por ejemplo: si tengo un formulario donde coloco el valor que estoy buscando pero en vez de pasarle una ciudad, en este caso "'s-Hertogenbosch" y paso algo parecido a weak";DROP TABLE City;

Y nuestra tabla desapareció o sea algo parecido a esto

En un futuro hablaremos de esto creo.

Hay una página que tiene muy explicado este tema y es https://portswigger.net/web-security/sql-injection

real_query

Realiza una consulta SQL en nuestra base de datos, como ya hemos mencionado antes en consultas con mysqli en php utilizar query en vez de prepare puede traernos problemas grandes con los ataques de SQL inyection(inyección de código SQL) se recomienda utilizar prepare en todo caso en que tengamos inputs

public mysqli::real_query(string $query): bool

reap_async_query

Obtener el resultado de una consulta asincrónica, para poder utilizar este método necesitarás mysqlnd

public mysqli::reap_async_query(): mysqli_result[obj]

Retorna un objeto mysqli_result, en caso de error devolverá false.

refresh(Deprecated by MySQL)

realiza un refresh, realiza flushes tablas o caches, o resetea la onformacion del server replicada.

rollback

Revierte la transacción que se está realizando.

public mysqli::rollback(int $flags = 0, ?string $name = null): bool

select_db

Selecciona la base de datos, aunque es posible cambiar la base de datos por defecto para una consulta, se sugiere utilizar este método solo para establecer la base de datos de conexión, cosa que ya puede hacerse con el método constructor.

Puedes cambiar la base de datos de la conexión, siempre y cuando el usuario sea el mismo.

ublic mysqli::select_db(string $database): bool

set_charset

Setea el charset de la conexión cliente MySQL para data proveniente desde el servidor, como para data hacia el servidor.

Si necesitas saber las charset que puedes usar este link muestra todas las charset de MySQL posibles

 public mysqli::set_charset(string $charset): bool

ssl_set

ssl_set es utilizado para establecer una conexión segura utilizando SSL.

public mysqli::ssl_set(
    ?string $key,
    ?string $certificate,
    ?string $ca_certificate,
    ?string $ca_path,
    ?string $cipher_algos
): bool

stat

Gets the current system status

public mysqli::stat(): string|false

stmt_init

Inicializa un prepare statement y crea un objeto mysqli_stmt.

public mysqli::stmt_init(): mysqli_stmt|false

$stmt = $dbconnection->stmt_init();

store_result

Transfiere un conjunto de resultados de la última consulta

public mysqli::store_result(int $mode = 0): mysqli_result|false

use_result

Inicia la recuperación de un result set(set de resultados), en definitiva suponga que hace una consulta y necesita el resultado de esta más adelante. Este método devolverá el resultado de la última consulta utilizada

public mysqli::use_result(): mysqli_result|false