banco.php library

Path in the Gestor bibliotecas/banco.php

banco.php is the data access layer of the whole Gestor. It is always loaded ($_GESTOR['bibliotecas']) and talks to MySQL/MariaDB through MySQLi, building SQL by string concatenation. There are no prepared statements: safety depends on escaping every value with banco_escape_field().

Configuration and connection

The connection uses $_BANCO, filled in gestor/config.php from .env:

• The connection is lazy. banco_query() and banco_escape_field() call banco_conectar() the first time; there is no need to connect by hand.

• banco_conectar() enables MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT, opens the connection and sets the utf8 charset. If the connection fails, it ends the request with die(), printing the error and the stack built by banco_erro_debug() (HTML with file:line => function for each frame).

• banco_fechar_conexao() closes and removes $_BANCO['conexao'].

• banco_ping() tests the connection with mysqli_ping() and, when it is down, only increments $_BANCO['RECONECT']: it does not reconnect.

Running SQL

• banco_query($query) runs any SQL. With $_BANCO['distribuido'] enabled, it does not use the local database: it forwards the statement to banco_distribuido_query() (distributed modules, req-005), which returns a BancoResultadoRemoto for SELECT or true/false for writes. Locally, a mysqli_sql_exception is caught, logged with error_log() (including the SQL) and becomes false. No error reaches the screen.

• banco_sql($sql) runs and returns every row with numeric and named indexes (mysqli_fetch_array), or null without results.

• banco_sql_names($sql, $campos) runs and returns associative rows using the names in $campos (comma-separated list, or *).

• banco_linhas_afetadas() returns how many rows the last write changed (or null in distributed mode). It supports "only the first request claims the action": UPDATE … WHERE <not done yet> affects 1 row for whoever arrives first and 0 for the others.

• banco_last_id() returns the AUTO_INCREMENT of the last INSERT (in distributed mode, the id reported by the remote installation).

Reading a raw result

The wrappers accept a mysqli_result or a BancoResultadoRemoto:

• banco_num_rows($result) returns 0 for false. This avoids the PHP 8.1+ TypeError when the query failed;

• banco_num_fields($result), banco_field_name($result, $i) and banco_fields_names($table): the last one runs SELECT * … LIMIT 1 and returns the column names, or null when there are no columns;

• banco_row($result) returns an indexed row;

• banco_row_array($result) returns an indexed and associative row;

• banco_fetch_assoc($result) returns an associative row.

Structured SELECT: banco_select()

This is the recommended way to query:

$paginas = banco_select(Array(
    'tabela' => 'paginas',
    'campos' => Array('id', 'nome', 'caminho'),
    'extra'  => "WHERE status='A' AND language='".banco_escape_field($lang)."' ORDER BY nome",
));
// [ ['id' => 'x', 'nome' => 'X', 'caminho' => 'x/'], ... ]  or  null

• campos is an array (joined with commas) or a string, or *.

• extra receives everything after FROM (JOIN, WHERE, ORDER BY, LIMIT). The table may have an alias: 'tabela' => 'paginas AS p'.

• unico returns only the first row as a flat array, instead of a list.

• Without results the return is null, not an empty array.

Positional variants, used by legacy code:

• banco_select_name($campos, $tabela, $extra) returns associative rows (non-numeric values cast to string);

• banco_select_editar($campos, $tabela, $extra) returns only the first row and sets $_GESTOR['banco-resultado'] (true/false).

Keeping the "before" of an edit

The CRUD history pattern:

1. banco_select_campos_antes_iniciar($campos, $tabela, $extra) reads the record and stores its first row in $_GESTOR['banco-antes'] (returns true/false).

2. banco_select_campos_antes($campo) returns a field's old value (or null) to compare with $_REQUEST and build the history with interface_historico_incluir().

Writing

INSERT

The most common way is to accumulate fields and insert once:

banco_insert_name_campo('id', $id);                 // escapes and quotes
banco_insert_name_campo('versao', '1', true);       // no quotes (number, NOW(), NULL)
banco_insert_name_campo('html', $html, false, false); // no escaping (already escaped)
banco_insert_name(banco_insert_name_campos(), 'paginas');

• banco_insert_name_campo($nome, $valor, $sem_aspas_simples = false, $escape_field = true) accumulates in $_BANCO['insert-name-campos'], escaping the value by default.

• banco_insert_name_campos() returns the accumulated fields and clears the list.

• banco_insert_name($dados, $tabela) takes [[name, value, no_quotes], …] and builds INSERT INTO t (…) VALUES (…). It does not escape: either the values came from banco_insert_name_campo() or you escape them first (as modules do with banco_escape_field($_REQUEST[...])). Items without a name or value are skipped.

• banco_insert_name_varios(['tabela' => …, 'campos' => [['nome' => …, 'valores' => [...], 'sem_aspas_simples' => true], …]]) runs a multi-row INSERT, organized by column. null becomes NULL. It does not escape.

Legacy functions without callers in the core, which depend on the physical column order and escape nothing:

• banco_insert($campos, $tabela): VALUES('0', …);

• banco_insert_tudo($campos, $tabela) and banco_insert_id($campos, $tabela): VALUES(…);

• banco_insert_varios($campos, $tabela) and banco_insert_varios_tudo($campos, $tabela): several rows. Both concatenate into an uninitialized variable (PHP 8 warning).

UPDATE

• banco_update($campos, $tabela, $extra) runs UPDATE t SET <fields> <extra>. $campos is the ready string ("nome='x', versao=versao+1").

• banco_update_campo($nome, $valor, $sem_aspas_simples = false, $escape_field = true) accumulates in $_BANCO['update-campos'], and banco_update_executar($tabela, $extra = '') runs and clears it. With nothing accumulated, it does nothing.

• banco_update_varios($campos, $tabela, $campo_nome, $id_nome) updates many records with CASE id WHEN … THEN …, splitting into several queries above ~1 MB. Values are not escaped, and the function concatenates into an uninitialized $sql_fechar. No callers in the core.

Insert or update

banco_insert_update(['tabela' => ['nome' => …, 'id' => …, 'extra' => …], 'dados' => [...], 'dadosTipo' => [...]]) looks up the record by dados[<id>]: UPDATE if it exists, INSERT otherwise. With dadosTipo, bool stores 1/NULL and int stores the number unquoted (empty becomes NULL); everything else is escaped and quoted. It does not filter by language, neither when looking up nor when updating.

DELETE

• banco_delete($tabela, $extra) runs DELETE FROM t <extra>. Without a WHERE in $extra, it empties the table.

• banco_delete_varios($tabela, $campo_ids, $array_ids) builds DELETE … WHERE field IN (…).

Unique identifiers (slugs)

CRUDs generate the record's textual id from its name:

$id = banco_identificador(Array(
    'id' => $_REQUEST['nome'],
    'tabela' => Array(
        'nome' => 'paginas', 'campo' => 'id', 'id_nome' => 'id_paginas',
        'where' => "language='".$_GESTOR['linguagem-codigo']."'",
    ),
));

1. banco_identificador() normalizes the text with banco_retirar_acentos(), cuts it at ~90 characters (by word) and, when the text already ends in -<number>, starts from that number.

2. banco_identificador_unico() tries id, id-1, id-2… until it finds a free one, ignoring records with status='D'. tabela options:

   • id_valor excludes the record itself, when editing;

   • status sets another status column;

   • sem_status disables the status filter;

   • where adds a condition. With sem_traco, hyphens are removed from the result.

banco_retirar_acentos($var, $retirar_espaco = true) replaces accents with ASCII, strips punctuation, turns parentheses and brackets into hyphens and spaces into hyphens (optional), and collapses hyphens.

Utilities

• banco_escape_field($field) escapes with mysqli_real_escape_string(), connecting if needed. Without an active MySQLi connection it throws LogicException instead of returning the value unescaped.

• banco_campos_virgulas($campos) joins an array with commas ('' when empty).

• banco_total_rows($tabela, $extra = null) runs SELECT count(*) and returns the total. No callers in the core.

• banco_campos_nomes($tabela) runs SHOW COLUMNS and returns each column's metadata (Field, Type, Null, Key, Default, Extra).

• banco_campo_existe($campo, $tabela) tells whether the column exists. Modules use it to work both before and after a migration (for example, css_source_hash).

• banco_tabelas_lista() runs SHOW TABLES and returns the names.

• banco_smartstripslashes($str) only casts to string. It is kept for compatibility; do not use it in new code.

See also

• Gestor libraries

• Skills c2f-database-operations, c2f-database-testing and c2f-mysql-utf8-emoji-encoding.

Functions (generated reference)

banco_escape_field(string $field): string

banco_smartstripslashes(mixed $str): string

banco_erro_debug(): string

banco_conectar(): void

banco_ping(): void

banco_fechar_conexao(): void

banco_query(string $query): mysqli_result|bool

banco_linhas_afetadas(): int|null

banco_num_rows(mixed $result): int

banco_num_fields(mysqli_result $result): int

banco_field_name(mysqli_result $result, int $num_field): string

banco_fields_names(string $table): array|null

banco_row(mysqli_result $result): array|null

banco_row_array(mysqli_result $result): array|null

banco_fetch_assoc(mysqli_result $result): array|null

banco_sql(string $sql): array|null

banco_sql_names(string $sql, string $campos): array|null

banco_select(array|false $params = false): array|null

banco_select_name(string $campos, string $tabela, string $extra): array|null

banco_select_editar(string $campos, string $tabela, string $extra): array|null

banco_select_campos_antes_iniciar(string $campos, string $tabela, string $extra): bool

banco_select_campos_antes(string $campo): mixed|null

banco_update(string $campos, string $tabela, string $extra): void

banco_update_campo(string $nome, string $valor, bool $sem_aspas_simples = false, bool $escape_field = true): void

banco_update_executar(string $tabela, string $extra = ''): void

banco_update_varios(array $campos, string $tabela, string $campo_nome, string $id_nome): void

banco_insert(string $campos, string $tabela): void

banco_insert_name(array $dados, string $tabela): void

banco_insert_name_campo(string $nome, string $valor, bool $sem_aspas_simples = false, bool $escape_field = true): void

banco_insert_name_campos(): array

banco_insert_name_varios(array|false $params = false): void

banco_insert_varios(array $campos, string $tabela): void

banco_insert_varios_tudo(array $campos, string $tabela): void

banco_insert_id(string $campos, string $tabela): void

banco_insert_tudo(string $campos, string $tabela): void

banco_last_id(): int|null

banco_delete(string $tabela, string $extra): void

banco_delete_varios(string $tabela, array|string $campo_ids, array $array_ids): void

banco_campos_virgulas(array $campos): string

banco_total_rows(string $tabela, string|null $extra = null): int

banco_campos_nomes(string $tabela): array

banco_campo_existe(string $campo, string $tabela): bool

banco_retirar_acentos(string $var, bool $retirar_espaco = true): string

banco_identificador_unico(array|false $params = false): string

banco_identificador(array|false $params = false): string

banco_insert_update(array|false $params = false): void

banco_tabelas_lista(): array