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.

Composer — wgclient & wghandler als Pakete

Beide Client-Dateien lassen sich alternativ über ein privates Composer-Repository installieren. Die Authentifizierung erfolgt mit Ihrem Station-Login (HTTP Basic — Composer fragt beim ersten Zugriff danach und speichert die Zugangsdaten in der auth.json).

composer config repositories.widget-storm composer https://widget-storm.de/composer
composer require widget-storm/wgclient:^4.1
vendor/bin/wg-deploy public/

Schlüssel-Semantik: Wiederholte Installationen und composer update liefern denselben Schlüssel erneut aus — Ihr installierter wgclient bleibt gültig. Nur die allererste Composer-Installation eines Kontos erzeugt einmalig einen neuen Schlüssel (ein zuvor über die Station geladener wgclient wird dabei ungültig). Eine bewusste Rotation ist jederzeit möglich (wgclientcreator.php?rotate=1); danach composer clear-cache && composer reinstall widget-storm/wgclient ausführen und neu deployen — ohne clear-cache würde Composers lokaler Paket-Cache den alten Client wiederherstellen.

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). Ihr requestkey bleibt bei wiederholtem Download erhalten; ein neuer wird nur beim allerersten Download erzeugt — oder auf Wunsch per ?rotate=1 (Key-Rotation, der alte Schlüssel wird ungültig).

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');
?>

Support-Chat wg_chat nach dem Kauf einrichten

Der Chat läuft auf Ihrem eigenen Webserver: PHP ab Version 7.0 mit den Erweiterungen openssl und curl. Nach dem Kauf steht dieselbe Anleitung mit Ihrer Domain in der Station unter „Ihre gekauften Widgets“.

1. Laden Sie in der Station wgclient.php und wghandler.php und legen Sie beide in das Hauptverzeichnis Ihrer Website. Danach muss https://ihre-seite.de/wgclient.php erreichbar sein, denn der Chat ruft genau diese Adresse auf. Erneutes Laden behält Ihren Schlüssel.
2. Bauen Sie den Chat in eine PHP-Seite im selben Verzeichnis ein, zum Beispiel kontakt.php (Code unten). Die erste Zeile steht ganz am Anfang der Datei, vor jeder anderen Ausgabe.
3. Öffnen Sie die Seite einmal mit ?wg_chat_key= und einem selbst gewählten Betreiber-Schlüssel von mindestens 12 Zeichen am Ende der Adresse. Danach sehen Sie die Betreiber-Ansicht. Richten Sie den Chat ein, bevor Sie die Seite verlinken: Bis dahin sehen Besucher einen Einrichtungshinweis, und der erste Schlüssel gilt.
4. Zum Antworten öffnen Sie dieselbe Adresse mit Ihrem Schlüssel. Die Betreiber-Ansicht bleibt bis 12 Stunden nach der letzten Nutzung angemeldet. Besucher öffnen die Seite ohne Schlüssel.

<?php require_once __DIR__ . '/wgclient.php'; ?>
<!DOCTYPE html>
<html lang="de">
<head>
  <meta charset="utf-8">
  <link rel="stylesheet" href="/wgclient.php?wgname=wg_chat&amp;wgauthor=WidgetStormSystem&amp;wgmode=css">
</head>
<body>
  <?php $wg->get('wg_chat', 'WidgetStormSystem', ['uid' => 'support'], 'php'); ?>
  <script src="/wgclient.php?wgname=wg_chat&amp;wgauthor=WidgetStormSystem&amp;wgmode=js"></script>
</body>
</html>

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.