InhaltsverzeichnisAnleitung für Entwickler
Das Yana-Framework bietet eine API zum Arbeiten mit Datenbanken, welche auf PEAR-DB basiert. Diese API erweitert die Fähigkeiten von PEAR um folgende Features:
Es gibt einige Features welche die FlatFile-Datenbank zur Zeit nicht unterstützt, die aber für eine zukünftige Version geplant sind.
Es gibt einige Features welche in Datenbankschemata zur Zeit nicht unterstützt werden, aber für zukünftige Versionen geplant sind.
Voraussetzung ist eine Schemadatei. Die Schemadateien müssen sich im Verzeichnis "config/db/" befinden und die Dateiendung ".config" besitzen.
API-Dokumentation
<?php
global $YANA;
$name_der_strukturdatei = "guestbook";
$datenbankverbdinung = $YANA->connect($name_der_strukturdatei);
?>Die Verbindungsdaten für die Datenbank (wie Hostadresse, Nutzername und Passwort) werden vom Nutzer im Administrationsmenü eingegeben. Sie müssen diese im Quellcode NICHT angeben.
Wenn Sie keine Strukturdatei verwenden möchten, können Sie diese Angabe frei lassen. Dies wird jedoch in einer Produktionsumgebung nicht empfohlen. In diesem Fall wird das Framework versuchen, die Angaben selbst zu ermitteln. Falls dies fehlschlägt ist die Datenbankverbindung nicht nutzbar.
Wenn Sie eine Verbindung mit einer Datenbank herstellen, aber die Verbindungsdaten selbst angeben wollen, dann gehen Sie wie folgt vor:
<?php
/* Die Verbindungsdaten werden als assoziatives Array angegeben: */
$verbindungsdaten = array(
'DBMS' => 'mysql',
'HOST' => 'localhost',
'PORT' => 0,
'USERNAME' => 'nutzername',
'PASSWORD' => 'passwort',
'DATABASE' => 'name_der_datenbank'
);
/* Um die YANA-API zur Kommunikation mit der Datenbank zu benutzen schreiben Sie: */
$datenbank_server = new DbServer($verbindungsdaten);
$yana_api = new DbStream($datenbank_server);
/* Um die PEAR-API zur Kommunikation mit der Datenbank zu benutzen schreiben Sie: */
$datenbank_server = new DbServer($verbindungsdaten);
$pear_api = $datenbank_server->get();
/* Um die PEAR-API mit den Standardverbindungsdaten zu benutzen schreiben Sie: */
$datenbank_server = new DbServer();
$pear_api = $datenbank_server->get();
?><?php
if (YANA_DATABASE_ACTIVE === true) {
print "Datenbank ist aktiviert";
} else if (YANA_DATABASE_ACTIVE === false) {
print "Datenbank ist NICHT aktiviert";
}
?>Dazu bietet die API die Funktion $db->get(string $key). Diese führt eine Select-Anfrage auf der Datenbank aus und liefert den Wert an der Stelle zurück, welche mit dem Argument $key angegeben wurde.
<?php
global $YANA;
$db = $YANA->connect("guestbook");
/*
Es gilt folgende Syntax:
$db->get(
string "$tabelle.$zeile.$spalte",
string $where,
string $order_by,
int $offset,
int $limit
);
Beispiel:
$value = $db->get("table.1.field","row1=wert1,row2=wert2","row1",0,1);
erzeugt folgende SQL-Anfrage:
SELECT field from table where primary_key = "1" and row1 like '%wert1%' and row2 like '%wert2%' order by row1 limit 1;
*/
/* Feld ausgeben */
$value = $db->get("table.1.field");
/*
erzeugt folgende SQL-Anfrage:
SELECT field from table where primary_key = "1";
*/
/* Spalte ausgeben: */
$column = $db->get("table.*.field");
foreach ($column as $row => $value)
{
print "<p>Value of 'field' in row '$row' = $value</p>";
}
/*
erzeugt folgende SQL-Anfrage:
SELECT field from table;
*/
/* Zeile ausgeben: */
$row = $db->get("table.2");
foreach ($row as $column => $value)
{
echo "<p>Value of column '$column' in row '2' = $value</p>";
}
/*
erzeugt folgende SQL-Anfrage:
SELECT * from table where primary_key = "2";
*/
/* Tabelle ausgeben: */
$table = $db->get("table");
foreach ($table as $index => $row)
{
foreach ($row as $column => $value)
{
echo "<p>Value at 'table.$index.$column' = $value</p>";
}
}
/*
erzeugt folgende SQL-Anfrage:
SELECT * from table;
*/
?>Dazu verwenden Sie die Funktion $db->insert($key,$value). Diese fügt den Wert "value" an der Stelle "key" ein. Dabei kann es sich entweder um eine Zeile oder eine Tabellenzelle handeln. Das Einfügen von ganzen Tabellen oder Spalten ist nicht möglich.
Beim ersten Aufruf der Funktion wird automatisch eine Transaktion gestartet. Benutzen Sie die Funktion $db->write() um ein COMMIT der Daten auszulösen. Wenn eine der Anweisungen in der Transaktion fehlschlägt, wird automatisch ein CALLBACK ausgeführt.
Falls die Zeile nicht existiert, wird ein die SQL-Anweisung "insert" benutzt, sonst "update".
Die Funktion gibt bei Erfolg "true" zurück und "false" sonst.
Bitte beachten Sie: die SQL-Anweisung wird erst ausgeführt, wenn die Funktion $db->write() aufgerufen wird.
Im Folgenden einige Beispiele:
<?php
global $YANA;
$db = $YANA->connect("guestbook");
/* Neue Zeile einfügen: */
$db->insert("table.*",array("row1"=>"wert1","row2"=>"wert2"));
$db->write();
/* Zeile aktualisieren: */
$db->insert("table.2",array("row1"=>"wert1","row2"=>"wert2"));
$db->write();
/* Zelle aktualisieren: */
$db->insert("table.2.row1","wert1");
$db->write();
/* Transaktion durchführen: */
$db->insert("table.*",array("row1"=>"wert1","row2"=>"wert2"));
$db->insert("table.*",array("row1"=>"wert3","row2"=>"wert4"));
$db->insert("table.1.row3","wert1");
$db->write();
?>Dazu verwenden Sie die Funktion $db->remove($key). Diese löscht den Datensatz an der Adresse "key" aus der Tabelle. Die Funktion gibt bei Erfolg "true" zurück und "false" sonst. Es können nur Datensätze gelöscht werden. Keine Tabellen, Zellen oder Spalten.
Beachten Sie folgende Beschränkung: aus Sicherheitsgründen wird pro Aufruf stets maximal 1 Datensatz gelöscht. Wenn Sie mehrere Datensätze löschen wollen, müssen Sie die Funktion mehrmals aufrufen. Diese Einschränkung soll verhindern, dass jemand durch Unachtsamkeit oder aus einem Versehen eine gesamte Tabelle löschen kann.
Bitte beachten Sie: die SQL-Anweisung wird erst ausgeführt, wenn die Funktion $db->write() aufgerufen wird.
<?php
global $YANA;
$db = $YANA->connect("guestbook");
/* Die zweite Zeile löschen: */
$db->remove("table.2");
$db->write();
/**
* erzeugt folgende SQL-Anfrage:
* DELETE FROM table WHERE primary_key = "2" LIMIT 1;
*/
/* Die ganze Tabelle "table" löschen: */
for ($i=0; $i < $db->length($table); $i++)
{
$db->remove("table.*");
}
$db->write();
/**
* erzeugt folgende SQL-Anfrage:
* DELETE FROM table WHERE primary_key = "2" LIMIT 1;
*/
?><?php
global $YANA;
$db = $YANA->connect("guestbook");
if ($db->length("table") === 0) {
print "Die Tabelle 'table' ist leer.";
} else {
print "Die Tabelle 'table' enthält ".$db->length("table")." Datensätze.";
}
?><?php
global $YANA;
$db = $YANA->connect("guestbook");
/* Datenbankverbindung prüfen: */
if ($db->exists() === true) {
print "Die Datenbankverbindung ist verfügbar.";
} else if ($db->exists() === false) {
print "Die Datenbankverbindung ist NICHT verfügbar";
}
/* Prüfen ob Tabelle existiert: */
if ($db->exists("table") === true) {
print "Die Tabelle 'table' existiert.";
} else if ($db->exists("table") === false) {
print "Es gibt keine Tabelle mit dem Namen 'table'.";
}
/* Prüfen ob Datensatz existiert: */
if ($db->exists("table.2") === true) {
print "Der Datensatz '2' in der Tabelle 'table' existiert.";
} else if ($db->exists("table.2") === false) {
print "Es gibt keinen Datensatz '2' in der Tabelle 'table'.";
}
/* Prüfen ob Feld existiert und einen Wert hat: */
if ($db->exists("table.2.field") === true) {
print "Das Feld 'field' im Datensatz '2' in Tabelle 'table' hat einen Wert.";
} else if ($db->exists("table.2.field") === false) {
print "Das Feld 'field' im Datensatz '2' in Tabelle 'table' existiert nicht oder ist NULL.";
}
/* Prüfen ob mindestens 1 Feld existiert, dass NOT NULL ist: */
if ($db->exists("table.*.field") === true) {
print "Die Spalte 'field' in Tabelle 'table' existiert.";
} else if ($db->exists("table.*.field") === false) {
print "Die Spalte 'field' in Tabelle 'table' existiert nicht oder alle Werte sind NULL.";
}
?>Das manuelle Erstellen von Installationsroutinen für das Yana Framework ist nicht erforderlich.
Das Yana Framework hat eine generische Installationsroutine für Datenbanken, welche Sie im Administrationsmenü, in der Basiskonfiguration im Menü "Datenbank Setup" finden. Über dieses Menü kann ein Nutzer alle Tabllen installieren oder Inhalte zwischen dem DBMS und der FlatFile-Datenbank synchronisieren.
Abbildung: Herstellen einer Verbindung und Installation von Datenbanken
Die dafür erforderlichen SQL-Anweisungen erstellt das Framework automatisch aus der Strukturdatei Ihrer Datenbank. Der folgende Quellcode zeigt, wie Sie den durch das Framework generierten Code einsehen können.
<?php
$db = $YANA->connect('guestbook');
$dbe = new DbExtractor($db);
// Erzeugen der "Create Table ..."-Anweisungen für MySQL
$sql = $dbe->createMySQL();
// es existieren einige weitere Funktionen für andere DBMS
$sql = $dbe->createPostgreSQL();
$sql = $dbe->createMSSQL();
$sql = $dbe->createMSAccess();
$sql = $dbe->createDB2();
$sql = $dbe->createOracleDB();
// Ergebnis ausgeben
print implode("\n", $sql);
?>Falls der generierte Code nicht Ihren Erwartungen entspricht, können Sie diesen durch eine eigene SQL-Datei ersetzen. Kopieren Sie diese bitte in das Verzeichnis "config/db/.install/{DBMS}", wobei Sie statt {DBMS} das Unterverzeichnis wählen, welches dem gewünschten DBMS entspricht. Die Datei "config/db/.install/readme.txt", enthält eine Liste der unterstützten DBMS und der Namen der für diese vorgesehenen Verzeichnisse. Sie müssen nicht für alle DBMS eigene Dateien hinterlegen. Falls eine erforderliche Datei nicht existiert, wird das Framework (wie zuvor) automatisch die notwendigen SQL-Anweisungen selbst erzeugen.
Weitere Details finden Sie in der API-Dokumentation der Klasse: "DbExtractor".
<?php
global $YANA;
$db = $YANA->connect("guestbook");
$db->importSQL('data.sql');
?><?php
global $YANA;
$db = $YANA->connect("guestbook");
$csv = $db->toString("table");
file_put_contents("table.csv", $csv);
?>
Thomas Meyer, www.yanaframework.net