BeamReactor – Plugin Development Documentation #

> Version: 1.1 — locales migrated to JSON (.json + .js.json); legacy .inc.php kept as fallback

> Audience: Plugin developers for the BeamReactor CMS

> Scope: Architecture, conventions, security rules, APIs, SQL, JS, i18n

BeamReactor is a centralized CMS developed and maintained for more than 22 years.

Fundamental rules:

• No PHP script can ever be called directly. Everything goes through the XDP engine (index.php).
• Plugins are isolated, non-colliding, and auto-loaded.
• Predictability, security, and performance outweigh convenience.

Coding Conventions (Mandatory) #

• Allman indentation style
• Boolean logic uses !!0 and !!1
• Strict typing for functions and methods whenever possible
• Prefer single quotes
• Avoid constant PHP context switching (performance cost)
• Always close PHP tags (?>) unless outputting raw text/HTML/JSON/JS
• Plugins must never use exit() or die()

- Only return / control flow

Plugins are:

• Managed by the BeamReactor package manager
• Loaded automatically by the engine
• Designed so multiple plugins may coexist on the same page without conflict

Naming discipline is therefore critical.

When a plugin is called via:

index.php?obj=oneliner.php

The engine automatically loads:

• Configuration
• Library
• Locale

/plugins/oneliner/conf/oneliner.conf.inc.php
/plugins/oneliner/oneliner.lib.inc.php
getlocale('oneliner')
?>

⚠️ Manual includes are forbidden for configs and libs.

The only allowed include:

include_once(getlocale('nom_du_plugin'));
?>

Every plugin must begin with the BeamReactor guard (the only exit allowed):

// Ceci vérifie que nous sommes bien en contexte BeamReactor.
// C'est le SEUL exit autorisé dans le code d'un plugin.
if(!function_exists('frameheader')) die('forbidden');

Then, standard pattern:

if($obj=='plugin.php') frameheader($dialplugindisplay);

Notes:

• Locale must be loaded before frameheader() to avoid missing variable errors
• frameheader('title', $headingLevel='h3', $noheader=false) structures the UI

- H1 = page title (one per page)

- H2 = main sections

- H3+ = frames/widgets

• framefooter() closes a frame; not needed at page bottom (auto-close)
• Do not use ob_flush(); flush(); without a preceding ob_start()

if(!function_exists('frameheader')) return;

$basedatadisplay = 'yes';
$basedisplevel   = MYPLUGIN_LEVEL_HIGHUSER;
$ftype		   = 1;
$is_public	   = 0;
?>

Security Levels #

• Levels are constants only
• Never hardcode numeric values

Standard suffixes:

• _LEVEL_USER
• _LEVEL_HIGHUSER
• _LEVEL_MODERATOR
• _LEVEL_ADMIN
• _LEVEL_OVERMIND

Locales are now JSON (migrated from the legacy .inc.php format). The mandatory trio is fr / en / de.

Location:

/plugins/myplugin/locale/myplugin.fr.json      ← server-side strings (+ .en / .de)
/plugins/myplugin/locale/myplugin.fr.js.json   ← front-end strings (+ .en / .de)

Server-side file (myplugin.fr.json):

{
    "_plugindisplay": "Fabrique de spaghetti",
    "_plugincall": "Spaghettisation",
    "1": "Suivez le spaghetti"
}

getlocale('myplugin') — loaded before frameheader(), the only allowed include:

• Loads myplugin.<lang>.json, falling back to myplugin.fr.json.
• Materializes reserved meta keys (_plugincall, _plugindisplay, _plugindescription, …) into globals $dialplugincall, $dialplugindisplay, …
• Materializes every other key into the $dialmyplugin[...] array.
• If present, myplugin.<lang>.js.json is auto-injected into the front-end under window.PLUGIN_TRANSLATION.myplugin — no manual wiring needed.

Legacy .inc.php locales still load as a fallback, but new plugins ship JSON.

$cfg[0]   // Base URL
$cfg[1]   // Site name
$cfg[3]   // Skins path
$cfg[4]   // Data path
$cfg[17]  // Max upload size
$cfg['obj']
$cfg['request_method']
?>

Use BEAM_BASE_URL in JavaScript instead of $cfg[0].

• Plugins rely on core.css
• Never invent colors
• If a style is missing → propose adding it to core.css

• Endpoints only (JSON / XML / text)
• No UI
• Called as:

?obj=myplugin.mod

❌ Forbidden:

?obj=plugins/myplugin/handlers/myplugin.mod.php

Levels:

DEBUG, INFO, SUCCESS, WARNING, ERROR, CRITICAL

Example:

$toastId = Toast::add(
	Toast::LEVEL_WARNING,
	'Sécurisez votre compte',
	'Activez la 2FA',
	BASE_LEVEL_USER
);
?>

Broadcast toasts are persistent and reserved for emergencies.

Replaces:

• filter_var
• intval
• cleanhtml

Allowed datatypes:

Bool, Date, Email, Name, HTML, XML, UUID, URL, String, IP, Float, Arithmetic, Path, PHPsession, ...

Usage:

use Beamreactor\Sanitizer\Parser;
$email = Parser::sanitize($_POST['email'], 'email');
$page  = Parser::sanitize($_GET['page'], 'int') ?: 1;
?>

Rules:

• Always sanitize before SQL
• Never concatenate
• Always check results

use Beamreactor\Database\SQL;
$users = SQL::query(
	"SELECT * FROM users WHERE level >= ?",
	[$level]
);
?>

If SQL fails → empty array, no exception.

Global:

BEAM_BASE_URL

Dialogs:

alertWindow('Title', 'Message');
confirmWindow('Title', 'Question', {}, callback);

Inject JS via PHP:

$headdata .= "<script>...</script>";
$footdata .= "doSomething();";
?>

Preferred path: ship a myplugin.<lang>.js.json file (see §7) — getlocale() auto-injects it under window.PLUGIN_TRANSLATION.myplugin. No PHP wiring required.

setJavascriptLocale() remains available for strings assembled dynamically at runtime:

$js_translations = [
	'plugin' => [
		'reply' => $dialemail[16]
	]
];
setJavascriptLocale($js_translations);
?>

• ❌ No require, include, require_once for plugin internals
• ❌ No exit/die except BeamReactor guard at top
• ❌ No direct file calls
• ✅ Locale before header
• ✅ Sanitizer before SQL
• ✅ One archive = one plugin

BeamReactor is not permissive by accident. It is strict by design.