F.A.Q.
Funktionen und Architektur
Technische Fragen zur XDP-Engine, Plugins, Sicherheit, dem Frame-System und den Entwicklungskonventionen von BeamReactor.
Wozu dient frameheader()?+
frameheader() öffnet einen visuellen Abschnitt (Frame) auf der Seite. Sie zeigt den Plugin- oder Abschnittstitel an und erstellt den HTML-Container, in dem der Inhalt gerendert wird. Verwendung: frameheader('Mein Titel', 'h3', false). Die Titelebenen folgen der HTML-Hierarchie: h1 für den Seitentitel (nur einmal), h2 für Hauptabschnitte, h3 und darüber für Frames und Widgets. Ein direkt aufgerufenes Plugin muss beginnen mit: if($obj=='mein_plugin.php') frameheader($dialplugindisplay); — diese Bedingung verhindert die doppelte Header-Anzeige, wenn das Plugin von einem anderen Skript eingebunden wird.
Wann sollte ich framefooter() verwenden?+
framefooter() schließt den von frameheader() geöffneten Frame. Sie ist erforderlich, bevor ein neuer Abschnitt mit frameheader() geöffnet wird. Rufen Sie framefooter() nie ohne ein folgendes frameheader() auf, außer am Seitenende. Das Standardmuster für die Strukturierung einer Seite in mehrere Blöcke: frameheader('Abschnitt 1'); /* Inhalt */ framefooter(); frameheader('Abschnitt 2'); /* Inhalt */. Die Engine übernimmt das abschließende Schließen automatisch.
Wie strukturiere ich eine Seite mit mehreren Abschnitten?+
Verwenden Sie das Paar framefooter() / frameheader(), um Abschnitte zu verketten. Jeder Abschnitt erstellt einen eigenständigen visuellen Block mit eigenem Titel. Beispiel: Nach dem Anzeigen eines Formulars und einem Fehler schließen Sie den aktuellen Frame mit framefooter(), öffnen einen neuen sauberen Frame mit frameheader(''), binden das Formular erneut ein und machen return. So bleibt der Benutzer auf einer gültigen, korrekt gerahmten Seite ohne HTTP-Weiterleitung.
Wie funktioniert secure()?+
secure() prüft, ob die Stufe des eingeloggten Benutzers für den Zugriff auf eine Ressource ausreicht. Sie nimmt eine Stufenkonstante als Parameter (BASE_LEVEL_ADMIN, PLUGIN_LEVEL_MODERATOR, usw.) und gibt true oder false zurück. Das Standardmuster: frameheader($dialplugindisplay); if(!secure(PLUGIN_LEVEL_MODERATOR)) { forbids(); return; }. Der Frame wird VOR der Prüfung geöffnet — forbids() wird im Frame angezeigt, sonst bricht das Layout. Der Trick secure(0) prüft einfach, ob der Benutzer überhaupt eingeloggt ist.
Welche Includes sollte ich in einem Plugin verwenden?+
Keine für Konfiguration und Bibliotheken — die XDP-Engine lädt sie automatisch. Das einzig erlaubte Include ist für die Locale: include(getlocale('plugin_name'));. Dateien mit .conf.inc.php und .lib.inc.php werden von der Engine erkannt und geladen. Manuelles require oder include für Konfiguration oder Libs verursacht eine Warnung und einen fehlerhaften Pfad. Ebenso niemals ein Modul (.mod.php) einbinden — sie werden ausschließlich über ?obj=name.mod aufgerufen.
Wie funktionieren Übersetzungen in einem Plugin?+
Jedes Plugin hat seine Übersetzungsdateien in /locale/plugin_name.XX.inc.php (XX = ISO-Sprachcode). Das Laden erfolgt über include(getlocale('plugin_name'));, das VOR frameheader() aufgerufen werden muss, um Fehler durch fehlende Variablen zu vermeiden. Übersetzungen verwenden ein Array $dialpluginname[]. $dialplugindisplay enthält den angezeigten Plugin-Titel, $dialplugincall den Namen im Kontrollzentrum. getAvailableLanguages() gibt die Liste der verfügbaren Sprachen zurück.
Wie lade ich plugin-spezifisches CSS oder JavaScript?+
Verwenden Sie die globale Variable $headdata zur Injektion in <head>: $headdata .= '<link rel="stylesheet" type="text/css" href="plugins/mein_plugin/css/mein_plugin.css">'; Für JavaScript dasselbe Prinzip: $headdata .= '<script src="plugins/mein_plugin/js/mein_plugin.js"></script>'; Um JS nach dem DOM auszuführen, verwenden Sie $footdata mit einem Heredoc. CSS muss die in core.css definierten Variablen verwenden — niemals Farben erfinden. Wenn eine Variable fehlt, schlagen Sie vor, sie zu core.css hinzuzufügen.
Wie validiere ich Benutzereingaben?+
Verwenden Sie den Sanitizer: use Beamreactor\Sanitizer\Parser; dann Parser::sanitize($input, 'type'). Verfügbare Typen: bool, date, email, name, html, xml, uuid, url, string, ip, float, int, path und andere. sanitize() bereinigt und validiert die Daten und gibt false zurück, wenn ungültig. check() prüft das Format ohne zu bereinigen. Immer VOR jeder SQL-Operation sanitizen. Niemals einen Datentyp erfinden — schlagen Sie einen vor, wenn nötig.
Wie interagiere ich mit der Datenbank?+
Verwenden Sie die SQL-Klasse: use Beamreactor\Database\SQL;. Hauptmethoden: SQL::query() für mehrere Zeilen, SQL::queryFirst() für eine einzelne Zeile, SQL::queryValue() für einen einzelnen Wert, SQL::insertRow() zum Einfügen, SQL::updateRow() zum Aktualisieren, SQL::deleteRow() zum Löschen. Verwenden Sie immer Prepared Statements mit ?-Parametern. Direkte Variablenverkettung in SQL ist strikt verboten. Prüfen Sie die Datenbankverfügbarkeit mit isset($cfg['dbtable']) und die Tabellenexistenz mit SQL::tableExists().
Wie erstelle ich einen AJAX-Endpoint?+
Module (.mod.php) sind die AJAX-Endpoints von BeamReactor. Sie antworten mit JSON, XML, HTML oder Text. Sie gehören in /handlers/plugin_name.mod.php und werden über ?obj=plugin_name.mod aufgerufen (ohne .php). Niemals den vollständigen Dateipfad aufrufen. Minimalstruktur: frameheader-Prüfung, Sicherheit über secure(), Content-Type-Header, Aktionsverarbeitung über Parser::sanitize(), JSON-Antwort mit ['success' => !!1] oder ['success' => !!0]. Auf der JavaScript-Seite erfolgt der Aufruf mit $.post(BEAM_BASE_URL + '?obj=plugin_name.mod', {...}).
Wie funktioniert das Seiten-Routing?+
Alles in BeamReactor läuft über index.php. Der Parameter ?obj= bestimmt, was geladen wird. Ein Plugin: ?obj=mein_plugin.php. Ein AJAX-Modul: ?obj=mein_plugin.mod. Ein Dokument: ?obj=meine_seite.dta. Die XDP-Engine löst den Pfad auf, lädt Konfiguration, Bibliotheken und Locale automatisch und führt das Skript in einer gesicherten Umgebung aus. Kein PHP-Skript kann direkt aufgerufen werden — alles läuft über die Engine.
Wie zeige ich dem Benutzer Benachrichtigungen an?+
BeamReactor verfügt über ein Toast-System mit 6 Stufen: debug (0), info (1), success (2), warning (3), error (4), critical (5). Schnelle Verwendung: Toast::info('Titel', 'Nachricht', 5000); oder Toast::add(Toast::LEVEL_WARNING, 'Titel', 'Nachricht', BASE_LEVEL_USER, 0). Der Parameter minUserLevel richtet Benachrichtigungen nach Zugangsstufe. Dauer in Millisekunden, 0 für dauerhaft.
Wie ist die Struktur eines BeamReactor-Plugins?+
Ein Plugin ist ein eigenständiger Ordner in /plugins/plugin_name/ mit: plugin_name.php (Hauptschnittstelle), /conf/ (automatisch geladene Konfiguration), /lib/ (automatisch geladene Bibliotheken), /locale/ (Übersetzungen pro Sprache), /handlers/ (AJAX-Endpoints .mod.php), /css/, /js/, /images/, /sql/ (Tabelleninstallation), /tests/, /doc/ (Dokumentation .md und Hilfe .help.json), und /data/cache/ für persistente Daten. Installation bedeutet den Ordner ablegen. Entfernung bedeutet ihn herausnehmen.
Wie zeige ich JavaScript-Dialoge in BeamReactor an?+
BeamReactor ersetzt die nativen alert/confirm/prompt durch benutzerdefinierte Dialoge in javascript/dialogs.js.php. Vier Funktionen: alertWindow('Titel', 'Nachricht') für Alarme, confirmWindow('Titel', 'Frage?', {}, callback) für Bestätigungen, promptWindow('Titel', 'Label:', {}, callback) für Eingaben, infoWindow('Titel', 'Info') für Informationen. Niemals native alert(), confirm() oder prompt() verwenden.
Wie übergebe ich PHP-Übersetzungen an JavaScript?+
Definieren Sie in der Plugin-Locale-Datei ein Array $js_translations und rufen Sie setJavascriptLocale($js_translations) auf. Beispiel: $js_translations = ['mein_plugin' => ['error_msg' => $dialmeinplugin[5]], 'global' => ['error' => $dial[32]]]; setJavascriptLocale($js_translations);. Auf der JavaScript-Seite greifen Sie über PLUGIN_TRANSLATION.mein_plugin.error_msg auf die Übersetzungen zu. Die Übersetzungen werden als globales JavaScript-Objekt in den Head injiziert.
Kann ich exit oder die in einem Plugin verwenden?+
Nein. Plugins dürfen niemals exit oder die verwenden. Das einzig erlaubte die im gesamten Plugin-Code ist if(!function_exists('frameheader')) die('forbidden'); in der ersten Zeile, das den BeamReactor-Kontext überprüft. Um die Ausführung zu stoppen, verwenden Sie return. Um einen Fehler zu behandeln, zeigen Sie die Nachricht im Frame an und machen dann return. Wenn ein Plugin exit oder die verwendet, kann die Engine nicht feststellen, was fehlgeschlagen ist, und die Diagnose wird unmöglich.
Wie funktionieren die Sicherheitsstufen?+
BeamReactor verwendet eine feste Hierarchie: OVERMIND > ADMIN > MODERATOR > HIGHUSER > USER. BASE_LEVEL_*-Konstanten sind in cog.inc.php definiert. Jedes Plugin kann eigene Stufen über PLUGIN_NAME_LEVEL_* in seiner Konfiguration definieren. $basedisplevel verwendet immer BASE_LEVEL_*, niemals PLUGIN_LEVEL_*. Benutzerdefinierte define()-Aufrufe kommen nach $basedisplevel. Das System vervollständigt fehlende Stufen automatisch über base_user_levels().
Wie funktioniert das automatische Laden von Klassen?+
Dateien mit .lib.inc.php und .conf.inc.php werden automatisch von der Engine geladen. Für zusätzliche Klassen registrieren Sie einen PSR-4-Autoloader in der Plugin-Konfiguration mit spl_autoload_register(). Der Namespace folgt der Konvention Beamreactor\PluginName\. Klassendateien gehören in /lib/ und werden über den relativen Pfad zum Namespace aufgelöst. Dies ermöglicht es mehreren Plugins, ohne Namenskollisionen nebeneinander zu bestehen.