Dokumentation des DDDBLs

Übersicht

Ein Beispiel

Bevor die Spezifikation hilfreich ist, muß das Grundprinzip verstanden worden sein. Zur Erleichterung des Einlebens sei auf das DDDBL-Beispiel verwiesen.

Datenbankverbindung

Syntax

    [Verbindungs-Alias]
    CONNECTION = "DNS (siehe PHP-Handbuch: PDO)"
    USER = "Benutzername"
    PASS = "Passwort"
    BIND-DATA-TYPE = true
    
Der Verbindungs-Alias kann ein beliebiger Name bestehend aus allen alphanumerischen Zeichen, inklusive "-" und "_", sein.

CONNECTION ist der DNS zur Datenbank. Näheres erfahren sie im PDO Handbuch. Der DNS wird ohne weitere Prüfung oder Verarbeitung an PDO weitergereicht.

USER ist der Benutzername, mit dem Sie sich bei der Datenbank anmelden möchten.

PASS ist das Passwort zum Benutzernamen, mit dem Sie sich bei der Datenbank anmelden möchten.

BIND-DATA-TYPE ist ein optionaler Parameter. Datenbanken unterstützen eine Reihe von Datentypen, welche zum Teil auch in der Kommunikation mit der Applikation berücksichtigt werden können oder müssen. Es ist nun möglich der Datenbank die Datentypen NULL, Boolean, Integer und String explizit zu übermitteln. Ein übergebener Boolscher-Wert wird so in der Datenbank - falls unterstützt - auch als Boolean behandelt.


Schlägt ein Verbindungsaufbau fehl, gibt es keine Exception! Zum prüfen, ob eine Verbindung besteht, verwenden Sie bitte:
    \DDDBL\isConnected();
    
Es kommt immer wieder vor, dass eine direkte Arbeit mit der Datenbank notwendig ist. Sei es um Transaktionen zu managen oder um zu prüfen, ob die Datenbankverbindung überhaupt besteht. Dies ist über das PDO-Objekt möglich, welches über die Funktion \DDDBL\getDB gezogen wird:
    $objPDO = \DDDBL\getDB();
    

Definitions-Beispiel

    [STATISTIC-DB]
    CONNECTION = "mysql:host=localhost;dbname=statistics"
    USER = db_statistic
    PASS = w9vw3S%

SQL-Definition

    [Abfragen-Alias]
    QUERY = "SQL-Query"
    HANDLER = DER_HANDLER optionale Parameter - siehe Handler
    
Der Abfragen Alias kann ein beliebiger Name bestehend aus allen alphanumerischen Zeichen, inklusive "-" und "_", sein. Über diesen Namen wird die Abfrage innerhalb des Programmcodes aufgerufen und deren Durchführung veranlaßt.

QUERY enthält die Datenbankabfrage. Die Abfrage muß von Anführungszeichen umfaßt sein, es wird kein abschließendes Semikolon benötigt.
Der Query kann sich über mehrere Zeilen erstrecken und durch Whitesspaces beliebig formatiert werden.
Es sind keine Anführungszeichen innerhalb des Querys erlaubt.

Der HANDLER kann optional gesetzt werden.
Gibt eine Datenbankabfrage einen Wert zurück, kann der Handler das Ergebnis automatisch bearbeiten.
Ist kein Handler gesetzt, wird das Ergebnis direkt durch PDO geliefert. Dies kann true, false oder ein PDOStatement-Objekt sein.

Handler

SINGLE_VALUE

Syntax: SINGLE_VALUE [spalte]
Rückgabewert: Ein skalarer Wert

Der Handler SINGLE_VALUE gibt einen einzelnen skalaren Wert zurück.
Stehen mehrere Datensätze oder Spalten zur Verfügung, wird jeweils der erste verwendet.
Steht kein Datensatz zur Verfügung, wird null zurückgegeben.

Beispiele

    [SINGLE-VALUE-BEISPIEL]
    QUERY = "SELECT 1"
    HANDLER = SINGLE_VALUE
    

SINGLE

Syntax: SINGLE [spalte [spalte [..]]]
Rückgabewert: eindimensionaler, assosiativer Array

Der Handler SINGLE gibt einen eindimensionalen, assosiativen Array zurück.
Die Keys sind gemäß der Spalten benannt.
Bei einer leeren Ergebnismenge wird ein leerer Array zurückgegeben.

Beispiel

    [SINGLE-BEISPIEL]
    QUERY = "SELECT vorname, name FROM mitarbeiter WHERE mitarbeiter_nr = 1"
    HANDLER = SINGLE
    
    Ergebnis:
    array(
      'vorname' => 'Torsten'
      'name'    => 'Zühlsdorff'
    )
    

MULTI

Syntax: MULTI [spalte [spalte [..]]]
Rückgabewert: zweidimensionaler, assosiativer Array

Der Handler MULTI gibt einen zweidimensionalen, assosiativen Array zurück.
Die Keys sind gemäß der Spalten benannt.
Bei einer leeren Ergebnismenge wird ein leerer Array zurückgegeben.

Beispiel

    [MULTI-BEISPIEL]
    QUERY = "SELECT vorname, name FROM mitarbeiter"
    HANDLER = MULTI
    
    Ergebnis:
    array( 
      array(
        'vorname' => 'Torsten'
        'name'    => 'Zühlsdorff'
      ),
      array(
        'vorname' => 'Max'
        'name'    => 'Mustermann'
      )
    )
    

LIST

Syntax: LIST [spalte]
Rückgabewert: eindimensionaler Array

Der Handler LIST gibt einen eindimensionalen Array zurück, der eine Liste von skalaren Werten representiert.
Eine leere Ergebnismenge resultiert in einem leeren Array.

Beispiel

    [LIST-BEISPIEL]
    QUERY = "SELECT mitarbeiter_nr FROM mitarbeiter"
    HANDLER = LIST
    
    Ergebnis:
    array( 
      0 => 7,
      1 => 9,
      2 => 17
    )
    

NOT_NULL

Syntax: NOT_NULL
Rückgabewert: true, falls die Ergebnismenge nicht leer ist, false falls sie leer ist

Der Handler NOT_NULL prüft, ob eine Ergebnismenge nicht leer ist. Falls dem so ist, wird true zurückgegeben, anderfalls false. Ein typisches Verwendungsbeispiel ist die Prüfung, ob ein Eintrag existiert - z.B. ob ein Mitarbeiter existiert.