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.

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). A new requestkey is generated on every download (key rotation via md5(username + uniqid())).

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

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.