interface.php library

Path in the Gestor bibliotecas/interface.php

interface.php is the admin panel's CRUD engine. An admin module does not build listing, editing and deletion screens by hand: it states what it wants (table, columns, fields, validations, buttons), and the library draws the screen from components (interface-listar, interface-formulario-edicao…), records history, handles the standard AJAX calls and fires the hooks.

Request the library in the module JSON ("bibliotecas": ["interface", …]).

A module's cycle

Every module controller follows the same skeleton:

function my_module_start(){
    global $_GESTOR;
    gestor_incluir_bibliotecas();
    if($_GESTOR['ajax']){
        interface_ajax_iniciar();
        switch($_GESTOR['ajax-opcao']){ /* the module's own AJAX */ }
        interface_ajax_finalizar();          // standard AJAX: list, history, backup, verify-field
    } else {
        my_module_interfaces_padroes();      // fills $_GESTOR['interface'][<option>]
        interface_iniciar();
        switch($_GESTOR['opcao']){
            case 'adicionar': my_module_add(); break;
            case 'editar':    my_module_edit(); break;
        }
        interface_finalizar();
    }
}

• interface_iniciar() runs before the module code. It reads $_GESTOR['opcao'] (and $_GESTOR['interface-opcao'] when present), calls the matching interface_<option>_iniciar() with the parameters in $_GESTOR['interface'][<option>]['iniciar'] and sets the flags the module checks:

  • $_GESTOR['adicionar-banco'] when the add form was submitted (_gestor-adicionar);

  • $_GESTOR['atualizar-banco'] when the edit form was submitted (_gestor-atualizar);

  • $_GESTOR['modulo-registro-id'] with the record id (?id= on GET, or _gestor-registro-id). Without an id on options that need one, it redirects to the module root.

• interface_finalizar() runs afterwards. It calls interface_<option>_finalizar() with $_GESTOR['interface'][<option>]['finalizar'], which draws the screen into $_GESTOR['pagina'], then prints the pending alert and renders the marked components.

• With $_GESTOR['interface-nao-aplicar'], both do nothing.

Options

The handlers of each option:

Hooks fired

For module X and option O (and also for the interface-opcao):

• hook_do_action('X', 'O.pre-banco') on every POST, before the module code;

• O.parametros on GET, before the finisher;

• O.pagina on GET, after the finisher;

• excluir.banco (with the id) after deletion, and status.banco (with id and new status) after a status change.

See the hooks doc to register listeners.

Finisher parameters

The form finishers (adicionar, editar, visualizar, config, alteracoes, simples, *-incomum) accept, depending on the case:

Forms automatically replace every #form-…# in the HTML with the module variables whose id contains form (gestor_variaveis(['conjunto' => true, 'padrao' => 'form'])).

Listing

$_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' => 'Name', 'ordenar' => 'asc'),
            Array('id' => 'data_modificacao', 'nome' => 'Modified', '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( /* "Add" button etc. */ ),
);

• interface_listar_finalizar() draws the interface-listar layout and the interface-delecao-modal modal, and includes DataTables. interface_listar_tabela() builds the first page on the server and publishes the configuration in javascript-vars.interface.lista.

• The actions column is the first one (req-147) and uses its own key (INTERFACE_COLUNA_ACOES), so that button ids never come from a formatted column.

• Columns: ordenar (asc/desc), nao_ordenar, nao_procurar, nao_visivel, className and formatar (see Formatting).

• Records with status='D' never show up. The current page, total and page size live in a per-user session variable (<module>-<option>-interface-<user>), which later AJAX calls use.

• Subsequent pagination, search and sorting come via AJAX (ajax-opcao=listar) in interface_ajax_listar() → interface_listar_ajax(). The search runs UCASE(column) LIKE UCASE('%term%') on each searchable column and on columnsExtraSearch (id by default). Columns, sorting and extra columns come only from the configuration stored in the session by the server; the columns sent by DataTables is used just as an index, a column name must be a plain identifier (interface_listar_coluna_segura()) and the term is escaped, with % and _ treated as text (req-189).

Forms

Generated fields (formulario.campos)

interface_formulario_campos() inserts each field into the page's <span>#<id>#</span> marker, according to its tipo:

Browser validation (formulario.validacao)

interface_formulario_validacao() publishes rules for the Fomantic/Tailwind validator. Each item is ['regra', 'campo', 'label', 'identificador'?], and the rules are:

• texto-obrigatorio (3 to 255 characters) and texto-obrigatorio-verificar-campo (which also checks whether the value already exists);

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

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

• senha, senha-comparacao, dominio;

• regexPermited and regexNecessary, with regrasExtra for custom regexes.

removerRegra drops default rules.

Server validation

interface_validacao_campos_obrigatorios(['campos' => [...], 'redirect' => …]) checks $_REQUEST before saving. On the first failure it stores an alert and redirects (to redirect, or reloads the URL), ending the request.

• interface_verificar_campos(['campo', 'valor', 'language'?]) tells whether another active record already holds that value. When editing it ignores the record itself, and it can look into another table via verificarCamposOutraTabela in the module JSON. This is what the verificar-campo AJAX (interface_ajax_verificar_campo()) uses. The function's docblock describes other parameters; the real ones are these.

History

• interface_historico_incluir(['alteracoes' => [['campo','alteracao','alteracao_txt','valor_antes','valor_depois','tabela','filtro']], …]) stores in the historico table who changed what, linked to the module and the record. It accepts deletar (counts the next version), sem_id, versao, an alternative tabela and manual ids (id_numerico_manual, id_usuarios_manual, id_hosts_manual, modulo_id).

• interface_historico(['id','modulo','pagina','sem_id'?]) draws the paginated history on the edit screen. interface_ajax_historico_mais_resultados() loads the next pages.

CRUDs use the banco_select_campos_antes_iniciar()/banco_select_campos_antes() pair to know the "before" (see banco.php).

Field backups

For long fields (HTML, CSS), each version can be kept and restored:

• interface_backup_campo_incluir(['campo','id_numerico','versao','valor','modulo'?,'maxCopias'?]) stores the version and deletes the oldest ones beyond maxCopias;

• interface_backup_campo_select([...]) draws the version dropdown;

• interface_ajax_backup_campo() returns the chosen value.

Alerts

interface_alerta(['msg' => …]) schedules a message for the screen. With redirect, it survives the next redirect (it is kept in the session). interface_finalizar() calls interface_alerta(['imprimir' => true]), which publishes the alert in javascript-vars.interface.alert and includes modal-alerta.

Data formatting

interface_formatar_dado(['dado' => …, 'formato' => …]) is used by the listing's formatar columns. The formats are:

• data and dataHora: DD/MM/YYYY and DD/MM/YYYY HHhMM;

• dinheiroReais and dinheiroUSD;

• telefone;

• outraTabela: replaces the id with a name from another table, through interface_trocar_valor_outra_tabela();

• outroConjunto and outroArray: replace through a map (interface_trocar_valor_outro_conjunto() and interface_trocar_valor_outro_array());

• encapsular: wraps the value in a text, through interface_encapsular_valor().

formato may also be a list, applied in sequence, with valor_senao_existe and valor_substituir_por_rotulo.

The formatting helpers:

• interface_data_hora_from_datetime_to_text($dt, $format = false) uses the D/ME/A HhMI format by default (D, ME, A, H, MI and S are replaced by the date parts);

• interface_data_from_datetime_to_text($dt) returns DD/MM/YYYY;

• interface_formatar_telefone($phone) formats Brazilian numbers with and without +55 and the North American +1 pattern; anything else just gets a leading +.

Components and assets

• interface_componentes_incluir(['componente' => [...]]) marks components (loading, delete and alert modals…), and interface_componentes() renders them at the end of the page, in the right variant.

• interface_componente_variante($id) returns <id>-tailwind on a Tailwind-only request; interface_componente_canonico($id) strips the suffix. That way the same module serves Fomantic and Tailwind without code changes (req-118).

• interface_assets_incluir() includes interface/interface-tailwind.js (pure Tailwind) or interface/interface.css + interface/interface.js (Fomantic/hybrid).

• interface_botoes_cabecalho() and interface_botoes_rodape() draw the buttons from botoes/botoes_rodape, through interface_botoes_html($botoes). On a Tailwind-only page they output <a>/<button> with utilities and a Lucide icon (req-190): interface_botao_tailwind_classes($cor) maps the Fomantic color (blue, green, red, basic …) to one of four tones, and interface_botao_tailwind_icone($icone) maps the icon name (with no match, the button keeps only its label). excluir carries the URL in data-href and opens the delete modal. The classes live in the <template data-c2f-botoes> of the interface-formulario-*-tailwind components; a new class in the PHP must be added there too, or it renders unstyled. Add and edit have a Tailwind variant; the listing is still Fomantic.

• interface_modulo_variavel_valor(['variavel' => …]) reads a field of the module's current record (used to build the "Name - …" title).

Security and known defects

Delete and status require the CSRF token. These two actions run on GET (?opcao=excluir&id=…, ?opcao=status&status=I&id=…), and the global CSRF check only covers POST/PUT/PATCH/DELETE. So interface_excluir_iniciar() and interface_status_iniciar() call interface_acao_get_exigir_csrf(), which requires the session token in the query (_csrf_token); without it they show an alert and go back to the module root without changing anything (req-189). Panel links already carry the token: interface_url_csrf($url) on buttons rendered by the server and window.interfaceUrlCsrf(url) on links built by interface.js/interface-v2.js. A delete or status link built by hand in a module must go through one of them.

Other defects: interface_editar_finalizar() and interface_alteracoes_finalizar() pass 'id' => $id to the history without defining $id (undefined variable warning). It has no effect on the result, because interface_historico() ignores that parameter and filters by the current record's id_numerico.

See also

• gestor.php library, banco.php library, Gestor libraries

Functions (generated reference)

interface_data_hora_from_datetime_to_text(string $data_hora, string|false $format = false): string

interface_data_from_datetime_to_text(string $data_hora): string

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

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

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

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

interface_formatar_telefone(string $telefone): string

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

interface_alerta(array|false $params = false): void|string

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

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

interface_assets_incluir(): void

interface_componente_variante(string $id, string|null $modo = null): string

interface_componente_canonico(string $id): string

interface_status_selo(string $status): string

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

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

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

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

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

interface_modulo_variavel_valor(array|false $params = false): mixed

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

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

interface_verificar_campos(array|false $params = false): array

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

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

interface_botoes_html(array $botoes): string

interface_botao_tailwind_classes(string $cor): string

interface_botao_tailwind_icone(string $icone): string

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

interface_ajax_historico_mais_resultados(): void

interface_ajax_listar(): void

interface_ajax_verificar_campo(): void

interface_acao_get_exigir_csrf()

interface_url_csrf(string $url): string

interface_excluir_iniciar($params = false)

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

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

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

interface_adicionar_iniciar($params = false)

interface_clonar_iniciar($params = false)

interface_adicionar_finalizar($params = false)

interface_adicionar_incomum_iniciar($params = false)

interface_adicionar_incomum_finalizar($params = false)

interface_editar_incomum_iniciar($params = false)

interface_editar_incomum_finalizar($params = false)

interface_editar_iniciar($params = false)

interface_editar_finalizar($params = false)

interface_visualizar_iniciar($params = false)

interface_visualizar_finalizar($params = false)

interface_config_iniciar($params = false)

interface_config_finalizar($params = false)

interface_alteracoes_iniciar($params = false)

interface_alteracoes_finalizar($params = false)

interface_simples_iniciar($params = false)

interface_simples_finalizar($params = false)

interface_listar_coluna_segura(string $coluna): bool

interface_listar_ajax($params = false)

interface_listar_tabela($params = false)

interface_listar_iniciar($params = false)

interface_listar_finalizar($params = false)

interface_ajax_iniciar($params = false)

interface_ajax_finalizar($params = false)

interface_iniciar($params = false)

interface_finalizar($params = false)

Tailwind panel lists and status

Tailwind lists delegate to interface-listar-tailwind.php and its script, using server paging/ordering without DataTables. The classic variant retains DataTables. interface_status_selo accepts A/I and returns an active/inactive Tailwind badge; other values return empty. Forms and view pages choose component variants by effective framework. See Administrative interface.