Technical Reference

1. System Overview

Widget Storm is a modular widget platform for the web, active since 2008. Widgets are self-contained web components made of three layers (PHP, CSS, JavaScript), stored encrypted on the server and delivered over HTTP endpoints.

2. Widget Structure

Every widget consists of exactly three files. All three layers have access to the same parameters ($wgparams) and the instance ID ($wgguid).

Variables available in the widget code

PHP layer — example

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

Output modes

3. Parameter System

Parameters are passed to widgets via wgparams. The system supports three formats:

JSON (recommended)

{"text":"Hello World","color":"#ff0000","items":[1,2,3]}

Parsed into a stdClass object. Access via $wgparams->text.

Semicolon-separated

Value1;Value2;Value3

Parsed into an array. Access via $wgparams[0], $wgparams[1], etc.

Simple string

Any arbitrary text

Passed through unchanged as a string.

URL encoding for HTTP requests

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

// In PHP, for URL parameters:
$packurl = http_build_query(['wgparams' => $paramsArray]);

4. PHP-in-CSS/JS Bridge

CSS and JS files can contain embedded PHP code. Because PHP tags are syntactically invalid in CSS/JS, they are wrapped in comments. The system converts them automatically before execution.

Conversion rules

CSS example

/*<?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 example

/*<?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. Nesting & Markers

Widgets can load other widgets. This is done via markers in the PHP code, which the server resolves recursively.

Marker syntax

##wgstart##widgetname::author::parameter##wgend##

Resolution process

1. The server finds all ##wgstart##...##wgend## markers in the PHP code
2. Extracts the name, author, and parameters from the marker
3. Resolves the nested widget recursively
4. The nested widget's CSS and JS are appended to the parent widget
5. PHP is Base64-encoded and executed via intern_script_wall()

UID Scoping & Placeholders

6. Availability Levels

Developers set the availability at upload time (parameter wgrmode). The level determines who can retrieve the widget through their wgclient — and whether billing is required.

Access control

1. Widget.availability == 'open'       → Access granted
2. Widget.author == RequestUser        → Access granted (author)
3. Permission check                    → Checked against the internal permission table
   - Global permission                 → Applies to all users
   - Specific permission               → Applies to individual users

Widget-level security

Widgets can bring their own security mechanisms — independent of the host system. The wg_demo_todo widget demonstrates this principle: AES-256-encrypted persistence, key-based authentication with brute-force protection, and automatic preflight checks for dependencies and permissions. You can find more details on the widget overview.

7. HTTP Endpoints

wgclient.php — widget delivery (local)

Serves both as an HTTP endpoint and as a PHP include for server-side integration.

Composer — wgclient & wghandler as packages

Both client files can alternatively be installed from a private Composer repository. Authentication uses your Station login (HTTP Basic — Composer prompts for it on first access and stores the credentials in 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/

Key semantics: repeat installs and composer update re-issue the same key — your installed wgclient stays valid. Only an account's very first Composer install issues a new key once (a wgclient previously downloaded through the Station becomes invalid at that point). A deliberate rotation is possible at any time (wgclientcreator.php?rotate=1); afterwards run composer clear-cache && composer reinstall widget-storm/wgclient and redeploy — without clear-cache, Composer's local package cache would resurrect the old client.

wgcall.php — remote widget delivery

Endpoint for external servers. Requires authentication and encrypts the response.

wgregistration.php — widget upload

Endpoint for uploading new or updated widgets.

wgclientcreator.php — client download

Generates a personalized wgclient.php with embedded credentials. Requires an active session (login via the Station). Your requestkey survives repeat downloads; a new one is issued only on the very first download — or on request via ?rotate=1 (key rotation; the old key becomes invalid).

wghandlercreator.php — handler download

Generates a portable wghandler.php class with an embedded RIJNDAEL-256 implementation (pure PHP via phpseclib3, compatible with PHP 8+), local widget caching, and support for nested widgets.

8. Widget Integration

Local integration (same server)

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

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

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

Remote integration (external server)

<?php
// Place wgclient.php and wghandler.php on your own server
require_once 'wgclient.php';

// The credentials are embedded in wgclient.php
$wg->get('basic', 'WidgetStormSystem', $params, 'php');
?>

Setting up the support chat wg_chat after the purchase

The chat runs on your own web server: PHP 7.0 or later with the openssl and curl extensions. After the purchase the same instructions, with your domain, are in the Station under “Your purchased widgets”.

1. Download wgclient.php and wghandler.php in the Station and put both into the main folder of your website. Afterwards https://your-site.com/wgclient.php must be reachable, because the chat calls exactly that address. Downloading again keeps your key.
2. Put the chat into a PHP page in the same folder, for example contact.php (code below). The first line goes at the very top of the file, before any other output.
3. Open the page once with ?wg_chat_key= and an operator key of your choosing, at least 12 characters, at the end of the address. You then see the operator view. Set the chat up before you link the page: until then visitors see a setup notice, and the first key counts.
4. To answer, open the same address with your key. The operator view stays logged in until 12 hours after it was last used. Visitors open the page without the key.

<?php require_once __DIR__ . '/wgclient.php'; ?>
<!DOCTYPE html>
<html lang="en">
<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', 'wglang' => 'en'], 'php'); ?>
  <script src="/wgclient.php?wgname=wg_chat&amp;wgauthor=WidgetStormSystem&amp;wgmode=js"></script>
</body>
</html>

Execution modes (wgexecutionmode)

The developer uses wgexecutionmode to control whether a widget is rendered locally from the CodeVault or fetched live from the Widget Storm server. The default mode uses the local cache — which means no network latency and maximum loading speed.

9. Encryption

Communication between client and server is encrypted. The system supports two encryption versions per user: RIJNDAEL-256 (the original method, in use since 2008) and AES-256-CBC (the modern standard for new users). Both coexist through a central EncryptionNegotiator that automatically selects the appropriate version per user.

Both directions (server → client and client → server) are encrypted at the application level. Each user has an individual key, which is rotated on every client download.

10. Rate Limiting

Tracking is done per IP address and endpoint. State files in /tmp/ws-ratelimit/.

11. CodeVault

The CodeVault is the heart of widget delivery. It stores widget code as local files on the client server — which means direct file-system access instead of network round-trips. Widgets load as fast as any other local PHP file, without any dependency on the central Widget Storm server.

Purpose & benefits

Directory structure

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

The directory structure is organized by author. During batch upload (uploadwidgets mode), the wghandler scans the wgbuilds/ directory and automatically uploads changed files to the server — processing only your own widgets. Widgets from other authors remain untouched.

Rendering from the CodeVault

In the default mode, the wgclient reads the widget code directly from wgbuilds/ and executes it locally (evalThe CodeVault code is executed via eval() in the server context. The files come from the authenticated download or your own upload — they are identical to the database original. No external input flows into the execution.). The live mode bypasses the CodeVault and queries the Widget Storm server directly — useful during development, but slower than the local cache.