dbxDB Klassenreferenz

Zentrale Datenbank-, DD-, CRUD-, Rechte- und Validierungsschicht von dbxapp. Mehr ...

Öffentliche Methoden
	__construct ()
	Initialisiert das DBX-Datenbankobjekt mit Standardwerten und lädt den zentralen Validator.
	__destruct ()
	Gibt interne Referenzen beim Zerstören des Objekts frei.
	is_sqlite_database_locked ($database_path)
	Prüft, ob eine SQLite-Datenbank aktuell gelockt ist.
	db_connect ($server, $db_type, $db_host, $db_name='', $db_user='', $db_pass='', $db_port='')
	Stellt eine Verbindung zu einer Datenbank her und speichert sie in $this->db[$server].
	get_dd_table ($dd, $rec=0)
	Gibt den Tabellennamen oder die komplette Table-Definition einer DD zurück.
	get_dd_autosync ($dd, $rec=0)
	Gibt das Autosync-Flag einer DD zurück.
	get_new_record (string $dd, array $field_values=[])
	Erstellt einen neuen Datensatz mit Standardwerten.
	insert ($dd, $field_values, $verify_access=1, $verify_fields=1, $verify_values=1, $trace=1)
	Fügt einen neuen Datensatz in die Datenbank ein.
	update ($dd, $field_values, $where, $verify_access=1, $verify_fields=1, $verify_values=1, $trace=1)
	Führt ein UPDATE-Statement auf einer Tabelle aus.
	save ($dd, $field_values, $where, $verify_access=1, $verify_fields=1, $verify_values=1, $trace=1)
	Speichert einen Datensatz mit UPSERT-ähnlichem Verhalten.
	delete ($dd, $where, $verify_access=1, $trace=1)
	Löscht Datensätze aus einer Tabelle anhand einer WHERE-Bedingung.
	empty ($dd)
	Leert eine Tabelle anhand ihrer DD.
	get_table_exist ($dd, $dbtab='', bool $report_missing=true)
	Prüft, ob eine Tabelle existiert.
	get_convert_array ($field, $array, $convert='auto')
	Konvertiert Array-Werte automatisch in String-/Serialisierungsformate.
	check_access (string $mode, string $dd)
	Prüft die Zugriffsrechte für eine Operation auf einer DD.
	check_values ($dd, $field_values, $verify_values=1)
	Überprüft und validiert übergebene Feldwerte anhand der DD-Regeln.
	check_fields ($dd, $field_values)
	Filtert ungültige Felder aus einem Eingabearray heraus.
	empty_record (string $dd)
	Erstellt einen leeren Datensatz mit Standardwerten basierend auf der DD.
	check_where ($where, $owner=0, $dd='')

Öffentliche Attribute
	$db = array()
	$pdo = null
	$_connected = 0
	$_server = ''
	$_dbtype = ''
	$_insert_id = 0
	$_update_count = 0
	$_delete_count = 0
	$_insert_count = 0
	$_db_message = ''
	$o_validator = null
	$_validation_error = 0
	$_validation_warning = 0
	$_validation_error_flds = array()
	$_validation_warning_flds = array()
	$_validator_rules = 0
	$_validator_type = 1
	$_validator_error = 0
	$_validator_mode = 'clean'
	$_fld_id
	$_error = ''
	$_query = ''
	$_report_error = 1
	1 = DB-Fehler automatisch in dbxSysMsg schreiben, 0 = nicht
	$_error_status = ''
	db|sql|access
	$_error_text = ''
int	$_connect_timeout = 3
	Maximale Wartezeit für einen DB-Verbindungsaufbau in Sekunden.

Ausführliche Beschreibung

Zentrale Datenbank-, DD-, CRUD-, Rechte- und Validierungsschicht von dbxapp.

Zentrale Datenbank- und DD-Systemklasse von DBX.

Zweck

Diese Klasse ist die zentrale Infrastruktur für:

• Datenbankverbindungen
• DD-Auflösung und DD-Cache
• Tabellen-/Feld-/Server-Metadaten
• CRUD-Operationen
• Access-Prüfung
• Feld-/Wert-Validierung
• Trace-/Audit-Schreibung
• Hilfsfunktionen für Report/Grid/Tabellen-Metadaten

Architekturprinzip

• DDs bleiben die fachliche Quelle für Tabellen, Felder, Rechte und Defaults.
• DB-Verbindungen werden lazy aufgebaut und wiederverwendet.
• Bestehende DBX-Mechaniken werden genutzt, nicht parallel neu erfunden.
• Änderungen in dieser Klasse müssen minimal, stabil und systemkonform bleiben.

DD-Konzept

DD-Dateien liegen unter: dbx/modules/{modul}/dd/*.dd.php

Eine DD definiert typischerweise:

• $table
• optional $fields
• optional $indexes

Unterstützte DD-Aufrufe

• meinDD
• meinModul|meinDD
• modul|meinDD (modul = Platzhalter für aktives Modul)

Beispiel

$db = dbx()->get_system_obj('dbxDB');
 
$rows = $db->select('kunden', "status='aktiv'");
$rec  = $db->select1('crm|adresse', 15);
 
$ok = $db->insert('kunden', [
    'name'  => 'Muster GmbH',
    'city'  => 'Darmstadt'
]);
$id = $ok > 0 ? $db->get_insert_id() : 0;
 
$ok = $db->update('kunden', [
    'city' => 'Frankfurt'
], 15);
 
$ok = $db->save('kunden', [
    'name' => 'Test'
], 15);

Beschreibung der Konstruktoren und Destruktoren

__construct()

dbxDB::__construct

(

)

Initialisiert das DBX-Datenbankobjekt mit Standardwerten und lädt den zentralen Validator.

__destruct()

dbxDB::__destruct

(

)

Gibt interne Referenzen beim Zerstören des Objekts frei.

Dokumentation der Elementfunktionen

check_access()

dbxDB::check_access	(	string	$mode,
		string	$dd )

Prüft die Zugriffsrechte für eine Operation auf einer DD.

Zugriffssystem

• 0 = kein Zugriff
• 1 = voller Zugriff
• 2 = Owner-Zugriff

Verwendete DD-Rechte

• insert → create
• update → update
• delete → delete
• select → read

Parameter

string	$mode	Operation: insert|update|delete|select
string	$dd	Datenbeschreibung

Rückgabe

int 0|1|2

Benutzt $table und get_dd_table().

Wird benutzt von delete(), insert(), save() und update().

check_fields()

dbxDB::check_fields	(		$dd,
			$field_values )

Filtert ungültige Felder aus einem Eingabearray heraus.

Es werden nur Felder übernommen, die in der DD definiert sind. Bei ungültiger oder leerer DD-Feldliste wird defensiv ein leeres Ergebnis zurückgegeben.

Parameter

string	$dd	Datenstrukturdefinition
array	$field_values	Eingabewerte

Rückgabe

array Gefilterte Feldwerte

Benutzt $field und empty().

Wird benutzt von insert() und update().

check_values()

dbxDB::check_values	(		$dd,
			$field_values,
			$verify_values = 1 )

Überprüft und validiert übergebene Feldwerte anhand der DD-Regeln.

Die bestehende DBX-Logik bleibt erhalten:

• optionale Regelprüfung
• optionale Typ-/Längenprüfung
• Fehler/Warnungen je nach Validator-Modus
• optionales Cleanen oder Unsetzen ungültiger Werte

Stabilitätsverbesserungen

• fehlende DD-Keys werden defensiv behandelt
• 0 / '0' bleiben valide prüfbare Werte
• Array-Werte werden weiterhin vor Typprüfung konvertiert

Parameter

string	$dd	Datenstrukturdefinition
array	$field_values	Zu überprüfende Feldwerte
int	$verify_values	Gibt an, ob Werte überprüft werden sollen

Rückgabe

array Validierte und ggf. bereinigte Feldwerte

Benutzt $field, $fields und get_convert_array().

Wird benutzt von insert() und update().

check_where()

dbxDB::check_where	(		$where,
			$owner = 0,
			$dd = '' )

Wird benutzt von save().

db_connect()

dbxDB::db_connect	(		$server,
			$db_type,
			$db_host,
			$db_name = '',
			$db_user = '',
			$db_pass = '',
			$db_port = '' )

Stellt eine Verbindung zu einer Datenbank her und speichert sie in $this->db[$server].

Unterstützte Datenbanktypen

sqlite, mysql, pgsql, sqlsrv, oci, firebird, cubrid, dblib, ibm, informix, odbc.

Stabilitätsregel

Bei unbekanntem Datenbanktyp wird sauber ein Fehler gesetzt und protokolliert, ohne unkontrolliert nach außen abzubrechen.

Parameter

string	$server	Name des Servers (Schlüssel im $this->db-Array)
string	$db_type	Typ der Datenbank
string	$db_host	Hostname oder Datei für SQLite
string	$db_name	Name der Datenbank
string	$db_user	Benutzername
string	$db_pass	Passwort
string	$db_port	Port

Rückgabe

int 1 bei Erfolg, 0 bei Fehler

delete()

dbxDB::delete	(		$dd,
			$where,
			$verify_access = 1,
			$trace = 1 )

Löscht Datensätze aus einer Tabelle anhand einer WHERE-Bedingung.

Ablauf

• Access prüfen
• WHERE normalisieren
• optional Before-Rows für Trace lesen
• DELETE ausführen
• optional Trace mit gelöschten Vorwerten schreiben

Parameter

string	$dd	Datenbeschreibung
mixed	$where	WHERE-Bedingung
int	$verify_access	Zugriff prüfen
int	$trace	Trace aktivieren

Rückgabe

int 1|0|-1|-2

Benutzt $count, $id, $row, check_access(), get_dd_table() und insert().

empty()

dbxDB::empty

(

$dd

)

Leert eine Tabelle anhand ihrer DD.

Je nach DB-Typ werden passende Statements verwendet.

Parameter

string

$dd

Datenbeschreibung

Rückgabe

int 1 bei Erfolg, 0 bei Fehler

Benutzt get_dd_table().

Wird benutzt von check_fields(), insert() und update().

empty_record()

dbxDB::empty_record

(

string

$dd

)

Erstellt einen leeren Datensatz mit Standardwerten basierend auf der DD.

Beispiel

$empty = $this->empty_record('kunden');
// Rückgabe: [ [ 'id' => 0, 'name' => '', ... ] ]

Parameter

string

$dd

Datenstrukturdefinition

Rückgabe

array Leerer Datensatz als Array in Array-Hülle

Wird benutzt von get_new_record().

get_convert_array()

dbxDB::get_convert_array	(		$field,
			$array,
			$convert = 'auto' )

Konvertiert Array-Werte automatisch in String-/Serialisierungsformate.

Modi

• auto
• serial
• list

Beispiel

$value = $this->get_convert_array('tags', ['a', 'b'], 'auto');
// Ergebnis: "a,b"

Parameter

string	$field	Feldname
mixed	$array	Wert oder Array
string	$convert	Modus: auto|serial|list

Rückgabe

mixed Konvertierter Wert

Benutzt $field.

Wird benutzt von check_values() und update().

get_dd_autosync()

dbxDB::get_dd_autosync	(		$dd,
			$rec = 0 )

Gibt das Autosync-Flag einer DD zurück.

• rec = 0 → nur der Autosync-Wert
• rec = 1 → kompletter Autosync-Bereich, falls vorhanden

Parameter

string	$dd	Name der Datenbeschreibung
int	$rec	0 = Wert, 1 = kompletter Datensatzbereich

Rückgabe

mixed Autosync-Wert oder 0

get_dd_table()

dbxDB::get_dd_table	(		$dd,
			$rec = 0 )

Gibt den Tabellennamen oder die komplette Table-Definition einer DD zurück.

• rec = 0 → nur Tabellenname
• rec = 1 → komplette Table-Definition

Bei fehlender oder ungültiger DD wird 0 zurückgegeben.

Parameter

string	$dd	Name der Datenbeschreibung
int	$rec	0 = nur Tabellenname, 1 = komplette Table-Definition

Rückgabe

mixed Tabellenname, Table-Definition oder 0

Wird benutzt von check_access(), delete(), empty(), get_table_exist(), insert() und update().

get_new_record()

dbxDB::get_new_record	(	string	$dd,
		array	$field_values = [] )

Erstellt einen neuen Datensatz mit Standardwerten.

Falls field_values nicht angegeben ist, wird der leere Datensatz des DD-Objekts verwendet. Nicht gesetzte Felder erhalten Standardwerte.

Parameter

string	$dd	Datenbank-Objekt
array	$field_values	Initialwerte

Rückgabe

array Neuer Datensatz mit Standardwerten

Benutzt $field und empty_record().

Wird benutzt von insert().

get_table_exist()

dbxDB::get_table_exist	(		$dd,
			$dbtab = '',
		bool	$report_missing = true )

Prüft, ob eine Tabelle existiert.

• Bei DD-Aufruf werden Tabelle und Server aus der DD ermittelt.
• Bei explizitem Tabellenname in $dbtab wird $dd als Servername behandelt.
• Fehlende Datenbanken werden als SysMsg mit klarem why gemeldet, nicht als SQL-Query-Fehler.

Parameter

string	$dd	DD-Name oder Servername
string	$dbtab	Optional expliziter Tabellenname
bool	$report_missing	Fehlende DB oder Tabelle als Systemmeldung protokollieren

Rückgabe

int 1 wenn Tabelle existiert, sonst 0

Benutzt $db_file und get_dd_table().

insert()

dbxDB::insert	(		$dd,
			$field_values,
			$verify_access = 1,
			$verify_fields = 1,
			$verify_values = 1,
			$trace = 1 )

Fügt einen neuen Datensatz in die Datenbank ein.

Ablauf

1. Optional: Setzt System-/Audit-Felder
2. Ergänzt Standardwerte
3. Prüft Zugriff
4. Validiert Felder und Werte
5. Führt INSERT aus
6. Optional: Schreibt Trace-Eintrag

Bei retry-fähigen Lock-/Deadlock-Fehlern wird außerhalb aktiver Transaktionen mehrfach erneut versucht.

Parameter

string	$dd	Datenbank-Definition
array	$field_values	Zu speichernde Werte
int	$verify_access	Zugriff prüfen
int	$verify_fields	Felder prüfen
int	$verify_values	Werte prüfen
int	$trace	Trace aktivieren

Beispiel:

$ok = $db->insert('dbxUser', [
   'name' => 'Admin',
   'email' => 'admin@example.test'
]);
$rid = $ok > 0 ? $db->get_insert_id() : 0;

Rückgabe

int 1 = Erfolg (Insert-ID separat über get_insert_id()), 0 = Validierungsfehler, -1 = Zugriffsfehler, -2 = DB-Fehler

Benutzt $fields, $id, check_access(), check_fields(), check_values(), empty(), get_dd_table(), get_new_record() und insert().

Wird benutzt von delete(), insert(), save() und update().

is_sqlite_database_locked()

dbxDB::is_sqlite_database_locked

(

$database_path

)

Prüft, ob eine SQLite-Datenbank aktuell gelockt ist.

Zweck

SQLite sperrt bei Schreibzugriffen die Datenbank bzw. Teile davon. Diese Funktion versucht defensiv, eine Transaktion zu starten. Scheitert das, wird die DB als gelockt betrachtet.

Verhalten

• Öffnet temporäre Verbindung
• setzt PRAGMA locking_mode=NORMAL
• versucht beginTransaction()
• Rollback nur wenn tatsächlich eine Transaktion aktiv ist

Parameter

string

$database_path

Vollständiger Pfad zur SQLite-Datei

Rückgabe

int 1 = Datenbank ist gelockt, 0 = frei

Benutzt $pdo.

save()

dbxDB::save	(		$dd,
			$field_values,
			$where,
			$verify_access = 1,
			$verify_fields = 1,
			$verify_values = 1,
			$trace = 1 )

Speichert einen Datensatz mit UPSERT-ähnlichem Verhalten.

Ablauf

• wenn WHERE vorhanden: zuerst UPDATE
• UPDATE = 1 → Erfolg
• UPDATE = -1/-2 → direkt zurück
• UPDATE = 0 → prüfen, ob Datensatz bereits existiert
• INSERT nur dann, wenn anhand der WHERE-Bedingung kein Datensatz existiert

Zweck

Verhindert das frühere Fehlverhalten:

• UPDATE = 0 bedeutete früher automatisch INSERT
• das konnte bei unveränderten Datensätzen zu Doppel-Insert führen

Parameter

string	$dd	Datenbankdefinition
array	$field_values	Zu speichernde Werte
string	$where	WHERE-Bedingung
int	$verify_access	Zugriff prüfen
int	$verify_fields	Felder prüfen
int	$verify_values	Werte prüfen
int	$trace	Trace aktivieren

Beispiel:

$ok = $db->save('dbxConfig', ['value' => 'blue'], "name='default_color'");

Rückgabe

int 1 = Erfolg (bei Insert-Fallback: Insert-ID separat über get_insert_id()), 0 = Validierungsfehler/nichts geändert, -1 = Zugriffsfehler, -2 = DB-Fehler

Benutzt check_access(), check_where(), insert() und update().

update()

dbxDB::update	(		$dd,
			$field_values,
			$where,
			$verify_access = 1,
			$verify_fields = 1,
			$verify_values = 1,
			$trace = 1 )

Führt ein UPDATE-Statement auf einer Tabelle aus.

Bei retry-fähigen Lock-/Deadlock-Fehlern wird außerhalb aktiver Transaktionen mehrfach erneut versucht.

Ablauf

• Access prüfen
• WHERE normalisieren
• optional Before-Rows für Trace laden
• Felder/Werte prüfen
• UPDATE ausführen
• Delta-basiert Trace schreiben

Parameter

string	$dd	Datenbankdefinition oder Tabellenname
array	$field_values	Zu aktualisierende Werte
string	$where	WHERE-Bedingung
int	$verify_access	Zugriff prüfen
int	$verify_fields	Felder prüfen
int	$verify_values	Werte prüfen
int	$trace	Trace aktivieren

Beispiel:

$ok = $db->update('dbxUser', ['active' => 1], 15);

Rückgabe

int 1 = geändert, 0 = nichts geändert, -1 = Zugriff, -2 = DB-Fehler

Benutzt $count, $field, $id, $row, check_access(), check_fields(), check_values(), empty(), get_convert_array(), get_dd_table() und insert().

Wird benutzt von save().

Dokumentation der Datenelemente

$_connect_timeout

int dbxDB::$_connect_timeout = 3

Maximale Wartezeit für einen DB-Verbindungsaufbau in Sekunden.

$_connected

dbxDB::$_connected = 0

$_db_message

dbxDB::$_db_message = ''

$_dbtype

dbxDB::$_dbtype = ''

$_delete_count

dbxDB::$_delete_count = 0

$_error

dbxDB::$_error = ''

$_error_status

dbxDB::$_error_status = ''

db|sql|access

$_error_text

dbxDB::$_error_text = ''

$_fld_id

dbxDB::$_fld_id

$_insert_count

dbxDB::$_insert_count = 0

$_insert_id

dbxDB::$_insert_id = 0

$_query

dbxDB::$_query = ''

$_report_error

dbxDB::$_report_error = 1

1 = DB-Fehler automatisch in dbxSysMsg schreiben, 0 = nicht

$_server

dbxDB::$_server = ''

$_update_count

dbxDB::$_update_count = 0

$_validation_error

dbxDB::$_validation_error = 0

$_validation_error_flds

dbxDB::$_validation_error_flds = array()

$_validation_warning

dbxDB::$_validation_warning = 0

$_validation_warning_flds

dbxDB::$_validation_warning_flds = array()

$_validator_error

dbxDB::$_validator_error = 0

$_validator_mode

dbxDB::$_validator_mode = 'clean'

$_validator_rules

dbxDB::$_validator_rules = 0

$_validator_type

dbxDB::$_validator_type = 1

$db

dbxDB::$db = array()

$o_validator

dbxDB::$o_validator = null

$pdo

dbxDB::$pdo = null

Wird benutzt von is_sqlite_database_locked().

---

Die Dokumentation für diese Klasse wurde erzeugt aufgrund der Datei:

• dbxapp/dbx/include/dbxDB.class.php