Official PXL repository documentation — copy any code block or the full Markdown file below.
PXL Programming Language (Peter eXtended Programming Language)
Founder & Creator: Peter Joram Country: Tanzania Official Slogan: Beyond Code. Beyond Limits. Contact: peterjoram897@gmail.com | +255677780801
Overview
PXL (Peter eXtended Programming Language) is a statically typed, sandbox-capable, multi-paradigm programming language engineered with a complete compiler and runtime pipeline:
- Compiler Pipeline: Hand-written Lexer (
src/pxl/core/lexer.ts), Recursive-Descent + Pratt Parser (src/pxl/core/parser.ts), typed AST (src/pxl/core/ast.ts), Semantic Analyzer & Static Type Checker (src/pxl/core/semantic.ts), Intermediate Representation (src/pxl/core/ir.ts) with disassembler, and AST/IR execution engine (src/pxl/core/vm.ts). - Managed Memory: Scoped lexical lifetimes + reference tracking + garbage collection sweep + hard heap quotas (
src/pxl/core/memory.ts). - Security Sandbox: Zero
eval/new Functionin the core VM, default-deny host permissions (--allow-fs,--allow-fs-write,--allow-net,--allow-env,--allow-process), path traversal containment, infinite-loopmaxStepsprotection, call-depth cap, and Nodenode:cryptocryptographic primitives (SHA-256,SHA-512,HMAC-SHA256,AES-256-GCM,randomUUID). - Developer Tooling: Full CLI (
bin/pxl.js), Package Manager with SHA-256 lockfile verification (src/pxl/pkg/manager.ts), Code Formatter (pxl fmt), Linter (pxl lint), Debugger (pxl run --debug), REPL (pxl repl), Language Server (pxl lsp), VS Code TextMate grammar (editors/vscode/), and Next.js Web Docs + Interactive Playground (/playground).
Quick Start
# 1. Install dependencies & compile the PXL engine npm install npm run build:pxl # 2. Check PXL CLI version & help node bin/pxl.js --version node bin/pxl.js --help # 3. Type-check & run an example program node bin/pxl.js check examples/hello.pxl node bin/pxl.js run examples/hello.pxl node bin/pxl.js run examples/oop_structs_enums.pxl # 4. Run full automated test suite (Node unit/security tests + native .test.pxl suite) npm test # 5. Start the web documentation & interactive Playground (port 3000) npm run dev
Example PXL Program
const CREATOR: string = "Peter Joram";
enum Role { Guest = 0, Developer = 1, Founder = 2 }
interface Describable {
fn describe() -> string;
}
class Engineer implements Describable {
flux name: string = "";
flux role: Role = Role.Developer;
fn init(name: string, role: Role) {
this.name = name;
this.role = role;
}
fn describe() -> string {
return "${this.name} (${this.role}) — Beyond Code. Beyond Limits.";
}
}
flux peter = new Engineer(CREATOR, Role.Founder);
println(peter.describe());Documentation Index
| Document | Description |
|---|---|
| Linux, macOS, and Windows setup and verification instructions | |
| Step-by-step tutorial from Hello World to packages | |
| Lexical grammar, types, scoping, OOP, and async semantics | |
| Concise cheat sheet of every PXL keyword and construct | |
Built-in modules: core, math, json, csv, time, str, arr, url, fs, http, sys, crypto | |
| Complete CLI subcommands and permission flags | |
| Lexer -> Parser -> Semantic/Type -> IR pipeline details | |
| VM interpreter, scopes, closures, and memory management model | |
| Threat model, sandbox guarantees, cryptography policy, and honest limitations | |
| Contribution workflow, testing, and coding standards | |
| Release history | |
| Engineering roadmap | |
| Frequently asked questions | |
| MIT License |
Web Development & UI Component Library (/docs/*.md)
| Guide | Topics Covered |
|---|---|
| AI-friendly PXL syntax, compiler pipeline, and safe component patterns | |
| Prompt engineering templates for generating valid PXL sites | |
web.page, web.layout, web.app dynamic routing, sessions, HTML export | |
| Full-page sections, cards, tables, modals, tabs, charts, and widgets | |
| All 23 accessible button variants (WhatsApp, Call, Copy, Share, Payment, Download) | |
| All 13 responsive header variants with mobile drawers & dropdowns | |
| All 9 footer variants with multi-column links, newsletter & dynamic year | |
| All 12 ARIA menu & sidebar navigation variants | |
| All 14 loaders, skeletons, upload/download progress bars | |
All 15 form types + server-side forms.validate, CSRF & anti-spam checks | |
Motion transitions and prefers-reduced-motion support | |
| 12 curated design themes, dark/light toggling, CSS custom properties | |
Mobile-first breakpoints, .pxl-grid, viewport overflow guard | |
| XSS escaping, URL allowlisting, CSP headers, upload validation | |
Complete runnable demos & all 8 starter templates (pxl templates) | |
Exact API signatures for ui, web, theme/design, forms, security | |
| Master component index across all 30+ sections & helpers |
Using PXL Inside Websites (<?pxl ... ?> + .pxl + HTML)
PXL is a complete, drop-in, higher-security alternative to PHP for building full-stack websites. You can run PXL directly on a server, embed .pxl files inside .html, or protect logic using PXL Vault V2 (pxl_vault).
1. Mixed <?pxl ... ?> + HTML (PHP Replacement)
Write server logic at the top with <?pxl ... ?>, mix <?pxl= $expr ?> (auto XSS-escaped via htmlspecialchars), loops, and conditionals directly with clean HTML/CSS below:
<?pxl
session_start();
$site_name = "Duka la Teknolojia PXL";
$csrf = csrf_token();
mysql.connect();
mysql.schema("products", [
{ id: 1, title: "PXL Pro Cloud", price: 95000, status: "Tayari" },
{ id: 2, title: "Vault V2 Shield", price: 150000, status: "Maarufu" }
]);
$stmt = mysql.prepare("SELECT id, title, price, status FROM products WHERE id >= ?");
$stmt.execute([1]);
$products = $stmt.fetchAll();
?>
<!doctype html>
<html lang="sw">
<body style="background:#05050a;color:#f8fafc;font-family:system-ui,sans-serif;padding:24px">
<h1><?pxl= $site_name ?></h1>
<p>Tarehe: <?pxl= date("Y-m-d") ?></p>
<?pxl for ($p in $products) { ?>
<div style="border:1px solid #312e81;padding:14px;margin-top:10px;border-radius:12px">
<strong><?pxl= $p.title ?></strong> — TZS <?pxl= $p.price ?> (<?pxl= $p.status ?>)
</div>
<?pxl } ?>
</body>
</html>Supported PHP-compatible globals & helpers built into <?pxl ... ?>:
- Superglobals:
$_GET,$_POST,$_REQUEST,$_SERVER,$_SESSION,$_COOKIE,$_FILES,$_ENV(auto$varassignment supported alongsideflux). - Sessions, Cookies & Headers:
session_start(),session_set(),session_get(),session_has(),session_destroy(),setcookie(),header(),http_response_code(),redirect(). - Security:
csrf_token(),csrf_verify(),password_hash()(node:cryptoscryptSync),password_verify()(timingSafeEqual),htmlspecialchars(),urlencode(),urldecode(). - Utilities:
isset(),empty(),count(),explode(),implode(),trim(),strtolower(),strtoupper(),str_replace(),substr(),strpos(),json_encode(),json_decode(),date(),time_unix().
2. Running index.pxl Directly Inside .html (via CDN Script or Local Runtime)
Any .html page can load and execute .pxl files (index.pxl) or inline <script type="text/pxl"> scripts cleanly—without exposing raw source code—using either official runtime link (ptaditech.xyz or pxl-programming-language-wrii.vercel.app):
<!doctype html>
<html lang="sw">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>PXL Web App — Copyright (c) Peter Joram</title>
</head>
<body>
<pxl-app src="index.pxl"></pxl-app>
<!-- Official Script Links (both indexed in sitemap.xml): -->
<script src="https://ptaditech.xyz/pxl-runtime.js"></script>
<!-- Or: <script src="https://pxl-programming-language-wrii.vercel.app/pxl-runtime.js"></script> -->
</body>
</html>Stealth MySQL Database & Complete .env Setup Guide
PXL communicates with MySQL through a Stealth Bridge designed so external users and attackers cannot see table names, SQL statements, hostnames, or even confirm a SQL database is in use:
- All credentials live strictly server-side in
.env(never in HTML,.pxlfrontend bundles, or client JS). - Queries enforce Prepared Statements (
mysql.prepare("SELECT ... WHERE id = ?")/pdo.prepare(...)) preventing SQL Injection 100%. - All SQL or driver errors are masked behind opaque reference IDs (
Ref: PXL-DB-xxxxxx). - Browser-to-server execution goes through the opaque Vault-V2-sealed endpoint
/api/pxl/x(withX-Content-Type-Options: nosniff,Cache-Control: no-store, strict CSP, andX-Powered-Byremoved). - Use
mysql.stealthBind(action, sql)+mysql.stealthCall(token, params)to hide every query behind a PXL Vault V2 token.
Complete .env Variables Reference
Create a .env file in your project root (or set these in your hosting dashboard's Environment Variables):
| Variable | Required? | Default | Accepted Values & Explanation |
|---|---|---|---|
MYSQL_HOST | Yes (unless DATABASE_URL) | 127.0.0.1 | Hostname or IP of your MySQL server (e.g., 127.0.0.1, localhost, mysql.railway.internal, aws.connect.psdb.cloud). |
MYSQL_PORT | No | 3306 | TCP port of MySQL server (usually 3306, or cloud-assigned port like 25060 / 4000). |
MYSQL_USER | Yes (unless DATABASE_URL) | root | Database username (e.g., root locally, or dedicated least-privilege user pxl_app_user in production). |
MYSQL_PASSWORD | Production: Yes | (empty) | Database password. Leave empty only if local XAMPP/Laragon root has no password. |
MYSQL_DATABASE | Yes (unless DATABASE_URL) | pxl_app | Target MySQL schema/database name (must already exist on the MySQL server). |
MYSQL_SSL | Recommended | false | TLS/SSL encryption mode for MySQL connections. See exact values below! |
MYSQL_SSL_CA | Optional | (empty) | Optional PEM root certificate string (use \n for line breaks) when using MYSQL_SSL=strict with custom CAs (Aiven / DigitalOcean / Cloud SQL). |
DATABASE_URL | Optional override | (empty) | Single-line MySQL URI: mysql://USER:PASS@HOST:PORT/DATABASE. When set, overrides MYSQL_HOST/PORT/USER/PASSWORD/DATABASE. |
PXL_DB_STEALTH_KEY | Recommended | peter-joram | Server-only secret shield key used to seal/unseal Vault V2 stealth tokens and /api/pxl/x RPC payloads. Change to a long random string in production. |
What to Fill in MYSQL_SSL (Every Environment)
| Setting | Accepted Values | When to Use | How PXL Configures mysql2 |
|---|---|---|---|
| `MYSQL_SSL=false` | false, 0, off, no, disable | Localhost / Development — XAMPP, WAMP, Laragon, MAMP, local MySQL (127.0.0.1), Docker containers without TLS. | Disables SSL (ssl: undefined). |
| `MYSQL_SSL=true` | true, 1, on, yes, require, required | Managed Cloud MySQL — Railway, Aiven, DigitalOcean, Render, Hostinger, cPanel remote MySQL where TLS encryption is required without verifying custom CA bundles. | Enables encrypted TLS (ssl: { rejectUnauthorized: false }, or attaches ca if MYSQL_SSL_CA is set). |
| `MYSQL_SSL=strict` | strict, verify, verify-ca, verify-full | Enterprise / Strict Cloud TLS — PlanetScale, TiDB Cloud Serverless, AWS RDS, Google Cloud SQL, Azure Database for MySQL. | Enforces full TLS certificate chain verification (ssl: { rejectUnauthorized: true }, plus optional MYSQL_SSL_CA). |
Ready-to-Use .env Templates by Environment
A. Localhost (XAMPP / WAMP / Laragon / Local MySQL)
MYSQL_HOST=127.0.0.1 MYSQL_PORT=3306 MYSQL_USER=root MYSQL_PASSWORD= MYSQL_DATABASE=pxl_app MYSQL_SSL=false PXL_DB_STEALTH_KEY=peter-joram
B. Docker Compose / Internal Network
MYSQL_HOST=mysql-service MYSQL_PORT=3306 MYSQL_USER=pxl_worker MYSQL_PASSWORD=strong_internal_password MYSQL_DATABASE=pxl_prod MYSQL_SSL=false PXL_DB_STEALTH_KEY=change-this-to-a-32-char-random-secret
C. Cloud Hosting (Railway, Aiven, DigitalOcean, Render, cPanel/Hostinger)
MYSQL_HOST=containers-us-west.railway.app MYSQL_PORT=6543 MYSQL_USER=pxl_cloud_user MYSQL_PASSWORD=your_strong_cloud_password MYSQL_DATABASE=railway MYSQL_SSL=true # Optional if provider gives a CA certificate: # MYSQL_SSL_CA="-----BEGIN CERTIFICATE-----\nMII...\n-----END CERTIFICATE-----" PXL_DB_STEALTH_KEY=your-unique-production-stealth-key
D. Strict Verified TLS Cloud (PlanetScale, TiDB Cloud, AWS RDS, Google Cloud SQL)
MYSQL_HOST=aws.connect.psdb.cloud MYSQL_PORT=3306 MYSQL_USER=your_pscale_user MYSQL_PASSWORD=pscale_pw_xxxxxxxxxxxx MYSQL_DATABASE=pxl_production MYSQL_SSL=strict # Or use single URL mode: # DATABASE_URL=mysql://your_pscale_user:pscale_pw_xxxxxxxxxxxx@aws.connect.psdb.cloud:3306/pxl_production PXL_DB_STEALTH_KEY=your-unique-production-stealth-key
Connecting Every Layer in Production (Step-by-Step Checklist)
- Server-Side Database (`mysql` / `pdo` / `pxl_db`)
- Always configure
.env(never commit.envto Git; use.env.exampleas your template). - Call
mysql.connect()orpdo.connect(), define initial schema (mysql.schema(...)), and usemysql.prepare(...)ormysql.stealthBind(...)+mysql.stealthCall(...). - Note: Without
.envcredentials (or inside the browser Playground sandbox), PXL automatically falls back to its parameterized In-Memory Stealth SQL Engine so your pages never crash during development or previews.
- Client-to-Server Stealth RPC (`/api/pxl/s` & `/api/pxl/x`)
pxl-runtime.jscommunicates secretly with the server-side companion file/pages/api/pxl/s.ts(backed by/src/pxl/web/stealthCompanion.ts) using PXL Vault V2 encrypted envelopes, per-request nonces, and HMAC-SHA256 signed ephemeral session tickets (PXLRuntime.secretHandshake()/PXLRuntime.runSecureRemote()). Sensitive.envcredentials (MYSQL_*,PXL_COMPANION_SECRET,PXL_DB_STEALTH_KEY) never appear insidepxl-runtime.jsor browser responses.
- Media, Maps, Camera & Wi-Fi Components
- Use native PXL components (
ui.image,ui.videoPlayer/render_video_player,ui.googleMap/render_google_map,ui.camera/render_camera,ui.wifiFinder/render_wifi_finder) with automatic XSS/protocol sanitization and strict CSP allowlisting.
- CLI Execution with Host Permissions
- When running
.pxlscripts with live network/env access from the CLI:
node bin/pxl.js run index.pxl --allow-env --allow-net
- Build, Verification & Google Image SEO Deployment
- Verify TypeScript compiler + Next.js production build + ESLint + full test suite:
npm run generate:sitemap
npm run build
npm run lint
npm test
npm startpublic/sitemap.xmlandpublic/robots.txtindex both official domains (https://pxl-programming-language-wrii.vercel.appandhttps://ptaditech.xyz), bothpxl-runtime.jsscript URLs, and Google<image:image>metadata for the official PXL logo.- Copyright © 2026 Peter Joram · Tanzania · Beyond Code. Beyond Limits.
