Conn2Flow
Docs
Navegação das docs

Referência / Bibliotecas

Biblioteca interface.php

O motor de CRUD dos módulos administrativos: ciclo iniciar/finalizar por opção, listagem Tailwind ou DataTables conforme o framework, formulários, validação, histórico, backups de campo, alertas e as variantes Tailwind dos componentes.

Caminho no Gestor bibliotecas/interface.php

A interface.php é o motor de CRUD do painel. Um módulo administrativo não monta telas de listagem, edição e exclusão à mão: ele diz o que quer (tabela, colunas, campos, validações, botões), e a biblioteca desenha a tela a partir de componentes (interface-listar, interface-formulario-edicao…), grava histórico, trata os AJAX padrão e dispara os hooks.

Peça a biblioteca no JSON do módulo ("bibliotecas": ["interface", …]).

O ciclo de um módulo

Todo controlador de módulo segue o mesmo esqueleto:

function meu_modulo_start(){
    global $_GESTOR;
    gestor_incluir_bibliotecas();
    if($_GESTOR['ajax']){
        interface_ajax_iniciar();
        switch($_GESTOR['ajax-opcao']){ /* AJAX próprios do módulo */ }
        interface_ajax_finalizar();          // AJAX padrão: listar, histórico, backup, verificar-campo
    } else {
        meu_modulo_interfaces_padroes();     // preenche $_GESTOR['interface'][<opcao>]
        interface_iniciar();
        switch($_GESTOR['opcao']){
            case 'adicionar': meu_modulo_adicionar(); break;
            case 'editar':    meu_modulo_editar(); break;
        }
        interface_finalizar();
    }
}

  • interface_iniciar() roda antes do código do módulo. Ele lê $_GESTOR['opcao'] (e, se houver, $_GESTOR['interface-opcao']), chama o interface_<opcao>_iniciar() correspondente com os parâmetros de $_GESTOR['interface'][<opcao>]['iniciar'] e liga as bandeiras que o módulo testa:

    • $_GESTOR['adicionar-banco'] quando o formulário de inclusão foi enviado (_gestor-adicionar);

    • $_GESTOR['atualizar-banco'] quando o de edição foi enviado (_gestor-atualizar);

    • $_GESTOR['modulo-registro-id'] com o id do registro (?id= em GET, ou _gestor-registro-id). Sem id nas opções que precisam dele, redireciona para a raiz do módulo.

  • interface_finalizar() roda depois. Chama o interface_<opcao>_finalizar() com $_GESTOR['interface'][<opcao>]['finalizar'], que desenha a tela em $_GESTOR['pagina'], e depois imprime o alerta pendente e renderiza os componentes marcados.

  • Com $_GESTOR['interface-nao-aplicar'], os dois não fazem nada.

Opções

opcao / interface-opcao O que o finalizador faz
listar Tabela paginada (Tailwind; DataTables na variante clássica) com busca, ordenação, ações por linha e modal de exclusão
adicionar, clonar Formulário de inclusão (interface-formulario-inclusao). clonar exige id e parte do registro existente
editar Formulário de edição (interface-formulario-edicao, com variante Tailwind), metadados e histórico
visualizar Tela somente leitura (interface-formulario-visualizacao)
status Troca status do registro (?id=…&status=A|I), incrementa versao, registra no histórico
excluir Exclusão lógica: status='D', versao+1, histórico e redirecionamento
config Tela de configuração do módulo, sem registro (interface-formulario-configuracoes)
alteracoes, simples, adicionar-incomum, editar-incomum Só via interface-opcao: variações para telas que não seguem o CRUD padrão

Os tratadores de cada opção:

Opção Início Fim
listar interface_listar_iniciar() (vazio) interface_listar_finalizar()
adicionar interface_adicionar_iniciar() interface_adicionar_finalizar()
clonar interface_clonar_iniciar() (aceita forcarId) interface_adicionar_finalizar()
editar interface_editar_iniciar() (aceita forcarId) interface_editar_finalizar()
visualizar interface_visualizar_iniciar() interface_visualizar_finalizar()
status interface_status_iniciar() (exige id e status em GET) interface_status_finalizar()
excluir interface_excluir_iniciar() (exige id em GET) interface_excluir_finalizar()
config interface_config_iniciar() interface_config_finalizar()
alteracoes interface_alteracoes_iniciar() (usa modulo-registro-padrao-id sem id) interface_alteracoes_finalizar()
simples interface_simples_iniciar() interface_simples_finalizar()
adicionar-incomum interface_adicionar_incomum_iniciar() interface_adicionar_incomum_finalizar()
editar-incomum interface_editar_incomum_iniciar() interface_editar_incomum_finalizar()

Hooks disparados

Para o módulo X e a opção O (e também para a interface-opcao):

  • hook_do_action('X', 'O.pre-banco') em todo POST, antes do código do módulo;

  • O.parametros em GET, antes do finalizador;

  • O.pagina em GET, depois do finalizador;

  • excluir.banco (com o id) após a exclusão, e status.banco (com id e novo status) após a troca de status.

Veja a doc de hooks para registrar ouvintes.

Parâmetros dos finalizadores

Os finalizadores de formulário (adicionar, editar, visualizar, config, alteracoes, simples, *-incomum) aceitam, conforme o caso:

Parâmetro Efeito
formulario ['validacao' => [...], 'campos' => [...], 'opcao' => …]: validação no cliente e campos gerados (abaixo)
botoes Botões do cabeçalho: [id => ['url','rotulo','tooltip','icon','cor', 'callback'?]]
botoes_rodape Botões extras ao pé do formulário, mesmo formato
sem_botao_padrao Remove o botão de enviar padrão
metaDados Lista [['titulo' => …, 'dado' => …]] exibida ao lado do formulário
removerNaoAlterarId / removerBotaoEditar Tiram o "não alterar id" e o botão de edição
variaveisTrocarDepois ['chave' => 'valor'] trocados como #chave# no fim da montagem
campoTitulo / forcarSemID visualizar: campo usado no título, ou dispensa de registro
banco, historico, callbackFunction status/excluir: outra tabela, sem histórico, e função chamada após a gravação

Os formulários trocam automaticamente todos os #form-…# do HTML pelas variáveis do módulo cujo id contém form (gestor_variaveis(['conjunto' => true, 'padrao' => 'form'])).

Listagem

$_GESTOR['interface']['listar']['finalizar'] = Array(
    'banco' => Array(
        'nome' => 'paginas', 'id' => 'id', 'status' => 'status',
        'campos' => Array('nome', 'caminho', 'data_modificacao'),
        'where' => "language='".$_GESTOR['linguagem-codigo']."'",
    ),
    'tabela' => Array(
        'rodape' => true,
        'colunas' => Array(
            Array('id' => 'nome', 'nome' => 'Nome', 'ordenar' => 'asc'),
            Array('id' => 'data_modificacao', 'nome' => 'Modificação', 'formatar' => 'dataHora', 'nao_procurar' => true),
        ),
    ),
    'opcoes' => Array(
        'editar' => Array('url' => 'editar/', 'tooltip' => '…', 'icon' => 'edit', 'cor' => 'basic blue'),
        'excluir' => Array('opcao' => 'excluir', 'tooltip' => '…', 'icon' => 'trash', 'cor' => 'basic red'),
    ),
    'botoes' => Array( /* botão "Adicionar" etc. */ ),
);

  • interface_listar_finalizar() desenha o layout interface-listar e o modal interface-delecao-modal, e inclui o DataTables. interface_listar_tabela() monta a primeira página no servidor e publica a configuração em javascript-vars.interface.lista.

  • A coluna de ações é a primeira (req-147) e usa uma chave própria (INTERFACE_COLUNA_ACOES), para o id dos botões nunca vir de uma coluna formatada.

  • Colunas: ordenar (asc/desc), nao_ordenar, nao_procurar, nao_visivel, className e formatar (veja Formatação).

  • Registros com status='D' nunca aparecem. A página atual, o total e o tamanho da página ficam numa variável de sessão por usuário (<modulo>-<opcao>-interface-<usuario>), que as próximas chamadas AJAX usam.

  • A paginação, a busca e a ordenação seguintes vêm por AJAX (ajax-opcao=listar) em interface_ajax_listar() → interface_listar_ajax(). A busca faz UCASE(coluna) LIKE UCASE('%termo%') em cada coluna pesquisável e em columnsExtraSearch (por padrão, id). Colunas, ordenação e colunas extras vêm só da configuração guardada na sessão pelo servidor; o columns enviado pelo DataTables serve apenas de índice, nome de coluna precisa ser um identificador simples (interface_listar_coluna_segura()) e o termo é escapado, com % e _ tratados como texto (req-189).

Formulários

Campos gerados (formulario.campos)

interface_formulario_campos() insere cada campo no marcador <span>#<id>#</span> da página, conforme o tipo:

tipo Gera
select <select> Fomantic a partir de tabela (nome, campo, id_numerico ou id, where, id_selecionado/valor_selecionado) ou de dados ([['texto','valor','icone'?]]). Opções: menu, procurar, limpar, multiple, fluid, disabled, placeholder e ícones
imagepick / imagepick-hosts Seletor de imagem do gerenciador de arquivos (id_arquivos/id_hosts_arquivos)
templates-hosts Seletor de template por categoria_id (template_id, template_tipo gestor/hosts)

Validação no navegador (formulario.validacao)

interface_formulario_validacao() publica regras para o validador do Fomantic/Tailwind. Cada item é ['regra', 'campo', 'label', 'identificador'?], e as regras são:

  • texto-obrigatorio (3 a 255 caracteres) e texto-obrigatorio-verificar-campo (além disso, consulta se o valor já existe);

  • selecao-obrigatorio, nao-vazio, maior-ou-igual-a-zero;

  • email, email-comparacao, email-comparacao-verificar-campo;

  • senha, senha-comparacao, dominio;

  • regexPermited e regexNecessary, com regrasExtra para regex próprias.

removerRegra tira regras padrão.

Validação no servidor

interface_validacao_campos_obrigatorios(['campos' => [...], 'redirect' => …]) confere o $_REQUEST antes de gravar. Na primeira falha, grava um alerta e redireciona (para redirect ou recarrega a URL), encerrando a requisição.

Regra Confere
texto-obrigatorio Tamanho entre min (padrão 3) e max (padrão 255), em bytes (strlen)
selecao-obrigatorio Campo preenchido
email-obrigatorio Regex própria de e-mail

  • interface_verificar_campos(['campo', 'valor', 'language'?]) diz se já existe outro registro ativo com aquele valor. Na edição, ignora o próprio registro, e pode olhar outra tabela via verificarCamposOutraTabela no JSON do módulo. É o que o AJAX verificar-campo (interface_ajax_verificar_campo()) usa. O docblock da função descreve outros parâmetros; os reais são estes.

Histórico

  • interface_historico_incluir(['alteracoes' => [['campo','alteracao','alteracao_txt','valor_antes','valor_depois','tabela','filtro']], …]) grava na tabela historico quem mudou o quê, ligado ao módulo e ao registro. Aceita deletar (conta a versão seguinte), sem_id, versao, tabela alternativa e ids manuais (id_numerico_manual, id_usuarios_manual, id_hosts_manual, modulo_id).

  • interface_historico(['id','modulo','pagina','sem_id'?]) desenha o histórico paginado na tela de edição. interface_ajax_historico_mais_resultados() traz as páginas seguintes.

Os CRUDs usam o par banco_select_campos_antes_iniciar()/banco_select_campos_antes() para saber o "antes" (veja banco.php).

Backups de campo

Para campos longos (HTML, CSS), cada versão pode ser guardada e restaurada:

  • interface_backup_campo_incluir(['campo','id_numerico','versao','valor','modulo'?,'maxCopias'?]) guarda a versão e apaga as mais antigas além de maxCopias;

  • interface_backup_campo_select([...]) desenha o dropdown de versões;

  • interface_ajax_backup_campo() devolve o valor escolhido.

Alertas

interface_alerta(['msg' => …]) agenda uma mensagem para a tela. Com redirect, ela sobrevive ao próximo redirecionamento (fica na sessão). O interface_finalizar() chama interface_alerta(['imprimir' => true]), que publica o alerta em javascript-vars.interface.alert e inclui o modal-alerta.

Formatação de dados

interface_formatar_dado(['dado' => …, 'formato' => …]) é usada nas colunas formatar da listagem. Os formatos são:

  • data e dataHora: DD/MM/AAAA e DD/MM/AAAA HHhMM;

  • dinheiroReais e dinheiroUSD;

  • telefone;

  • outraTabela: troca o id pelo nome de outra tabela, via interface_trocar_valor_outra_tabela();

  • outroConjunto e outroArray: troca por um mapa (interface_trocar_valor_outro_conjunto() e interface_trocar_valor_outro_array());

  • encapsular: põe o dado dentro de um texto, via interface_encapsular_valor().

formato também pode ser uma lista, aplicada em sequência, com valor_senao_existe e valor_substituir_por_rotulo.

As funções auxiliares de formatação:

  • interface_data_hora_from_datetime_to_text($dt, $formato = false) usa por padrão o formato D/ME/A HhMI (D, ME, A, H, MI e S são trocados pelas partes da data);

  • interface_data_from_datetime_to_text($dt) devolve DD/MM/AAAA;

  • interface_formatar_telefone($tel) formata números brasileiros com e sem +55 e o padrão norte-americano +1; o resto sai só com + na frente.

Componentes e assets

  • interface_componentes_incluir(['componente' => [...]]) marca componentes (modais de carregamento, deleção e alerta…), e interface_componentes() os renderiza no fim da página, na variante certa.

  • interface_componente_variante($id) devolve <id>-tailwind numa requisição só Tailwind; interface_componente_canonico($id) tira o sufixo. Assim o mesmo módulo serve Fomantic e Tailwind sem mudar código (req-118).

  • interface_assets_incluir() inclui interface/interface-tailwind.js (Tailwind puro) ou interface/interface.css + interface/interface.js (Fomantic/híbrido).

  • interface_botoes_cabecalho() e interface_botoes_rodape() desenham os botões a partir de botoes/botoes_rodape, pelo interface_botoes_html($botoes). Em página só Tailwind saem <a>/<button> com utilities e ícone Lucide (req-190): interface_botao_tailwind_classes($cor) traduz a cor do Fomantic (blue, green, red, basic …) em um de quatro tons, e interface_botao_tailwind_icone($icone) traduz o nome do ícone (sem tradução, o botão fica só com o rótulo). O excluir leva a URL em data-href e abre o modal de deleção. As classes ficam no <template data-c2f-botoes> dos componentes interface-formulario-*-tailwind; classe nova no PHP precisa entrar lá, senão sai sem estilo. Incluir e editar têm variante Tailwind; a listagem ainda é Fomantic.

  • interface_modulo_variavel_valor(['variavel' => …]) lê um campo do registro atual do módulo (usado para compor o título "Nome - …").

Segurança e defeitos conhecidos

Excluir e status exigem o token CSRF. Essas duas ações agem por GET (?opcao=excluir&id=…, ?opcao=status&status=I&id=…), e a validação global de CSRF só cobre POST/PUT/PATCH/DELETE. Por isso interface_excluir_iniciar() e interface_status_iniciar() chamam interface_acao_get_exigir_csrf(), que exige o token da sessão na query (_csrf_token); sem ele, mostram um alerta e voltam à raiz do módulo sem alterar nada (req-189). Os links do painel já saem com o token: interface_url_csrf($url) nos botões renderizados pelo servidor e window.interfaceUrlCsrf(url) nos links montados pelo interface.js/interface-v2.js. Link de excluir ou status montado à mão num módulo precisa passar por uma das duas.

Outros defeitos: interface_editar_finalizar() e interface_alteracoes_finalizar() passam 'id' => $id ao histórico sem definir $id (warning de variável indefinida). Sem efeito no resultado, porque interface_historico() ignora esse parâmetro e filtra pelo id_numerico do registro atual.

Veja também

Funções (referência gerada)

Gerado a partir de gestor/bibliotecas/interface.php · 65 funções

65 de 65

interface_data_hora_from_datetime_to_text

ver no código · linha 38 ↗
interface_data_hora_from_datetime_to_text(string $data_hora, string|false $format = false): string

Converte data/hora do formato datetime (YYYY-MM-DD HH:MM:SS) para texto formatado.

Parâmetros

$data_horastring
Data/hora no formato datetime (YYYY-MM-DD HH:MM:SS)
$formatstring|false
Formato personalizado usando marcadores ou false para formato padrão

Retorno

string
Data/hora formatada ou string vazia se não houver data

interface_data_from_datetime_to_text

ver no código · linha 91 ↗
interface_data_from_datetime_to_text(string $data_hora): string

Converte data do formato datetime (YYYY-MM-DD) para texto no formato brasileiro (DD/MM/YYYY).

Parâmetros

$data_horastring
Data/hora no formato datetime (YYYY-MM-DD HH:MM:SS)

Retorno

string
Data formatada (DD/MM/YYYY)

interface_trocar_valor_outra_tabela

ver no código · linha 122 ↗
interface_trocar_valor_outra_tabela(array|false $params = false): string|array

Busca e substitui valores de um campo usando referência de outra tabela.

Parâmetros

$paramsarray|false
Parâmetros da função:

Retorno

string|array
Valor trocado, array de valores (se camposExtras) ou resultado encapsulado

interface_trocar_valor_outro_conjunto

ver no código · linha 260 ↗
interface_trocar_valor_outro_conjunto(array|false $params = false): string

Troca um valor por outro baseado em um conjunto de mapeamentos.

Parâmetros

$paramsarray|false
Parâmetros da função.

Retorno

string
O valor trocado se encontrado no conjunto, ou o dado original caso contrário.

interface_trocar_valor_outro_array

ver no código · linha 296 ↗
interface_trocar_valor_outro_array(array|false $params = false): string

Troca um valor por outro baseado em array de valores com campos específicos.

Parâmetros

$paramsarray|false
Parâmetros da função.

Retorno

string
O valor do campo alvo se encontrado, ou o dado original caso contrário.

interface_encapsular_valor

ver no código · linha 331 ↗
interface_encapsular_valor(array|false $params = false): string

Encapsula um valor dentro de uma cápsula de texto.

Parâmetros

$paramsarray|false
Parâmetros da função.

Retorno

string
O valor encapsulado se encontrado, ou o dado original caso contrário.

interface_formatar_telefone

ver no código · linha 356 ↗
interface_formatar_telefone(string $telefone): string

Formata um número de telefone para exibição.

Parâmetros

$telefonestring
Número de telefone (pode conter +, espaços, hífens, parênteses).

Retorno

string
Telefone formatado ou valor original se não for possível formatar.

interface_formatar_dado

ver no código · linha 437 ↗
interface_formatar_dado(array|false $params = false): string

Formata um dado de acordo com o formato especificado.

Parâmetros

$paramsarray|false
Parâmetros da função.

Retorno

string
O dado formatado de acordo com as especificações, ou valor padrão se dado estiver vazio.

interface_alerta

ver no código · linha 548 ↗
interface_alerta(array|false $params = false): void|string

Gerencia alertas de mensagens para o usuário na interface.

Parâmetros

$paramsarray|false
Parâmetros da função.

Retorno

void|string
Retorna HTML do alerta se $imprimir for true, caso contrário não retorna nada.

interface_historico

ver no código · linha 766 ↗
interface_historico(array|false $params = false): void

Exibe o histórico de alterações de um registro do sistema.

Parâmetros

$paramsarray|false
Parâmetros da função.

Retorno

void
Exibe o HTML do histórico diretamente.

interface_componente_variante

ver no código · linha 1235 ↗
interface_componente_variante(string $id, string|null $modo = null): string

Devolve o id da variante Tailwind de um componente quando a requisição é Tailwind pura.

Parâmetros

$idstring
Id canônico do componente.
$modostring|null
Modo resolvido; quando omitido, usa o da requisição corrente.

Retorno

string
Id a carregar.

interface_status_selo

ver no código · linha 1270 ↗
interface_status_selo(string $status): string

Selo de status (ativo/inativo) dos metadados da tela de edição (req-219).

Parâmetros

$statusstring
'A' (ativo) ou 'I' (inativo); outro valor devolve string vazia.

Retorno

string
HTML do selo.

interface_verificar_campos

ver no código · linha 3180 ↗
interface_verificar_campos(array|false $params = false): array

Verifica alterações em campos comparando valores atuais com valores anteriores.

Parâmetros

$paramsarray|false
Parâmetros da função.

Retorno

array
Lista de campos que foram alterados.

interface_botoes_cabecalho

ver no código · linha 3247 ↗
interface_botoes_cabecalho(array|false $params = false): void

Renderiza botões de ação no cabeçalho da interface administrativa.

Parâmetros

$paramsarray|false
Parâmetros da função.

Retorno

void
Renderiza HTML dos botões diretamente.

interface_botoes_rodape

ver no código · linha 3266 ↗
interface_botoes_rodape(array|false $params = false): string

Renderiza botões de ação no rodapé da interface administrativa.

Parâmetros

$paramsarray|false
Parâmetros da função.

Retorno

string
HTML dos botões do rodapé.

interface_botoes_html

ver no código · linha 3285 ↗
interface_botoes_html(array $botoes): string

Monta o HTML de um conjunto de botões (cabeçalho ou rodapé), no framework CSS da página.

Parâmetros

$botoesarray
Botões por id: cor, icon, icon2, rotulo, tooltip, url, callback, target.

Retorno

string
HTML dos botões.

interface_acao_get_exigir_csrf

ver no código · linha 3668 ↗
interface_acao_get_exigir_csrf()

req-189 (A2): excluir e status agem por GET (?opcao=excluir&id=…), e a validação global de CSRF só cobre POST/PUT/PATCH/DELETE. Com o cookie SameSite=Lax, um link aberto por um administrador logado bastava para excluir ou desativar registros. Essas ações passam a exigir o token da sessão na query (_csrf_token); os links do painel já saem com ele (interface_url_csrf() e window.interfaceUrlCsrf). Sem o token: alerta e volta à raiz do módulo, sem alterar nada.

interface_excluir_finalizar

ver no código · linha 3723 ↗
interface_excluir_finalizar(array|false $params = false): void

Finaliza a interface de exclusão de registro (exclusão lógica).

Parâmetros

$paramsarray|false
Parâmetros da função.

Retorno

void
Executa exclusão e redireciona para listagem.

interface_status_iniciar

ver no código · linha 3839 ↗
interface_status_iniciar(array|false $params = false): void

Inicializa a interface de alteração de status de registro.

Parâmetros

$paramsarray|false
Parâmetros da função (não utilizado nesta função).

Retorno

void
Prepara $_GESTOR para alteração de status ou redireciona.

interface_status_finalizar

ver no código · linha 3875 ↗
interface_status_finalizar(array|false $params = false): void

Finaliza a interface de alteração de status de registro.

Parâmetros

$paramsarray|false
Parâmetros da função.

Retorno

void
Executa alteração de status e redireciona para listagem.

Listagem e estado no painel Tailwind

A listagem Tailwind delega a interface-listar-tailwind.php e ao seu script, com paginação e ordenação no servidor, sem DataTables. A variante clássica mantém DataTables. interface_status_selo aceita A/I e retorna selo ativo/inativo em Tailwind; outros valores devolvem vazio. Formulários e visualização usam variantes de componentes conforme o framework efetivo. Veja Interface administrativa.

Verificado contra o código no commit 914c7b10

Fontes:

O Futuro é Híbrido: Humano + IA.

O Conn2Flow é a ferramenta. Se você precisa do Arquiteto para desenhar a estratégia da sua empresa usando essa tecnologia...

Contrate Consultoria Especializada