frameheader() abre uma secção visual (frame) na página. Apresenta o título do plugin ou da secção e cria o contentor HTML no qual o conteúdo será renderizado. Utilização: frameheader('O meu título', 'h3', false). Os níveis de título seguem a hierarquia HTML: h1 para o título da página (uma única vez), h2 para as secções principais, h3 e seguintes para as frames e widgets. Um plugin chamado diretamente deve começar por: if($obj=='o_meu_plugin.php') frameheader($dialplugindisplay); — esta condição evita a apresentação dupla do cabeçalho quando o plugin é incluído a partir de outro script.

framefooter() fecha a frame aberta por frameheader(). É indispensável antes de abrir uma nova secção com frameheader(). Nunca chame framefooter() sem um frameheader() a seguir, exceto no fim da página. O padrão clássico para estruturar uma página em vários blocos: frameheader('Secção 1'); /* conteúdo */ framefooter(); frameheader('Secção 2'); /* conteúdo */. O motor trata automaticamente do fecho final.

Use o par framefooter() / frameheader() para encadear as secções. Cada secção cria um bloco visual distinto com o seu próprio título. Exemplo: depois de apresentar um formulário e receber um erro, feche a frame atual com framefooter(), abra uma nova frame limpa com frameheader(''), inclua novamente o formulário e faça return. Assim, o utilizador permanece numa página válida e enquadrada, sem redirecionamento HTTP.

secure() verifica se o nível do utilizador com sessão iniciada é suficiente para aceder a um recurso. Recebe como parâmetro uma constante de nível (BASE_LEVEL_ADMIN, PLUGIN_LEVEL_MODERATOR, etc.) e devolve true ou false. O padrão normal: frameheader($dialplugindisplay); if(!secure(PLUGIN_LEVEL_MODERATOR)) { forbids(); return; }. A frame é aberta ANTES da verificação — forbids() é apresentado dentro da frame, caso contrário o layout fica partido. O truque secure(0) verifica simplesmente se o utilizador tem sessão iniciada.

Nenhum para a configuração e as bibliotecas — o motor XDP carrega-as automaticamente. O único include autorizado é o da locale: include(getlocale('nome_do_plugin'));. Os ficheiros .conf.inc.php e .lib.inc.php são detetados e carregados pelo motor. Fazer um require ou include manual da configuração ou das libs provoca um warning e um caminho partido. Do mesmo modo, nunca inclua um módulo (.mod.php) — são chamados exclusivamente através de ?obj=nome.mod.

Cada plugin tem os seus ficheiros de tradução em /locale/nome_do_plugin.XX.inc.php (XX = código de língua ISO). O carregamento é feito através de include(getlocale('nome_do_plugin'));, a chamar ANTES de frameheader() para evitar erros de variável em falta. As traduções usam um array $dialnomeplugin[]. $dialplugindisplay contém o título apresentado do plugin, $dialplugincall o nome no centro de controlo. getAvailableLanguages() devolve a lista das línguas disponíveis.

Use a variável global $headdata para injetar no <head>: $headdata .= '<link rel="stylesheet" type="text/css" href="plugins/o_meu_plugin/css/o_meu_plugin.css">'; Para o JavaScript, o princípio é o mesmo: $headdata .= '<script src="plugins/o_meu_plugin/js/o_meu_plugin.js"></script>'; Para executar JS depois do DOM, use $footdata com um heredoc. As CSS devem usar as variáveis definidas em core.css — nunca invente cores. Se faltar uma variável, proponha acrescentá-la a core.css.

Use o Sanitizer: use Beamreactor\Sanitizer\Parser; e depois Parser::sanitize($input, 'type'). Os tipos disponíveis incluem: bool, date, email, name, html, xml, uuid, url, string, ip, float, int, path e outros. sanitize() limpa e valida o dado, devolvendo false se for inválido. check() verifica o formato sem limpar. Faça sempre a sanitização ANTES de qualquer operação SQL. Nunca invente um datatype — proponha um se necessário.

Use a classe SQL: use Beamreactor\Database\SQL;. Métodos principais: SQL::query() para várias linhas, SQL::queryFirst() para uma só linha, SQL::queryValue() para um valor único, SQL::insertRow() para inserir, SQL::updateRow() para atualizar, SQL::deleteRow() para eliminar. Use sempre consultas preparadas com parâmetros ?. A concatenação direta de variáveis no SQL é estritamente proibida. Verifique que a BD está disponível com isset($cfg['dbtable']) e que a sua tabela existe com SQL::tableExists().

Os módulos (.mod.php) são os endpoints AJAX do BeamReactor. Respondem em JSON, XML, HTML ou texto. Ficam em /handlers/nome_plugin.mod.php e são chamados através de ?obj=nome_plugin.mod (sem o .php). Nunca chame o caminho completo do ficheiro. Estrutura mínima: verificação de frameheader, segurança com secure(), header Content-Type, tratamento da ação através de Parser::sanitize(), resposta JSON com ['success' => !!1] ou ['success' => !!0]. Do lado do JavaScript, a chamada faz-se com $.post(BEAM_BASE_URL + '?obj=nome_plugin.mod', {...}).

Tudo no BeamReactor passa pelo index.php. O parâmetro ?obj= determina o que é carregado. Um plugin: ?obj=o_meu_plugin.php. Um módulo AJAX: ?obj=o_meu_plugin.mod. Um documento: ?obj=a_minha_pagina.dta. O motor XDP resolve o caminho, carrega automaticamente a configuração, as libs e a locale, e executa o script num ambiente seguro. Nenhum script PHP pode ser chamado diretamente — tudo passa pelo motor.

O BeamReactor dispõe de um sistema de toasts com 6 níveis: debug (0), info (1), success (2), warning (3), error (4), critical (5). Utilização rápida: Toast::info('Título', 'Mensagem', 5000); ou Toast::add(Toast::LEVEL_WARNING, 'Título', 'Mensagem', BASE_LEVEL_USER, 0). O parâmetro minUserLevel permite direcionar as notificações por nível de acesso. A duração é em milissegundos, 0 para persistente.

Um plugin é uma pasta autónoma em /plugins/nome_do_plugin/ que contém: nome_do_plugin.php (interface principal), /conf/ (configuração carregada automaticamente), /lib/ (bibliotecas carregadas automaticamente), /locale/ (traduções por língua), /handlers/ (endpoints AJAX .mod.php), /css/, /js/, /images/, /sql/ (instalação das tabelas), /tests/, /doc/ (documentação .md e ajuda .help.json) e /data/cache/ para os dados persistentes. A instalação consiste em colocar a pasta. A remoção consiste em retirá-la.

O BeamReactor substitui os alert/confirm/prompt nativos por diálogos personalizados definidos em javascript/dialogs.js.php. Quatro funções: alertWindow('Título', 'mensagem') para um alerta, confirmWindow('Título', 'pergunta?', {}, callback) para uma confirmação, promptWindow('Título', 'Etiqueta:', {}, callback) para uma introdução de dados, infoWindow('Título', 'info') para uma informação. Nunca use alert(), confirm() ou prompt() nativos.

No ficheiro de locale do plugin, defina um array $js_translations e chame setJavascriptLocale($js_translations). Exemplo: $js_translations = ['o_meu_plugin' => ['error_msg' => $dialomeuplugin[5]], 'global' => ['error' => $dial[32]]]; setJavascriptLocale($js_translations);. Do lado do JavaScript, aceda às traduções através de PLUGIN_TRANSLATION.o_meu_plugin.error_msg. As traduções são injetadas no head como um objeto JavaScript global.

Não. Os plugins nunca podem usar exit ou die. O único exit autorizado em todo o código de um plugin é if(!function_exists('frameheader')) die('forbidden'); na primeira linha, que verifica o contexto BeamReactor. Para interromper a execução, use return. Para tratar um erro, apresente a mensagem dentro da frame e faça return. Se um plugin usar exit ou die, o motor não consegue saber o que falhou e o diagnóstico torna-se impossível.

O BeamReactor usa uma hierarquia fixa: OVERMIND > ADMIN > MODERATOR > HIGHUSER > USER. As constantes BASE_LEVEL_* são definidas em cog.inc.php. Cada plugin pode definir os seus próprios níveis através de NOME_PLUGIN_LEVEL_* na sua configuração. $basedisplevel usa sempre BASE_LEVEL_*, nunca PLUGIN_LEVEL_*. Os define() personalizados fazem-se depois de $basedisplevel. O sistema completa automaticamente os níveis em falta através de base_user_levels().

Os ficheiros .lib.inc.php e .conf.inc.php são carregados automaticamente pelo motor. Para classes adicionais, registe um autoloader PSR-4 na configuração do plugin com spl_autoload_register(). O namespace segue a convenção Beamreactor\NomePlugin\. Os ficheiros de classe ficam em /lib/ e são resolvidos pelo caminho relativo ao namespace. Isto permite que vários plugins coexistam sem colisão de nomes.

Para proteger a sua conta, são necessários dois passos. Os utilizadores registados devem iniciar sessão na interface principal do BeamReactor. Clicando no botão «Perfil», no canto superior esquerdo, acede ao seu perfil. Na parte inferior encontra um código QR 2FA para ler com uma aplicação como o Google Authenticator ou o Microsoft Authenticator. Serão disponibilizados códigos de recuperação: copie-os com cuidado para recuperar a sua conta em caso de perda ou roubo do telemóvel.

Inicie sessão com o seu nome de utilizador e palavra-passe no site BeamReactor. O sistema pedir-lhe-á depois um código, que encontra na aplicação Authenticator do seu telemóvel.

Atualize o sistema operativo do seu telemóvel e a aplicação Google ou Microsoft Authenticator para as versões mais recentes. Se não conseguir iniciar sessão mas ainda tiver acesso ao e-mail da sua conta, experimente alterar a palavra-passe. Sem acesso ao e-mail, contacte-nos através do formulário de suporte.

Pode redefini-la a qualquer momento clicando na ligação «Não consegue aceder à conta?» na página de início de sessão.

Utilize um dos códigos de recuperação fornecidos no registo da 2FA. Na página de autenticação, clique em «Código de recuperação», introduza-o e, depois de iniciar sessão, atualize as definições 2FA no seu perfil.

Novo aparelho, novo sistema, reinstalação após uma formatação: o procedimento é idêntico ao de um telemóvel perdido. Utilize os seus códigos de recuperação para iniciar sessão e depois sincronize o novo aparelho através do seu perfil de utilizador.

A autenticação de dois fatores (2FA) acrescenta uma camada de proteção indispensável, exigindo uma prova de identidade adicional. Garante que, mesmo que a sua palavra-passe seja roubada, um terceiro não consegue aceder aos seus dados. É a barreira mais eficaz contra tentativas de usurpação de identidade e de pirataria de contas.