Biblioteca banco.php

Caminho no Gestor bibliotecas/banco.php

banco.php é a camada de acesso a dados de todo o Gestor. Ela sempre vem carregada ($_GESTOR['bibliotecas']) e fala com MySQL/MariaDB por MySQLi, montando SQL por concatenação de strings. Não há prepared statements: a segurança depende de você escapar cada valor com banco_escape_field().

Configuração e conexão

A conexão usa $_BANCO, preenchido em gestor/config.php a partir do .env:

• A conexão é preguiçosa. banco_query() e banco_escape_field() chamam banco_conectar() na primeira vez; não é preciso conectar à mão.

• banco_conectar() liga MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT, abre a conexão e define o charset utf8. Se a conexão falhar, encerra a requisição com die(), imprimindo o erro e a pilha gerada por banco_erro_debug() (HTML com arquivo:linha => função de cada quadro).

• banco_fechar_conexao() fecha e remove $_BANCO['conexao'].

• banco_ping() testa a conexão com mysqli_ping() e, se ela caiu, só incrementa $_BANCO['RECONECT']: não reconecta.

Executar SQL

• banco_query($query) executa qualquer SQL. Com $_BANCO['distribuido'] ativo, não usa o banco local: repassa a instrução a banco_distribuido_query() (módulos distribuídos, req-005), que devolve um BancoResultadoRemoto para SELECT ou true/false para escrita. Localmente, uma mysqli_sql_exception é capturada, registrada com error_log() (junto com o SQL) e vira false. Nenhum erro chega à tela.

• banco_sql($sql) executa e devolve todas as linhas com índices numéricos e nomes (mysqli_fetch_array), ou null sem resultados.

• banco_sql_names($sql, $campos) executa e devolve linhas associativas usando os nomes de $campos (lista separada por vírgulas, ou *).

• banco_linhas_afetadas() devolve quantas linhas a última escrita alterou (ou null no modo distribuído). Serve para "só a primeira requisição reivindica a ação": UPDATE … WHERE <ainda não feito> afeta 1 linha para quem chegou primeiro e 0 para as outras.

• banco_last_id() devolve o AUTO_INCREMENT do último INSERT (no modo distribuído, o id informado pela instalação remota).

Lendo um resultado cru

Os wrappers aceitam um mysqli_result ou um BancoResultadoRemoto:

• banco_num_rows($result) devolve 0 para false. Evita o TypeError do PHP 8.1+ quando a consulta falhou;

• banco_num_fields($result), banco_field_name($result, $i) e banco_fields_names($tabela): o último faz SELECT * … LIMIT 1 e devolve os nomes das colunas, ou null se não houver colunas;

• banco_row($result) devolve uma linha indexada;

• banco_row_array($result) devolve uma linha indexada e associativa;

• banco_fetch_assoc($result) devolve uma linha associativa.

SELECT estruturado: banco_select()

É a forma recomendada de consultar:

$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/'], ... ]  ou  null

• campos é um array (unido por vírgula) ou uma string, ou *.

• extra recebe tudo o que vem depois do FROM (JOIN, WHERE, ORDER BY, LIMIT). A tabela pode ter apelido: 'tabela' => 'paginas AS p'.

• unico devolve só a primeira linha como array simples, em vez de uma lista.

• Sem resultado, o retorno é null, e não array vazio.

Variantes com assinatura posicional, usadas pelo código legado:

• banco_select_name($campos, $tabela, $extra) devolve linhas associativas (valores não numéricos convertidos para string);

• banco_select_editar($campos, $tabela, $extra) devolve só a primeira linha e grava $_GESTOR['banco-resultado'] (true/false).

Guardar o "antes" de uma edição

O padrão de histórico dos CRUDs:

1. banco_select_campos_antes_iniciar($campos, $tabela, $extra) lê o registro e guarda a primeira linha em $_GESTOR['banco-antes'] (devolve true/false).

2. banco_select_campos_antes($campo) devolve o valor antigo de um campo (ou null) para comparar com o $_REQUEST e montar o histórico com interface_historico_incluir().

Escrever

INSERT

O jeito mais usado é acumular campos e inserir de uma vez:

banco_insert_name_campo('id', $id);                 // escapa e põe aspas
banco_insert_name_campo('versao', '1', true);       // sem aspas (número, NOW(), NULL)
banco_insert_name_campo('html', $html, false, false); // sem escapar (já escapado)
banco_insert_name(banco_insert_name_campos(), 'paginas');

• banco_insert_name_campo($nome, $valor, $sem_aspas_simples = false, $escape_field = true) acumula em $_BANCO['insert-name-campos'], escapando o valor por padrão.

• banco_insert_name_campos() devolve os campos acumulados e limpa a lista.

• banco_insert_name($dados, $tabela) recebe [[nome, valor, sem_aspas], …] e monta INSERT INTO t (…) VALUES (…). Não escapa: ou os valores vieram de banco_insert_name_campo(), ou você escapa antes (como fazem os módulos com banco_escape_field($_REQUEST[...])). Itens sem nome ou sem valor são ignorados.

• banco_insert_name_varios(['tabela' => …, 'campos' => [['nome' => …, 'valores' => [...], 'sem_aspas_simples' => true], …]]) faz um INSERT de várias linhas, organizado por coluna. null vira NULL. Não escapa.

Funções legadas sem chamadores no core, que dependem da ordem física das colunas e não escapam nada:

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

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

• banco_insert_varios($campos, $tabela) e banco_insert_varios_tudo($campos, $tabela): várias linhas. As duas concatenam numa variável não inicializada (warning no PHP 8).

UPDATE

• banco_update($campos, $tabela, $extra) executa UPDATE t SET <campos> <extra>. $campos é a string pronta ("nome='x', versao=versao+1").

• banco_update_campo($nome, $valor, $sem_aspas_simples = false, $escape_field = true) acumula em $_BANCO['update-campos'], e banco_update_executar($tabela, $extra = '') executa e limpa o acumulado. Sem campos acumulados, não faz nada.

• banco_update_varios($campos, $tabela, $campo_nome, $id_nome) atualiza muitos registros com CASE id WHEN … THEN …, quebrando em várias consultas acima de ~1 MB. Os valores não são escapados, e a função concatena em $sql_fechar sem inicializá-la. Sem chamadores no core.

Inserir ou atualizar

banco_insert_update(['tabela' => ['nome' => …, 'id' => …, 'extra' => …], 'dados' => [...], 'dadosTipo' => [...]]) procura o registro por dados[<id>]: se existe faz UPDATE, senão faz INSERT. Com dadosTipo, bool grava 1/NULL e int grava o número sem aspas (vazio vira NULL); o resto é escapado e vai com aspas. Não filtra por idioma, nem ao procurar nem ao atualizar.

DELETE

• banco_delete($tabela, $extra) executa DELETE FROM t <extra>. Sem WHERE no $extra, apaga a tabela inteira.

• banco_delete_varios($tabela, $campo_ids, $array_ids) monta DELETE … WHERE campo IN (…).

Identificadores (slugs) únicos

Os CRUDs geram o id textual do registro a partir do nome:

$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() normaliza o texto com banco_retirar_acentos(), corta em ~90 caracteres (por palavra) e, se o texto já termina em -<número>, parte desse número.

2. banco_identificador_unico() procura id, id-1, id-2… até achar um livre, ignorando registros com status='D'. Opções de tabela:

   • id_valor exclui o próprio registro, na edição;

   • status define outra coluna de status;

   • sem_status desliga o filtro de status;

   • where adiciona uma condição. Com sem_traco, remove os hífens do resultado.

banco_retirar_acentos($var, $retirar_espaco = true) troca acentos por ASCII, remove pontuação, troca parênteses e colchetes por hífen e espaços por hífen (opcional), e colapsa hífens.

Utilitários

• banco_escape_field($field) escapa com mysqli_real_escape_string(), conectando se preciso. Sem conexão MySQLi ativa, lança LogicException em vez de devolver o valor sem escape.

• banco_campos_virgulas($campos) une um array com vírgulas ('' para vazio).

• banco_total_rows($tabela, $extra = null) executa SELECT count(*) e devolve o total. Sem chamadores no core.

• banco_campos_nomes($tabela) executa SHOW COLUMNS e devolve os metadados (Field, Type, Null, Key, Default, Extra) de cada coluna.

• banco_campo_existe($campo, $tabela) diz se a coluna existe. Os módulos usam para funcionar antes e depois de uma migration (por exemplo, css_source_hash).

• banco_tabelas_lista() executa SHOW TABLES e devolve os nomes.

• banco_smartstripslashes($str) só converte para string. É mantida por compatibilidade; não use em código novo.

Veja também

• Bibliotecas do Gestor

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

Funções (referência gerada)

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