Kernfunktionen

In diesem Abschnitt dokumentieren wir alle Kernfunktionen der JsonSQL-Klasse im Detail. Jede Methode ist modular aufgebaut und kann mit oder ohne Tabellenbindung verwendet werden. Viele Funktionen lassen sich miteinander kombinieren und sind methodenverkettet einsetzbar.

📥 insert()

• Rückgabewert: void – kein Rückgabewert
• Parameter: array $records – Einzelner oder mehrere Datensätze als Array

[Trait: JS_CRUD]

Mit der Methode insert() lassen sich ein oder mehrere Datensätze in die aktuell gewählte Tabelle einfügen.

Wenn system.json nicht vorhanden ist, übernimmt JsonSQL alle Felder automatisch – ohne Validierung oder feste Felddefinitionen.

Wenn eine system.json vorhanden ist, richtet sich das Verhalten nach der Option "allowAdditionalFields":

• true – zusätzliche Felder werden beim Insert mitgespeichert
• false (Standard) – nur Felder, die in system.json definiert sind, werden übernommen

$db->insert([
  'name' => 'Alice',
  'email' => 'alice@example.com'
]);

// Mehrere Einträge auf einmal
$db->insert([
  ['name' => 'Bob'],
  ['name' => 'Charlie']
]);

Wird eine system.json verwendet, folgt der Insert-Vorgang definierten Regeln:

• Felder wie id, uuid, created_at usw. werden automatisch ergänzt.
• Datentypen wie string, integer, float, enum usw. werden validiert.
• Standardwerte, Min/Max-Prüfungen und Auto-Funktionen (z. B. AutoHash oder Autoincrement) werden angewendet.

⚙️ Option: allowAdditionalFields

Die system.json kann steuern, ob beim Einfügen zusätzliche Felder erlaubt sind, die nicht in der Felddefinition vorkommen. Das wird über den Schalter "allowAdditionalFields": true geregelt.

{
  "allowAdditionalFields": true,
  "fields": {
    "name": { "dataType": "string" },
    "created_at": { "dataType": "datetime" }
  }
}

Ist diese Option aktiviert, dürfen beim Insert auch neue Felder wie z. B. nickname oder info mitgegeben werden. Wenn sie deaktiviert ist, werden nur Felder übernommen, die in fields explizit definiert sind – alle anderen werden ignoriert.

🔍 Intern passiert Folgendes:

• applyAutoFields() ergänzt alle Felder laut Systemdefinition.
• insertAdditionalFields() prüft, ob weitere Felder erlaubt sind (via allowAdditionalFields).
• Der finale Datensatz wird validiert und am Ende der Tabelle gespeichert.

➕ Tipp: Nutze die system.json, um deine Tabellenstruktur gezielt zu steuern und automatisch sichere, saubere Einträge zu gewährleisten.

🛠️ update()

• Trait: JS_CRUD
• Rückgabewert: int – Anzahl der erfolgreich aktualisierten Datensätze
• Parameter: array $fieldsToUpdate – Zu ändernde Feld/Wert-Paare

Aktualisiert gezielt alle Datensätze in der aktuell gewählten Tabelle, die den gesetzten where()-Filtern entsprechen. Nur die gefilterten Datensätze werden angepasst – alle anderen bleiben unverändert.

Besonderheiten:

• Die Methode ist nicht destruktiv: Nur die übergebenen Felder werden verändert.
• Felder mit "auto_modified_timestamp": true in der system.json werden automatisch mit einem aktuellen Zeitstempel aktualisiert.
• Die Zeitformate und Zeitzonen dieser Felder sind individuell definierbar (z. B. format, timezone).
• Verwendet flock() zur sicheren Dateisperre beim Schreiben.

$affected = $db->from('produkte')
               ->where('kategorie', '=', 'Haushalt')
               ->update([
                   'status' => 'archiviert',
                   'sichtbar' => false
               ]);

echo "$affected Datensätze aktualisiert.";

Damit Felder automatisch mit dem aktuellen Datum/Zeit aktualisiert werden, muss in der system.json ein entsprechender Eintrag vorhanden sein:

{
  "fields": {
    "updated_at": {
      "dataType": "datetime",
      "auto_modified_timestamp": true,
      "format": "Y-m-d H:i:s",
      "timezone": "Europe/Berlin"
    }
  }
}

Diese Regelung gilt für beliebige Feldnamen. Du kannst mehrere Felder definieren, die bei jeder Änderung automatisch aktualisiert werden – mit jeweils eigenem Format und Zeitzone.

Wird where() nicht gesetzt, werden alle Datensätze in der Tabelle aktualisiert (mit Vorsicht verwenden).

🗑️ delete()

• Trait: JS_CRUD
• Rückgabewert: int – Anzahl gelöschter Datensätze

Löscht alle Datensätze aus der aktuell gewählten Tabelle, die den gesetzten where()-Filtern entsprechen. Die Datei wird dabei exklusiv gesperrt, um gleichzeitige Schreibzugriffe zu verhindern.

Wichtig:

• Die Methode from() muss zuvor aufgerufen worden sein.
• Nur Datensätze, die exakt den Filterbedingungen entsprechen, werden entfernt.
• Die gesetzten Filter bleiben nach dem Löschen aktiv – diese müssen ggf. manuell zurückgesetzt werden.

// Einzelne Bedingung
$deleted = $db->from('produkte')
              ->where('preis', '<', 10)
              ->delete();

// Mehrere Bedingungen
$deleted = $db->from('kunden')
              ->where([
                  ['land', '=', 'DE'],
                  ['newsletter', '=', false]
              ])
              ->delete();

echo "$deleted Datensätze gelöscht.";

Die Methode gibt die Anzahl der erfolgreich gelöschten Datensätze zurück. Ein Wert von 0 bedeutet, dass kein Eintrag den Kriterien entsprach.

🎯 select()

[Trait: JS_Query]

Mit select() bestimmst du, welche Felder (Spalten) aus der aktuellen Tabelle bei der Abfrage zurückgegeben werden sollen. Diese Methode ist optional – wenn sie nicht verwendet wird oder mit '*' aufgerufen wird, werden alle Felder zurückgegeben.

Du kannst die Methode mit einem einzelnen String oder einem Array aufrufen. Aliasnamen sind möglich – z. B. "preis AS cost" – und helfen dir, Felder umzubenennen.

// Gibt alle Felder zurück
$rows = $db->from('users')->select('*')->get();

// Nur bestimmte Felder
$rows = $db->from('users')->select('id, name')->get();

// Mit Aliasnamen
$rows = $db->from('products')->select('title AS Produktname, price AS Preis')->get();

// Array-Variante
$rows = $db->from('products')->select(['title AS name', 'price'])->get();

Besonderheiten:

• Mehrfaches Aufrufen von select() ist erlaubt – der letzte Aufruf überschreibt die vorherigen Einstellungen.
• Wird kein select() verwendet, ist das Verhalten wie bei select('*').
• Aliasnamen (AS) werden automatisch erkannt (case-insensitive).
• Felder, die im Datensatz fehlen, werden mit null gefüllt.

Internes Verhalten:

• Alle ausgewählten Felder werden in $this->select gespeichert.
• Die Zuordnung von Aliasnamen erfolgt über $this->aliasMap.
• Beim späteren Aufruf von get() wird die Auswahl über applySelect() umgesetzt.

Beispielausgabe:

[
  {
    "Produktname": "Wasserkocher",
    "Preis": 39.99
  },
  {
    "Produktname": "Toaster",
    "Preis": 29.95
  }
]

🔁 Diese Auswahl beeinflusst die Ausgabe von get() und ist kombinierbar mit where(), orderBy(), limit(), groupBy() usw.

🔎 where()

[Trait: JS_Query]

Die Methode where() filtert die Datensätze anhand definierter Bedingungen. Du kannst mehrere Bedingungen gleichzeitig prüfen und sie logisch mit AND oder OR verknüpfen (Standard: OR).

Jede Bedingung besteht aus einem Array mit drei Elementen: [Feld, Operator, Wert]. Alternativ kannst du eine Bedingung auch mit 'not' negieren.

// Einzelne Bedingung
$db->where([['vendor', '=', 'Aldi']]);

// Mehrere Bedingungen mit AND
$db->where([
  ['vendor', '=', 'Aldi'],
  ['rating', '>=', 4]
], 'AND');

// Negation mit NOT
$db->where([
  ['not', ['rating', '=', 2]],
  ['vendor', '=', 'Lidl']
], 'AND');

// IN-Filter
$db->where([
  ['vendor', 'in', ['Aldi', 'Lidl']],
  ['product', 'not in', 'Toaster, Wasserkocher']
], 'AND');

Unterstützte Operatoren:

• =, == – Gleichheit
• != – Ungleichheit
• >, >=, <, <= – Vergleichsoperatoren
• like – Textsuche mit Platzhalter %
• in, not in – Vergleich mit einer Liste (Array oder String)
• not – Negation einer einzelnen Bedingung

Verknüpfung:

• Standardmäßig werden Bedingungen mit ODER verknüpft ('OR')
• Mit dem zweiten Parameter kannst du 'AND' erzwingen
• Mit $append = true kannst du mehrere where()-Aufrufe kombinieren

Internes Verhalten:

• Alle Bedingungen werden in $this->filters gespeichert
• Die Verknüpfung (AND/OR) steht in $this->mergeCondition
• Beim get() werden alle Filter mit applyFilters() ausgewertet

Beispielausgabe:

[
  {
    "vendor": "Aldi",
    "product": "Wasserkocher",
    "rating": 4
  }
]

🔁 Diese Filterung kann mit select(), orderBy(), groupBy() usw. kombiniert werden.

📦 get()

[Trait: JS_CRUD]

Die Methode get() ist das Herzstück jeder Abfrage in JsonSQL. Sie führt alle gesetzten Bedingungen aus und gibt die Ergebnisse zurück – ähnlich wie ein klassisches SQL-SELECT.

Tabelle wählen

Bevor get() ausgeführt werden kann, muss eine Tabelle gesetzt sein. Dafür stehen drei Varianten zur Verfügung:

• $db->from('users') – lädt die Tabelle und setzt sie als aktiv. Optional mit autoload = true, um sie direkt zu lesen.
• $db->setTable('users') – setzt nur die Tabelle ohne sofortige Leseoperation.
• $db->truncate() – leert die aktuelle Tabelle vollständig (Achtung: destruktiv).

Optional verwendbar: join()

Falls du Daten aus mehreren Tabellen kombinieren möchtest, kannst du join() vor get() in die Kette einfügen:

$db->from('orders')
   ->join('users', 'orders.user_id', '=', 'users.id')
   ->select('orders.id, users.name')
   ->get();

Typischer Anwendungsfall:

// Abfrage mit Filter, Auswahl und Sortierung
$rows = $db->from('products')
           ->where('price', '>', 20)
           ->orderBy('price', 'desc')
           ->select('name AS Produktname, price AS Preis')
           ->limit(5)
           ->get();

Verarbeitungsschritte (intern):

1. 📁 Tabelle wird geladen (nur bei from())
2. 🔍 Filter: where()
3. 🔗 Joins (optional)
4. 📊 Gruppierung: groupBy()
5. 🔃 Sortierung: orderBy()
6. ⏳ Limitierung: limit()
7. 🎯 Feld-Auswahl: select()

Rückgabe:

Ein Array von assoziativen Arrays – jeder Eintrag entspricht einem Datensatz.

[
  { "Produktname": "Kaffeemaschine", "Preis": 79.90 },
  { "Produktname": "Toaster",        "Preis": 39.99 },
  ...
]

Hinweise:

• Wenn select() nicht aufgerufen wurde, gibt get() alle Felder zurück.
• Die Methode verändert keine Daten – sie ist rein lesend.
• In Kombination mit paginate() enthält die Rückgabe auch Metainformationen zur Seitennavigation.

📌 Intern werden alle Schritte strikt in Reihenfolge ausgeführt. Die Methode get() schließt die Abfrage ab.

❓ exists()

[Trait: JS_CRUD]

Prüft, ob ein bestimmter Datensatz existiert (true/false):

$exists = $db->from('users')->where('email', '=', 'bob@example.com')->exists();
  

🎯 pluck()

• Parameter:
• string $column – Der Feldname, der ausgegeben werden soll
• bool $all = false – Gibt bei true alle Werte zurück, sonst nur den ersten

[Trait: JS_CRUD]

Gibt den Wert eines bestimmten Feldes zurück – entweder vom ersten Datensatz oder von allen.

// Einzelwert (erster Treffer)
$email = $db->from('users')
            ->where('id', '=', 1)
            ->pluck('email');

// Mehrere Werte
$alleEmails = $db->from('users')
                 ->pluck('email', true);

• 📥 Gibt standardmäßig nur den ersten Wert zurück
• 🔁 Wenn true als zweiter Parameter gesetzt ist, wird ein Array aller Werte geliefert
• 💡 Kombinierbar mit where(), orderBy(), limit() etc.

Tipp: Ideal für Dropdowns, Autovervollständigung oder schnelle Lookups!

🥇 first()

[Trait: JS_CRUD]

Gibt den ersten passenden Datensatz einer Abfrage zurück – ideal für gezielte Einzelergebnisse wie Benutzer- oder Detaildaten.

$user = $db->from('users')
           ->where('email', '=', 'alice@example.com')
           ->first();

if ($user) {
    echo "Willkommen zurück, " . $user['name'];
}

• ✅ Gibt ein array mit den Felddaten zurück
• 🚫 Gibt null zurück, wenn kein Treffer gefunden wurde
• ⚡ Intern wird automatisch limit(1) gesetzt – schnell und effizient

Tipp: Kombiniere select(), where() und first() für gezielte Feldabfragen.

🧹 clearTable()

• Rückgabewert: void – Kein Rückgabewert
• Parameter: string $tableName – Name der Tabelle, die geleert werden soll

[Trait: JS_TABLES]

clearTable(string \$tableName) ist ideal für gezielte Löschvorgänge bei vorhandenen Tabellen, ohne das Risiko, versehentlich neue Dateien anzulegen. Anders als truncate() wird keine Tabelle erstellt, wenn sie fehlt.

📌 Methodensignatur

public function clearTable(string $tableName): void

📋 Beispiel

$json = new JsonSQL('data');
$json->clearTable('produkte'); // Inhalt der Tabelle 'produkte' wird geleert

✅ Unterschiede zu truncate()

• clearTable() → leert nur, wenn Tabelle existiert
• truncate() → leert oder erstellt leere Datei

❗ Fehlerbehandlung

• Wenn die Tabelle nicht existiert, wird eine Exception mit einer klaren Fehlermeldung geworfen.

☠️ clear()

• Rückgabewert: void – Kein Rückgabewert
• Parameter: bool $requireConfirmation – Muss auf true gesetzt werden, um die Aktion zu bestätigen

[Trait: JS_DATBASE]

Mit clear(bool \$requireConfirmation) entfernst du sämtliche JSON-Dateien (also Tabellen) aus dem aktuell gesetzten Datenbankverzeichnis. Der Parameter \$requireConfirmation muss explizit auf true gesetzt werden, um versehentliches Löschen zu vermeiden.

📌 Methodensignatur

public function clear(bool $requireConfirmation = false): void

📋 Beispiel

$json = new JsonSQL('data');
$json->clear(true); // Alle Tabellen löschen (nur mit Bestätigung!)

🧠 Hinweis

• Ohne true als Parameter wird die Methode mit einer Exception abgebrochen.
• Diese Methode löscht nur die .json-Tabellen, nicht die .system.json-Dateien – sofern du das möchtest, kannst du das intern noch erweitern.

📄 paginate()

Teilt große Ergebnislisten in Seiten auf:

$page = 1;
$limit = 10;
$result = $db->from('users')->paginate($page, $limit);
  

Die Rückgabe enthält Einträge, Gesamtanzahl, Seitenanzahl und mehr.

Datenfelder & system.json

📘 Einführung

In JsonSQL kann jede Tabelle durch eine ergänzende .system.json-Datei um eine strukturierte Felddefinition erweitert werden. Diese Datei steuert automatisch:

• ⚙️ die Feldtypen (dataType) und ihre Eigenschaften
• 🛡️ Validierungsregeln wie required, min, max, enum
• 🔐 Verschlüsselung einzelner Felder mit encrypt
• ⏱️ automatische Timestamps bei Erstellung und Änderung
• 🧮 automatisches Hochzählen von Feldern (autoincrement)
• 🎲 Zufallswerte oder Hashes

Die system.json ist optional, wird jedoch bei komplexeren Datenstrukturen empfohlen, da sie die Validierung und Automatisierung auf Tabellenebene kapselt und die Wartbarkeit erhöht.

JsonSQL lädt diese Konfiguration automatisch beim Setzen der Tabelle mittels setTable() und nutzt sie u. a. bei:

• insert() – automatische Ergänzung & Prüfung von Feldern
• update() – Validierung & Timestamp-Aktualisierung
• analyzeTable() – strukturelle Analyse der Tabellendaten

Die Konfiguration befindet sich standardmäßig in [TABELLE].system.json im selben Verzeichnis wie die Tabelle selbst.

Filterlogik mit where()

Mit where() kannst du gezielt Datensätze filtern. JsonSQL unterstützt eine Vielzahl an Operatoren, auch in Kombination. Du kannst einfache Vergleiche durchführen oder komplexe Bedingungen mit verschachtelten Feldern und Filtergruppen bauen.

🔣 Unterstützte Operatoren

Standardmäßig stehen dir diese Operatoren zur Verfügung:

• = (gleich)
• != (ungleich)
• >, >=, <, <=
• in, not in (Array-Vergleich)
• like (enthält Teilstring, Case-insensitiv)
• between (zwischen zwei Werten)

// Benutzer mit Alter > 30
$db->from('users')->where('age', '>', 30)->get();

// Benutzer mit Namen in Liste
$db->where('name', 'in', ['Alice', 'Bob']);

// Email enthält "gmail"
$db->where('email', 'like', 'gmail');
  

🔗 Kombinierte Bedingungen (and / or)

Mehrere Filter kannst du mit andWhere() oder orWhere() kombinieren:

$db->from('users')
   ->where('age', '>', 30)
   ->andWhere('status', '=', 'active')
   ->get();

$db->orWhere('name', '=', 'Alice')
   ->orWhere('name', '=', 'Bob');
  

🪆 Nested-Felder und Pfadfilter

Du kannst auch auf verschachtelte Felder zugreifen, z. B. bei Objekten oder Arrays innerhalb eines Datensatzes:

// Greife auf verschachteltes Feld zu
$db->where('address.city', '=', 'Berlin');

// Oder in Arrays mit Index
$db->where('roles.0', '=', 'admin');
  

🧩 Filtergruppen

Du kannst auch mehrere Bedingungen gruppieren und so komplexere Logik umsetzen. Dafür nutzt du Arrays als Eingabe:

$db->where([
  ['status', '=', 'active'],
  ['age', '>', 30]
]);

$db->orWhere([
  ['country', '=', 'DE'],
  ['country', '=', 'AT']
]);
  

Die Filterlogik ist flexibel, performant und erweiterbar – ideal für komplexe Abfragen auf JSON-Basis. Weitere Filterfunktionen wie groupBy(), orderBy() und limit() werden in separaten Abschnitten behandelt.

Aggregation & Statistik

JsonSQL unterstützt eine Vielzahl an Aggregatfunktionen, mit denen du deine Daten gruppieren, zählen, zusammenfassen oder statistisch analysieren kannst. Diese Funktionen sind ideal für Auswertungen, Dashboards oder Reports.

📊 groupBy()

Gruppiert die Datensätze nach einem bestimmten Feld und erlaubt dir, Aggregatfunktionen innerhalb dieser Gruppen anzuwenden.

// Anzahl Nutzer pro Land
$db->from('users')
   ->groupBy('country')
   ->count();
  

➕ Aggregatfunktionen

Folgende Funktionen stehen dir zur Verfügung:

• count() – Anzahl der Einträge
• sum('feld') – Summe eines Feldes
• avg('feld') – Durchschnitt
• min('feld'), max('feld')
• median('feld')
• mode('feld') – häufigster Wert
• stddev('feld'), variance('feld')
• range('feld') – Spanne zwischen Min und Max

// Gesamtsumme aller Bestellungen
$total = $db->from('orders')->sum('amount');

// Durchschnittsalter aller Nutzer
$avg = $db->from('users')->avg('age');
  

📈 stats() – kombinierte Übersicht

Mit stats('feld') bekommst du alle wichtigen Kennzahlen in einem Aufruf:

$stats = $db->from('users')->stats('age');
/* Gibt zurück:
[
  'count' => 100,
  'sum' => 2300,
  'avg' => 23,
  'min' => 18,
  'max' => 65,
  'median' => 22,
  'mode' => 21,
  'stddev' => 4.2,
  'variance' => 17.64,
  'range' => 47
]
*/
  

Du kannst stats() auch mit groupBy() kombinieren:

// Statistik pro Land
$statistik = $db->from('users')->groupBy('country')->stats('age');
  

Mit diesen Tools kannst du deine Daten schnell analysieren – direkt aus JSON-Dateien heraus, ganz ohne klassische Datenbank.

Joins & Beziehungen

JsonSQL unterstützt SQL-ähnliche Joins, um Daten aus mehreren Tabellen zu kombinieren. Dabei kannst du klassische inner, left, right oder full Joins nutzen – alles direkt auf JSON-Basis.

🔗 join()-Logik

Die Methode join() erlaubt das Verknüpfen zweier Tabellen anhand gemeinsamer Felder:

$rows = $db->from('orders')
  ->join('users', 'user_id', '=', 'id', 'left')
  ->get();
  

Parameter:

• Tabelle: Die zweite Tabelle, z. B. users
• Feld 1: Feld aus der Haupttabelle
• Operator: Meist =
• Feld 2: Feld aus der zweiten Tabelle
• Typ: inner, left, right, full

🔁 n:m-Beziehungen über Zwischentabellen

Für viele-zu-viele-Beziehungen empfiehlt sich eine Zwischentabelle:

Tabellen:
- products.json
- tags.json
- product_tags.json (Felder: product_id, tag_id)
  

Beispiel:

$db->from('product_tags')
   ->join('products', 'product_id', '=', 'id')
   ->join('tags', 'tag_id', '=', 'id')
   ->get();
  

So erhältst du kombinierte Informationen aus allen drei Tabellen.

✅ Best Practices

• Nutze eindeutige IDs für Relationen
• Halte Relationen schlank (keine riesigen JSON-Objekte einbetten)
• Vermeide Duplikate durch gute Datenmodellierung
• Trenne Stammdaten (z. B. Produkte) und Meta-Relationen (z. B. Kategorien)
• Nutze pluck() oder groupBy() für zusammengefasste Daten

🚀 Live-Demo

• Demo: Klassischer Join (orders + users)
• Demo: n:m (products + tags über mapping)

Joins sind ein starkes Werkzeug, um deine JSON-Daten strukturiert zu verbinden – fast wie in echten relationalen Datenbanken.

Extras & Tools

JsonSQL bietet eine Reihe nützlicher Zusatzfunktionen für Entwickler, Power-User und Admins. Hier findest du praktische Tools wie Import/Export, Backupfunktionen, Locking-Mechanismen und eine einfache SQL-Parser-Schnittstelle.

📤 import() & 📥 export()

Du kannst Tabellen oder ganze Datenbanken als JSON-Dateien importieren oder exportieren – z. B. für Backups oder Migrationszwecke:

// Ganze Tabelle exportieren
$data = $db->from('users')->export();

// Importieren
$db->from('users')->import($data);
  

🔒 Locking & paralleler Zugriff

JsonSQL arbeitet mit Dateisperren, um gleichzeitige Schreibzugriffe abzusichern. Beim Öffnen einer Tabelle wird automatisch ein exklusiver flock() verwendet. Damit ist auch Multiuser-Zugriff auf dem gleichen Server möglich.

Tipps:

• Immer get() oder save() korrekt abschließen
• Keine Dauerprozesse mit blockierenden Operationen!

🗂️ Backupstrategien

Backups können automatisch oder manuell erfolgen. Aktiviere die Option enableBackups(true), um bei jedem Speichern eine Kopie in /backups abzulegen:

$db->enableBackups(true);
  

Backups werden automatisch mit Zeitstempel versehen und in einem separaten Unterordner abgelegt.

📝 SQL-Parser mit query()

Mit query() kannst du einfache SQL-Befehle ausführen, die intern auf JsonSQL gemappt werden. Unterstützt werden aktuell:

• SELECT ... FROM ... WHERE ...
• INSERT INTO ...
• UPDATE ... SET ...
• DELETE FROM ...

$db->query("SELECT * FROM users WHERE age > 18");
  

Ideal für einfache API-Schnittstellen oder SQL-ähnliche Skripte.

🐞 Logging & Debugging (FancyDumpVar)

Für tieferen Einblick in die Funktionsweise kannst du das Tool FancyDumpVar nutzen. Es visualisiert interne Objekte, Status und Rückgaben direkt im Browser:

$debugger->addInfoText('Datenbankobjekt');
$debugger->dump($db);

$debugger->addInfoText('Letzte Einträge');
$debugger->dump($rows);
  

FancyDumpVar ist ideal bei der Plugin-Entwicklung, für Analysezwecke oder zum Nachvollziehen von komplexeren Abläufen.

Erweiterung & eigene Module

JsonSQL ist modular aufgebaut. Du kannst eigene Module erstellen, um die Funktionalität zu erweitern oder Speziallogik für dein Projekt einzubinden – ganz ohne die Hauptklasse zu verändern.

🧩 Neue Module erstellen & einbinden

Lege einfach eine neue Datei im src/-Verzeichnis an, z. B. JS_CustomDemo.php. Die Datei muss eine Trait-Definition enthalten, die dann in JsonSQL.php eingebunden wird:

// Datei: src/JS_CustomDemo.php
trait JS_CustomDemo {
  public function sayHello($name) {
    return "Hallo, $name!";
  }
}

Danach fügst du die Datei in JsonSQL.php ein:

require_once __DIR__ . '/JS_CustomDemo.php';
class JsonSQL {
  use JS_CustomDemo;
  // ...weitere Module...
}

🧱 Struktur & Best Practices

• Jedes Modul als JS_*.php benennen
• Immer einen trait verwenden
• Methoden sprechend und eindeutig benennen
• Keine direkten echo-Ausgaben in Modulen – lieber Rückgabewerte verwenden
• Verwende interne Methoden wie $this->load() oder $this->save(), falls du mit Tabellen arbeitest

📦 Beispiele für eigene Module

Einige Beispielmodule findest du in den Demos:

• JS_Export.php – Export/Import von JSON-Daten
• JS_SQLParser.php – SQL-kompatibler Query-Parser
• JS_System.php – Automatische Felder und system.json-Regeln
• JS_CustomUUID.php – eigenes Modul zur UUID-Erzeugung

🚀 Demo: Custom Modul

• Demo: Eigene Methode sayHello()

Mit dieser modularen Struktur kannst du JsonSQL beliebig erweitern – ideal für eigene Projekte, Frameworks oder spezialisierte Tools.

API-Referenz

Die folgende API-Referenz listet alle öffentlichen Methoden der JsonSQL-Klasse mit Signatur, Beschreibung, Parametern und Rückgabewerten auf. Sie eignet sich als Nachschlagewerk für Entwickler.

📥 insert()

Beschreibung: Fügt einen oder mehrere Datensätze in die aktive Tabelle ein.

insert(array|array[] $data): array

• $data: Einzelnes Array oder Array von Arrays mit Feldern und Werten

Rückgabe: Array mit eingefügten Einträgen (inkl. Auto-Felder)

🛠️ update()

Beschreibung: Aktualisiert Einträge gemäß Filterkriterien.

update(array $values): int

• $values: Felder und neue Werte

Rückgabe: Anzahl der aktualisierten Datensätze

🗑️ delete()

Beschreibung: Löscht Einträge gemäß aktueller Filterung.

delete(): int

Rückgabe: Anzahl der gelöschten Einträge

🔎 get()

Beschreibung: Führt die aktuelle Abfrage aus und gibt das Ergebnis zurück.

get(): array

Rückgabe: Liste der Datensätze (ggf. gefiltert, sortiert etc.)

🔍 where()

Beschreibung: Fügt eine Filterbedingung hinzu.

where(string $field, string $operator, mixed $value): self

🔗 join()

Beschreibung: Verknüpft eine weitere Tabelle mit der aktuellen via Join.

join(string $table, string $field1, string $operator, string $field2, string $type = 'inner'): self

🎯 pluck()

Beschreibung: Gibt eine Spalte als flaches Array zurück.

pluck(string $field): array

🥇 first()

Beschreibung: Gibt das erste Ergebnis der Abfrage zurück.

first(): ?array

♻️ clear()

Beschreibung: Löscht alle Datensätze in der aktuellen Tabelle.

clear(): bool

📄 paginate()

Beschreibung: Gibt eine paginierte Liste mit Meta-Daten zurück.

paginate(int $page, int $limit): array

📊 stats()

Beschreibung: Gibt Statistikwerte zu einem Feld zurück.

stats(string $field): array

📝 query()

Beschreibung: Führt einen einfachen SQL-Befehl aus.

query(string $sql): mixed

Weitere Hilfsfunktionen wie use(), setTable(), enableBackups(), enableTrashMode() usw. findest du in den entsprechenden Abschnitten der Dokumentation.

Über den Autor

Mein Name ist Johannes Teitge, ich bin 58 Jahre alt und habe Jahrzehnte als Informatiker gearbeitet – in unterschiedlichsten Projekten, mit Herzblut für sauberen Code, pragmatische Lösungen und flexible Tools.

JsonSQL ist ein rein privat entwickeltes Projekt, entstanden aus der Idee, strukturierte Daten einfach und ohne klassische Datenbank handhabbar zu machen – ideal für kleine Web-Apps, Admin-Tools, Offline-Anwendungen oder embedded Systeme.

Lizenz & Verwendung

Die Nutzung erfolgt unter einer erweiterten MIT-Lizenz – mit einer einzigen Bedingung:

Mein Name als Urheber (Johannes Teitge) muss im Quelltext oder in der Dokumentation erhalten bleiben.

Unterstützen mit Kaffee?

Ich bin leidenschaftlicher Hobby-Barista – wer mir eine Freude machen will, darf mir gern ein Päckchen richtig guter Kaffeebohnen schicken ☕️😊

Feedback, Bugs & Grüße

Ich freue mich über jede Art von Rückmeldung, Verbesserungsvorschläge, Bugmeldungen oder nette Worte. Einfach eine Mail an:

johannes@teitge.de

Danke fürs Lesen – und viel Freude beim Nutzen und Weiterentwickeln von JsonSQL! 🛠️📂