Technische Referenz

1. Systemübersicht

Widget Storm ist eine modulare Widget-Plattform für das Web, aktiv seit 2008. Widgets sind eigenständige Webkomponenten aus drei Schichten (PHP, CSS, JavaScript), die verschlüsselt auf dem Server gespeichert und über HTTP-Endpunkte ausgeliefert werden.

2. Widget-Struktur

Jedes Widget besteht aus exakt drei Dateien. Alle drei Schichten haben Zugriff auf die gleichen Parameter ($wgparams) und die Instanz-ID ($wgguid).

Verfügbare Variablen im Widget-Code

PHP-Schicht — Beispiel

<?php
if(isset($widgetparams->uid)) $wgguid = $widgetparams->uid;
else $wgguid = "";
if(isset($wgparams)){
    $text = isset($wgparams->text) ? $wgparams->text : "Standard-Text";
    ?>
    <div id="mein_widget<?= $wgguid;?>" class="mein-widget">
        <p><?= $text;?></p>
    </div>
    <?php
}
?>

Ausgabemodi

3. Parameter-System

Parameter werden über wgparams an Widgets übergeben. Das System unterstützt drei Formate:

JSON (empfohlen)

{"text":"Hallo Welt","color":"#ff0000","items":[1,2,3]}

Wird zu einem stdClass-Objekt geparst. Zugriff via $wgparams->text.

Semikolon-getrennt

Wert1;Wert2;Wert3

Wird zu einem Array geparst. Zugriff via $wgparams[0], $wgparams[1], etc.

Einfacher String

Ein beliebiger Text

Wird unverändert als String durchgereicht.

URL-Encoding für HTTP-Requests

wgparams={"text":"Hallo","uid":"abc123"}

// In PHP für URL-Parameter:
$packurl = http_build_query(['wgparams' => $paramsArray]);

4. PHP-in-CSS/JS Bridge

CSS- und JS-Dateien können eingebetteten PHP-Code enthalten. Da PHP-Tags in CSS/JS syntaktisch ungültig sind, werden sie in Kommentare verpackt. Das System konvertiert diese automatisch vor der Ausführung.

Konvertierungsregeln

CSS-Beispiel

/*<?php
if(isset($wgparams->uid)) $wgguid = $wgparams->uid;
else $wgguid = "";
?>*/
div#mein_widget/*<?= $wgguid;?>*/ {
    background: rgba(170,210,210,0.08);
    border: 1px solid rgba(170,210,210,0.2);
    padding: 1em;
    border-radius: 0.4em;
}

JS-Beispiel

/*<?php
if(isset($wgparams->uid)) $wgguid = $wgparams->uid;
else $wgguid = "";
?>*/
jQuery(document).ready(function(){
    jQuery("#mein_widget/*<?= $wgguid;?>*/").on("click", function(){
        jQuery(this).toggleClass("active");
    });
});

5. Verschachtelung & Marker

Widgets können andere Widgets laden. Dies geschieht über Marker im PHP-Code, die vom Server rekursiv aufgelöst werden.

Marker-Syntax

##wgstart##widgetname::autor::parameter##wgend##

Auflösungsprozess

1. Server findet alle ##wgstart##...##wgend## Marker im PHP-Code
2. Extrahiert Name, Autor und Parameter aus dem Marker
3. Löst das verschachtelte Widget rekursiv auf
4. CSS und JS des verschachtelten Widgets werden an das Eltern-Widget angehängt
5. PHP wird Base64-kodiert und über intern_script_wall() ausgeführt

UID-Scoping & Platzhalter

6. Verfügbarkeitsstufen

Entwickler legen die Verfügbarkeit beim Upload fest (Parameter wgrmode). Die Stufe bestimmt, wer das Widget über seinen wgclient abrufen kann — und ob eine Abrechnung erforderlich ist.

Zugriffskontrolle

1. Widget.availability == 'open'       → Zugriff gewährt
2. Widget.author == RequestUser        → Zugriff gewährt (Autor)
3. Berechtigungsprüfung              → Prüfung in interner Berechtigungstabelle
   - Globale Berechtigung              → Gilt für alle Nutzer
   - Spezifische Berechtigung          → Gilt für einzelne Nutzer

Sicherheit auf Widget-Ebene

Widgets können eigene Sicherheitsmechanismen mitbringen — unabhängig vom Hostsystem. Das Widget wg_demo_todo demonstriert dieses Prinzip: AES-256-verschlüsselte Persistenz, schlüsselbasierte Authentifizierung mit Brute-Force-Schutz und automatische Preflight-Checks für Abhängigkeiten und Berechtigungen. Weitere Details finden Sie auf der Widget-Übersicht.

7. HTTP-Endpunkte

wgclient.php — Widget-Auslieferung (lokal)

Dient als HTTP-Endpunkt und als PHP-Include für serverseitige Einbindung.

wgcall.php — Remote Widget-Auslieferung

Endpunkt für externe Server. Erfordert Authentifizierung und verschlüsselt die Antwort.

wgregistration.php — Widget-Upload

Endpunkt zum Hochladen neuer oder aktualisierter Widgets.

wgclientcreator.php — Client-Download

Generiert eine personalisierte wgclient.php mit eingebetteten Zugangsdaten. Erfordert aktive Session (Login über Station). Bei jedem Download wird ein neuer requestkey generiert (Key-Rotation via md5(username + uniqid())).

wghandlercreator.php — Handler-Download

Generiert eine portable wghandler.php Klasse mit eingebetteter RIJNDAEL-256 Implementierung (pure PHP via phpseclib3, kompatibel mit PHP 8+), lokalem Widget-Caching und Unterstützung für verschachtelte Widgets.

8. Widget-Einbindung

Lokale Einbindung (gleicher Server)

<!-- CSS im <head> -->
<link rel="stylesheet"
    href="wgclient.php?wgname=basic&wgauthor=WidgetStormSystem&wgmode=css&wgparams=..."
    type="text/css">

<!-- JavaScript vor </body> -->
<script src="wgclient.php?wgname=basic&wgauthor=WidgetStormSystem&wgmode=js&wgparams=..."></script>

<!-- PHP im <body> -->
<?php
require_once 'wgclient.php';
$wg->get('basic', 'WidgetStormSystem', $params, 'php');
?>

Remote-Einbindung (externer Server)

<?php
// wgclient.php und wghandler.php auf eigenem Server platzieren
require_once 'wgclient.php';

// Zugangsdaten sind in wgclient.php eingebettet
$wg->get('basic', 'WidgetStormSystem', $params, 'php');
?>

Ausführungsmodi (wgexecutionmode)

Der Entwickler steuert über den wgexecutionmode, ob ein Widget lokal aus dem CodeVault gerendert wird oder live vom Widget-Storm-Server abgerufen werden soll. Der Standard-Modus nutzt den lokalen Cache — das bedeutet keine Netzwerk-Latenz und maximale Ladegeschwindigkeit.

9. Verschlüsselung

Die Kommunikation zwischen Client und Server ist verschlüsselt. Das System unterstützt zwei Verschlüsselungsversionen pro Benutzer: RIJNDAEL-256 (das ursprüngliche Verfahren seit 2008) und AES-256-CBC (der moderne Standard für neue Nutzer). Beide koexistieren über einen zentralen EncryptionNegotiator, der automatisch die passende Version pro Benutzer wählt.

Beide Richtungen (Server → Client und Client → Server) sind auf Anwendungsebene verschlüsselt. Jeder Nutzer hat einen individuellen Schlüssel, der bei jedem Client-Download rotiert wird.

10. Rate Limiting

Tracking erfolgt pro IP-Adresse und Endpunkt. Zustandsdateien in /tmp/ws-ratelimit/.

11. CodeVault

Der CodeVault ist das Herzstück der Widget-Auslieferung. Er speichert Widget-Code als lokale Dateien auf dem Client-Server — das bedeutet direkten Dateisystem-Zugriff statt Netzwerk-Roundtrips. Widgets werden so schnell geladen wie jede andere lokale PHP-Datei, ohne Abhängigkeit vom zentralen Widget-Storm-Server.

Zweck & Vorteile

Verzeichnisstruktur

wgbuilds/
  ├─ {Autor}/
  │   ├─ {widget_name}.php
  │   ├─ {widget_name}.css
  │   └─ {widget_name}.js
  └─ WidgetStormSystem/
      ├─ basic.php
      ├─ basic.css
      ├─ basic.js
      ├─ wg_nav.php
      └─ ...

Die Verzeichnisstruktur ist nach Autoren organisiert. Beim Batch-Upload (uploadwidgets-Modus) scannt der wghandler das wgbuilds/ Verzeichnis und lädt geänderte Dateien automatisch auf den Server hoch — dabei werden nur eigene Widgets verarbeitet. Widgets anderer Autoren bleiben unberührt.

Rendering aus dem CodeVault

Im Standard-Modus liest der wgclient den Widget-Code direkt aus wgbuilds/ und führt ihn lokal aus (evalDer CodeVault-Code wird via eval() im Server-Kontext ausgeführt. Die Dateien stammen aus dem authentifizierten Download oder eigenem Upload — sie sind identisch mit dem Datenbank-Original. Kein externer Input fließt in die Ausführung ein.). Der Live-Modus umgeht den CodeVault und fragt den Widget-Storm-Server direkt ab — nützlich während der Entwicklung, aber langsamer als der lokale Cache.