De:DBAPI

From MODx Wiki

Die DBAPI stellt die grundlegenden Funktionen zur Kommunikation mit der Datenbank dar. Sie ist eine Abstraktionsebene - sollte MODx also einmal weiter Datenbanksysteme als MySQL benutzen ist die Benutzer der DBAPI einem direkten Benutzen der PHP-Funktionen vorzuziehen, um die Kompatibilität zu wahren. Dieser Artikel bietet eine grundlegende Übersicht über die Funktionen und Beispiele für den Einsatz.

Anm. Es ist hilfreich die Schriftgröße deines Browser eins größer zu stellen (strg + (Windows),⌘ + (Mac))

Select

Befehl

Wie der Name schon sagt ist das ein einfacher Wrapper für eine SELECT-Abfrage:

select(string felder,string tabelle[, string bedingung[,string sortierung[,string limit]]])

Erklärung

Die erzeugte Abfrage entspricht also je nach Angaben diesem Schema:

SELECT felder FROM tabelle WHERE bedingung ORDER BY sortierung LIMIT limit

Der Query wird dabei auch gleich durchgeführt.

Rückgabewerte

Rückgabewert (Erfolg): Resource des Queries

Rückgabewert (Fehler): FALSE

Beispiel

Einfach

$modx->db->select('*','freunde');

Zeigt alle meine Freunde. Die erzeugte Abfrage entspricht also

SELECT * FROM freunde

Vollständig

$heute = $modx->db->prepareDate(time(),'DATE');
$modx->db->select('*','geburtstage','verhaeltnis = familie AND datum >= ' . $heute,'datum ASC','0,5');

Diese Abfrage zeigt die nächsten 10 Geburtstage in meiner Familie, ausgehend von Heute. Die erzeugte Abfrage entspricht also:

SELECT * FROM geburtstage WHERE verhaeltnis = familie AND datum >= 2006-10-24  ORDER BY datum ASC LIMIT 0,5

Record Count

Befehl

Dieser Befehl entspricht mysql_num_rows von PHP und gibt die Anzahl der Werte die eine Select-Abfrage liefern würde zurück.

getRecordCount(resource query);

Rückgabewerte

Erfolg: Anzahl der Einträge als Ganzzahl (Int)

Beispiel

$query = $modx->db->select('*','freunde');
$anzahlMeinerFreunde = $modx->db->getRecordCount($query);

Dieser Befehl sagt mir wie viele Freunde ich habe.

Get a single Row

Befehl

Jetzt wird es interessant: Die Select-Abfrage von oben gibt ja erstmal nur eine Resource zurück. Um nun aber wirklichen ein Ergebnis zu erhalten benutzen wir diesen Befehl. Er ist ein Wrapper für mysql_fetch_assoc,mysql_fetch_row und mysql_fetch_array von PHP.

getRow(resource query[,string modus])

Der Modus gibt den Typ des zurückgegebenen Arrays an. Möglich sind folgende Werte:

Rückgabewerte

Erfolg: Ein Array den Werten einer Tabellenzeile Fehler oder keine Werte mehr in der Tabelle: FALSE

Beispiel

Einfach

$query = $modx->db->select('*','freunde');
$daten = $modx->db->getRow($query);

Praxisnah

Das obige Beispiel ist nützlich wenn nur eine Zeile in der Tabelle vorhanden ist. Wenn man, wie in den meisten Fällen, mehrere Zeilen holen will kann man beispielsweise folgende Methode einsetzen:

$query =  $modx->db->select('*','geburtstage','verhaeltnis = familie AND datum >= ' . $heute,'datum ASC','0,5');
while($daten = $modx->db->getRow($query)) {
echo	"Mein Verwandter " . $daten["name"] . "hat am " . $daten["datum"] . "Geburtstag.\n";
}

Als Rückgabe würde ich nun folgendes erhalten:

Mein Verwandter Hans hat am 2006-10-28 Geburtstag.
Mein Verwandter Anne hat am 2006-11-09 Geburtstag.
...

Zwar noch nicht ganz praxistauglich, aber es erklärt das Prinzip.

Alte Methode

In manchen Snippets wird noch diese oder eine ähnliche Methode zu finden sein. Sie gilt als veraltet und sollte nicht mehr verwendet werden.

$result = $modx->dbQuery("SELECT * FROM foobar");
for($i=0;$i<@$modx->recordCount($result);$i++)  {
  array_push($ergebnisseArray,@$modx->fetchRow($result));
}

Die in diesem Beispiel eingesetzten Funktionen benutzen nicht die DBAPI (Intern sind es nurnoch Wrapper für die entsprechenden Funktionen der DBAPI)

Get Column Names

Befehl

Gibt die Namen der Spalten einer Tabelle zurück

getColumnNames(resource query);

Ansatt eine resource kann auch eine SQL-Abfrage angegeben werden. Diese wird dann zu erst durchgeführt.

Beispiel

$spaltenNamenQuery = $modx->db->select('*','geburtstage');
$spaltenNamenArray = $modx->db->getColumnNames($spaltenNamenQuery);

Get Entries in Column

Befehl

Dieser Befehl gibt alle Werte in einer Spalte zurück

getColumn(string spaltenname,resource query);

Genau wie bei getColumnNames kann hier anstatt einer resource auch eine SQL-Abfrage angegeben werden.

Beispiel

$query = $modx->db->select('*','geburtstage');
$tageMitGeburtstagenArray = $modx->db->getColumn('datum',$query);

Jetzt habe ich einen Array in dem alle Tage aufgelistet sind, an denen jemand aus meiner Geburtstagsliste Geburtstag hat.

Get First Field

Befehl

Stellt man sich die Datenbanktabelle wie die Matrix einer Tabellenkalkulation vor so erhält man mit diesem Befehl das Feld A1

getValue(resource query);

Beispiel

$query = $modx->db->select('*','foobar');
$ersterWert = $modx->db->getValue($query);

Stellt man sich also folgende Tabelle vor

    +-----+-----+-----+
    |  A  |  B  |  C  |
+---+-----+-----+-----+
| 1 | 42  |  1  |  2  |
+---+-----+-----+-----+
| 2 | 5   |  7  |  3  |
+---+-----+-----+-----+

So würde das Ergebnis der Abfrage 42 sein. Der Befehl ist ein Wrapper für getRow, kann also auch in einer Schleife benutzt werden.

Get XML

Befehl

Dieser Befehl gibt die Werte einer Abfrage im XML-Schema zurück

getXML(resource query);

Beispiel

$query = $modx->db->query('*','freunde');
$xml = $modx->db->getXML($query);

$xml enthält nun einen String der etwa so aussieht:

<xml>
  <recordset>
    <item>
      <name>Hans Müller</name>
      <ort>Buxdehude</ort>
    </item>
    <item>
     <name>Max Mustermann</name>
     <ort>Musterstadt</ort>
    </item>
  </recordset>
</xml>

Damit sollte das Prinzip klar sein: Jede Zeile der Tabelle wird als <item> ausgegeben, die einzelnen Spalten erhalten ihren eigenen Tag nach ihrem Namen.

Get Table Metadata

Befehl

Gibt weitere Informationen zu den einzelnen Spalten einer Tabelle zurück.

getTableMetaData(string tabellenname);

Das Ergebnis ist ein multidimensionaler Array, die Schlüsselwerte des obersten Arrays sind die Namen der Spalten.

Prepare a Date for MySQL

Befehl

Diese Funktion wandelt einen UNIX-Timestamp in ein Datum um, das in Feldern mit einem Datumstyp eingesetzt werden kann.

prepareDate(int timestamp[, string datumstyp])

Datumstyp kann einer der folgenden Werte sein:

Eine Erklärung der Variablen gibt es in der PHP-Dokumentation zu date().

Beispiel

$timestamp = 1161711995; //Tue, 24 Oct 2006 19:46:35
$datumFuerMysql = $modx->db->prepareDate($timestamp);

Als Rückgabewert erhalte ich nun

2006-10-24 19:46:35

Get as HTML Grid

Befehl

Diese Funktion gibt eine HTML-Tabelle aus

getHTMLGrid(resource query,array parameter);

parameter ist ein assoziativer Array und sollte folgende Schlüssel enthalten

Get as Array

Befehl

Gibt alle Werte einer Abfrage als multidimensionalen Array zurück

makeArray(resource query);

Beispiel

Will ich z.b. alle meine Freunde aus einer Tabelle holen kann ich mir das ganz einfach machen:

$query = $modx->db->select('*','freunde');
$alleFreundeArray = $modx->db->makeArray($query);

Als Ergebnis habe ich jetzt einen Array nach folgenden Schema:

Array
(
    [0] => Array
        (
         [name] => Hans Müller
         [ort] => Buxdehude
        )
    [1] => Array
        (
         [name] => Max Mustermann
         [ort] => Musterstadt
        )
)

Delete

Befehl

Dieser Befehl ist ein Wrapper für eine DELETE-Abfrage

delete(string tabelle[, string bedingung[, string felder]]);

Die Abfrage entspricht

DELETE felder FROM tabelle WHERE bedingung

Diese Abfrage wird auch gleich durchgeführt.

Beispiel

Hans ist umgezogen und ich habe keinen Kontakt mehr zu ihm, also kann ich ihn als Freund löschen.

$modx->db->delete('freunde','name = "Hans Müller"');

Die Abfrage entspricht:

DELETE FROM freunde WHERE name = "Hans Müller"

Update

Befehl

Dieser Befehl ist ein Wrapper für die Update-Abfrage um Datensätze zu verändern.

update(array felder,string tabelle[,string bedingung])

felder ist ein assoziativer Array bei dem die Schlüssel dem Spaltennamen entsprechen. Der Wert kann aber auch als String übergeben werden (Spaltenname = 'Wert', Spalte2 = 'Wert2') Der Befehl entspricht folgender SQL-Abfrage

UPDATE tabelle SET felder WHERE bedingung

Beispiel

Mein anderer Freund ist jetzt auch noch umgezogen. Zum Glück nicht so weit weg, darum muss ich nur seine Adresse ändern:

$werteZumAktualisierenArray = array('ort' => 'Musterdorf');
$modx->db->update($werteZumAktualisierenArray,'freunde','name = "Max Mustermann"');

Insert

Befehl

Dieser Befehl ist ein Wrapper für den INSERT-Befehl

insert(array felder,string inTabelle[, string vonFelder[, string vonTabelle[, string bedingung[, string limit]]]]);

Der Befehl akzeptiert es neue Werte einzufügen oder sie aus einer anderen Tabelle zu holen. Siehe dazu die Beispiele.

Beispiele

Einfaches Beispiel

Ich hab einen neuen Freund gefunden!

$felderArray = array('name' => 'Anna Maier','ort' => 'Dorf Im Wald');
$modx->db->insert($felderArray,'freunde');

Dieser Befehl entspricht folgender Abfrage:

INSTERT INTO freunde (name, ort) VALUES('Anna Maier','Dorf Im Wald');

Komplexes Beispiel

Bei dem komplexen Beispiel wird ein INSERT mit einem SELECT gekoppelt. Mein ehemaliger Freund Hans ist wieder zurückgezogen. Damals hatte ich in die Tabelle altefreunde geschoben. Jetzt kann ich ihn wieder zurückholen.

$schluesselArray = array('name' => ,'ort' => );
$modx->db->insert($schluesselArray,'freunde','*','altefreunde','name = "Hans Müller");

Die erzeugte Abfrage entspricht

INSERT INTO freunde (name,ort) SELECT * FROM altefreunde WHERE name = "Hans Müller"

Last Insert Id

Befehl

Dieser Befehl entspricht mysql_insert_id von PHP.

getInsertId([resource Datenbankverbindung]);

In der Regel wird der Befehl ohne Parameter aufgerufen.

Beispiel

Vorhin habe ich ja Anna als neuen Freund hinzugefügt. Welche ID hat sie denn nun in der Datenbank?

$felderArray = array('name' => 'Anna Maier','ort' => 'Dorf Im Wald');
$modx->db->insert($felderArray,'freunde');
$id = $modx->db->getInsertId();

Query

Befehl

Dieser Befehl ist ein Wrapper für mysql_query. Wenn möglich sollte er nicht direkt benutz werden sondern die Select,Insert,Delete und Update Funktionen.

query(string sql);

Affected Rows

Dieser Befehl gibt die Anzahl der Zeilen zurück, die durch eine vorherige Abfrage verändert wurden.

getAffectedRows([resource Datenbankverbindung]);

Wie bei getInsertId gibt man normalerweise keine Parameter an.

Last Error

Befehl

Für Debugging ist diese Funktion nützlich, die den letzten Fehler bei einer SQL-Abfrage anzeigt.

getLastError();

Beispiel

$falscherQuery = 'SELECT nix FROM foobar WHERE 1 > 2';
$modx->db->query($falscherQuery);
$fehlermeldung = $modx->db->getLastError();