PrizeX-Dokumentation

Was PrizeX ist

PrizeX ist eine PHP-basierte Gewinnspiel-, Gaming- und Marktplatz-Plattform: Auktionen, Lotterie, Mystery-Boxen, ein Arcade-Spielepaket, ein Multi-Vendor-Shop und eine Wallet-/Coin-Ökonomie — alles in einer einzigen selbst gehosteten Anwendung. Die Software basiert auf einer Plugin-/Theme-Architektur mit Adminbereich und bringt 38 Plugins für Zahlungsanbieter mit, die Karten, Wallets, Krypto und regionale Anbieter abdecken, dazu 3 vom Kern angelegte manuelle Zahlungsmethoden.

Es gibt keine SaaS-Bindung: Sie installieren die Software auf Ihrem eigenen Hosting, die Datenbank gehört Ihnen, und die Lizenz enthält lebenslange Updates. Jeder Bereich (Auktionen, Lotterie, Mystery-Boxen, Spiele, Shop) lässt sich im Adminbereich unabhängig ein- und ausschalten — eine Neuinstallation kann als Produkt mit einem einzigen Bereich oder als komplette Suite laufen.

Worauf es läuft

PrizeX läuft auf gewöhnlichem Shared Hosting oder einem VPS — es braucht keine besondere Serverkonfiguration, nur einen Webserver mit Rewrite-Unterstützung.

* Mehrere Dateien unter database/migrations/ nutzen die nur in MariaDB verfügbare Erweiterung ADD COLUMN IF NOT EXISTS. Reines MySQL 8.0/8.4 lehnt sie ab — setzen Sie als Datenbank MariaDB ein, in der Entwicklung wie im Produktivbetrieb.

Eine Neuinstallation zum Laufen bringen

Für eine Neuinstallation gibt es keinen Installationsassistenten — Sie importieren das Schema direkt und konfigurieren die Umgebungsdatei.

1. PHP-Abhängigkeiten installieren:
   composer install
2. Die Vorlage für die Umgebungsdatei kopieren und Ihre Datenbank-Zugangsdaten eintragen:
   cp .env.example .env
3. Importieren Sie database/production.sql in die Datenbank, die in Ihrer .env eingetragen ist — damit entsteht das vollständige Schema.
4. Ersetzen Sie das vorangelegte Admin-Konto (siehe Hinweis unten) und melden Sie sich dann unter /admin/ an.

Für die lokale Entwicklung genügt der eingebaute PHP-Server ohne Apache: php -S localhost:8000 router.php — beachten Sie, dass dieser Server .htaccess vollständig ignoriert, weshalb router.php dieselben Routing-Regeln von Hand nachbildet (siehe Webserver einrichten).

Umgebungsvariablen

Alle umgebungsspezifischen Einstellungen stehen in .env und werden über vlucas/phpdotenv geladen. Kopieren Sie .env.example nach .env (von Git ignoriert) und tragen Sie je Umgebung echte Werte ein — mindestens die Datenbank-Zugangsdaten, bevor Sie das Schema importieren.

Seitenweite Einstellungen, die nicht umgebungsspezifisch sind (App-Name, Währung, aktive Plugins, aktives Theme und die Schalter je Bereich), liegen in der Datenbank in tbl_settings und werden im Adminbereich verwaltet, nicht in Dateien.

Webserver einrichten

Routing- und Sicherheitsregeln — sprechende URLs, das Sperren des direkten Zugriffs auf .env/connection.php/Logdateien und das Verhindern, dass hochgeladene Inhalte als PHP ausgeführt werden — sind in .htaccess-Dateien im ganzen Projekt hinterlegt. Apache und LiteSpeed/OpenLiteSpeed lesen sie nativ.

Unter nginx nehmen Sie nginx.conf.example: Die Datei bildet jede dieser Regeln als nginx-server{}-Block ab — passen Sie server_name, root und den PHP-FPM-Socket an Ihre Umgebung an.

Request-Architektur

Jede Storefront-Seite (index.php, item.php, …) startet über includes/header.php, und zwar in dieser Reihenfolge:

connection.php startet die Session, verbindet sich per mysqli mit den Zugangsdaten aus .env, lädt tbl_settings in Konstanten wie APP_NAME und CURRENCY und meldet den aktuellen Nutzer samt eines Datensatzes mit Geräte-Fingerabdruck an. plugins_load() startet jedes aktive Plugin und löst den Hook plugins_loaded aus — erst an diesem Punkt steht fest, welche Bereiche tatsächlich aktiv sind. Genau deshalb gleicht header.php anschließend die alten Einstellungs-Flags (shop, multivendor, auction, lottery) noch einmal mit dem echten Aktivierungsstand der Plugins ab.

Der Adminbereich dupliziert diesen Bootstrap nicht — admin/includes/connection.php setzt admin-spezifische Session- und Fehlereinstellungen und bindet dann dieselbe includes/connection.php aus dem Projektstamm ein.

Plugin-System

Ein Plugin besteht aus plugins/<slug>/plugin.php — Metadaten im Kopfkommentar, die ausgelesen werden, ohne die Datei auszuführen — plus einer optionalen plugin.json für ausführlichere Katalogangaben. Die aktiven Plugins stehen als JSON-Array in tbl_settings.active_plugins.

• Tabellenhoheit — jedes Plugin definiert seine eigene includes/schema.php, die bei der Aktivierung aufgerufen wird und den idempotenten Helfer db_delta() nutzt (CREATE TABLE IF NOT EXISTS + rein additives ALTER TABLE ADD COLUMN). Ein Plugin fasst niemals die Tabellen eines anderen Plugins an.
• Die Registries laden zuerst — add_admin_page, add_route, add_cron_job, add_api_route und register_module sind allesamt definiert, bevor irgendein Plugin geladen wird. Aufrufe auf oberster Ebene eines Plugins lösen deshalb nie einen Fatal Error aus, selbst wenn das Plugin am Ende inaktiv bleibt.
• Sauberes Entfernen — beim Löschen eines Plugins läuft dessen uninstall.php, und sein Ordner wird entfernt; außerhalb von plugins/<slug>/ darf nichts seine Dateien zwingend einbinden, damit der Rest der Seite auch ohne das Plugin weiterläuft.

Theme-System

Ein Theme liegt unter assets/themes/<slug>/ — eine manifest.php, eine theme.css, eine functions.php für Theme-Hooks und ein optionales components/. Das aktive Theme steht in tbl_settings.active_theme; ist keines gesetzt, greift editorial als Fallback.

Komponenten werden in dieser Reihenfolge aufgelöst: zuerst der eigene components/-Ordner des aktiven Themes, dann das per register_module() angemeldete Komponentenverzeichnis eines Plugins, dann das gemeinsame components/ im Projektstamm. In der Praxis heißt das: Die gemeinsame Standardfassung liegt genau einmal in components/, und jedes Theme — oder jedes aktive Bereichs-Plugin — kann einen bestimmten Komponentenpfad mit einer eigenen Kopie überschreiben.

Datenbank

Tabellenpräfix tbl_, direktes mysqli, überwiegend Prepared Statements. Die SQL-Dateien, nach Verbindlichkeit geordnet:

• database/core-schema.sql — von Hand gepflegt, ausschließlich Kerntabellen; die Tabellen der Bereiche und Plugins sind bewusst ausgenommen.
• database/production.sql — generiert (Kernschema plus die eigene Installationsroutine jedes Plugins, aus einer leeren Wegwerf-Datenbank exportiert). Das ist die Datei, die Sie für eine Neuinstallation importieren.
• database/sandbox.sql — Demo- und Beispieldaten für die lokale Entwicklung.
• database/migration.sql — konsolidiertes, idempotentes Upgrade-Skript für bestehende Installationen.
• database/migrations/<slug>/up.sql (+ down.sql, wo umkehrbar) — eine Datei je einzelner Migration.

Module

Jedes Modul steckt in derselben Installation und lässt sich im Adminbereich einzeln ein- und ausschalten.

Auktionen

Live-Gebote mit Multi-Vendor-Verkäuferportal und Provisions-Engine. Kern-Plugin: plugins/auction.

Lotterie

Ziehungen mit Losen, dazu konfigurierbare Zeitpläne, Preise und Gewinnerbenachrichtigungen. Kern-Plugin: plugins/lottery.

Mystery-Box

Konfigurierbare Gewinnpools mit Aufdeck-Animationen — Nutzer kaufen eine Box und sehen sofort, was sie gewonnen haben. Plugin: plugins/mystery-box.

Spiele & Belohnungen

Ein Arcade-Paket unter games/ plus Plugins für Nutzerbindung und Verdienstmöglichkeiten:

Shop & Marktplatz

Eine Multi-Vendor-E-Commerce-Schicht mit Werkzeugen für Aktionen und Warenpräsentation. Kern-Plugins: plugins/shop, plugins/multivendor.

Wallet, Coins & Investieren

Eine plattformweite Wallet, die alle Module gemeinsam nutzen.

Empfehlungen & Belohnungen

Anmeldung, Vertrauen & Compliance

Werkzeuge

Adminbereich

Der Adminbereich liegt unter admin/ und dupliziert den Bootstrap der Storefront nicht — er setzt admin-spezifische Session- und Fehlereinstellungen und bindet dann dieselbe includes/connection.php aus dem Projektstamm ein. Seiten melden sich über add_admin_page() an, das den Eintrag in der Seitenleiste, die Rechteprüfung, CSRF und die Anmelde-Rahmenlogik übernimmt; rein administrative JSON-Aktionen melden sich über add_admin_ajax() an und werden über admin/ajax.php?action=<slug> aufgerufen.

Storefront-Themes

Fünf Themes werden unter assets/themes/ mitgeliefert und lassen sich je Installation im Adminbereich umschalten. Jedes Theme hält seine eigene Kopie der gemeinsamen Komponenten in seinem eigenen components/-Ordner.

Zahlungsanbieter

Die 38 automatischen Zahlungsanbieter gehören jeweils einem Plugin — jeder liegt in seinem eigenen Ordner plugins/gateway-<slug>/ und meldet sich über add_payment_gateway() beim Kern an. Einen davon zu aktivieren genügt; im Checkout-Dispatcher (payment_processor.php) ist nichts auf einen bestimmten Anbieter fest verdrahtet.

Die 3 manuellen Methoden sind vom Kern angelegte Datensätze mit gateway_type = 'manual', ohne Init- oder Verify-Code, den man konfigurieren müsste — sie zeigen lediglich eine Zahlungsanleitung oder einen QR-Code an. Mit dem Plugin manual-gateway-builder legt ein Administrator weitere eigene manuelle Zahlungsmethoden an, ohne Code anzufassen.

Einige Anbieter (Stripe, Razorpay, Midtrans, Venmo) melden zusätzlich einen render-Hook an, für Checkout-Abläufe, die clientseitiges JS brauchen — einen Bootstrap für Stripe Checkout oder ein Razorpay-, Midtrans- oder Braintree-SDK, das zuerst eine serverseitig erzeugte Bestell-ID oder ein Token benötigt. Jeder andere Anbieter läuft ganz ohne zusätzliche Verdrahtung im Kern.

API- & AJAX-Schichten

• api/v1/ — per JWT authentifizierte REST-API für die Mobile App und externe Anwendungen. api/v1/middleware/*.php prüft den Header Authorization: Bearer <token>. Plugins ergänzen eigene Endpunkte über add_api_route().
• ajax/ — internes AJAX für das eigene JS der Storefront (Warenkorb, Gutscheine, Benachrichtigungen), authentifiziert über das Session-Cookie. Keine Token-Schicht — es stützt sich auf die PHP-Session, die connection.php aufbaut.
• Loses api/ auf oberster Ebene — verschiedene nicht versionierte Endpunkte wie geo_location.php, exchange-rate.php und offerwall_postback.php.

Mobile App

mobile/ ist ein eigenes Projekt auf Basis von Capacitor und Ionic — ein WebView-Wrapper um die Live-Seite, keine eigenständige SPA und nicht ausschließlich ein Konsument von api/v1. In seiner capacitor.config.ts zeigt server.url auf Ihre Domain. Es hat seine eigene package.json und wird nicht aus dem Projektstamm heraus gebaut:

Updates & Migrationen

Legen Sie einen Snapshot an, bevor Sie database/migration.sql oder eine database/migrations/<slug>/up.sql auf einer Live-Datenbank ausführen:

Zu den meisten Migrationen gehört eine passende down.sql, die genau diese eine Änderung zurücknimmt. Einige wenige, die bestehende Daten umformen statt nur Struktur zu ergänzen, liefern stattdessen eine down.sql, die dokumentiert, warum sie nichts tut — dort spielen Sie für einen Rollback den Dump von vor dem Deployment zurück.

Hinweise zur Sicherheit

• Wechseln Sie die vorangelegten Admin-Zugangsdaten sofort nach dem Import (siehe Installation).
• .env, connection.php und Logdateien sind über die mitgelieferten Regeln in .htaccess bzw. nginx vom direkten HTTP-Zugriff ausgeschlossen — entfernen Sie diese Regeln nicht.
• Hochgeladene Inhalte werden so ausgeliefert, dass sie nicht als PHP ausgeführt werden können — durchgesetzt in der Webserver-Konfiguration, nicht auf Anwendungsebene.
• Zugangsdaten für Zahlungsanbieter werden je Anbieter im Adminbereich hinterlegt und serverseitig gespeichert — sie gelangen nie in die Storefront.

Tests

Es gibt keine PHPUnit-Suite. composer test führt bin/run-probes.php aus, das jede probe_*.php-Datei unter includes/_probes/ und im jeweils eigenen _probes/-Ordner der Plugins einsammelt, jede davon als CLI-Subprozess startet und ihren Exit-Code prüft.

Häufige Fragen

Support & Ressourcen

Kommen Sie nicht weiter oder brauchen Sie etwas, das diese Seite nicht abdeckt?