Tuple-Tub V1.1 - Dokumentation

(c) 2005/2006 Carsten Meier

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Inhaltsverzeichnis

1. Einleitung
2. Funktionsweise
3. Funktionen
   1. Öffnen einer Datenbank
   2. Schließen einer Datenbank
   3. Anlegen von Tabellen
   4. Einfügen von Datensätzen
   5. Auslesen von Daten
   6. Ändern von Datensätzen
   7. Löschen von Datensätzen
4. Änderungen zu Vorversionen
5. Kontakt

1 Einleitung

Tuple-Tub ist eine PHP-Bibliothek, die die grundlegende Funktionalität einer relationalen Datenbank mit Hilfe des Dateisystems und des PHP-Serialize-Mechanismus nachbildet. Bei mittlerem oder großem Datenvolumen ist der Einsatz dieses Skriptes nicht zu empfehlen, für kleinere Datenmengen ist es jedoch gut geeignet.

Bei der vorliegenden Fassung handelt es sich um Version 1.1 vom 5.9.2006. Die jeweils aktuelle Version können Sie auf der Tuple-Tub-Homepage herunterladen.

Folgende Dateien sind enthalten:

tuple-tub.php

Tuple-Tub-Bibliothek

LICENSE

Eine Kopie der GNU Lesser General Public License V2.1

LIESMICH.html

Die Datei, die Sie gerade lesen

Es wird PHP >= 4.3.0 benötigt. Das Skript wurde unter PHP 4.3.3 und PHP 4.3.10 mit den Laufzeit-Optionen register_globals off und allow_call_time_pass_reference off getestet.

2 Funktionsweise

Unterschiedliche Datenbanken werden als Verzeichnisse verwaltet. Um eine Datenbank zu erstellen, muß nur ein für den Webserver beschreibares Verzeichnis angelegt werden. Tabellen werden darin mit Hilfe des PHP-Serialize-Mechanismus auf Dateien abgebildet.

Um konkurrierende Zugriffe auszuschließen, wird File-Locking benutzt. Tabellen werden beim ersten Zugriff komplett in den Speicher geladen, und dort bis zum Schließen der Datanbank gecachet. Bei Datenänderungen wird aus Gründen der Sicherheit immer sofort die gesamte Tabelle in die entsprechende Datei zurückgeschrieben.

Achtung!

Falls Apache-2 zum Einsatz kommt ist, unbedingt darauf zu achten, daß kein Threaded-MPM benutzt wird. Der File-Locking-Mechanismus funktioniert in diesem Fall nicht und Datenverlust kann die Folge sein! Für weitere Information lesen Sie bitte die Dokumentation zu der Funktion flock() im PHP-Handbuch.

3 Funktionen

Es folgt eine thematisch sortierte Übersicht über die bereitgestellten Funktionen. Um diese zu nutzen, kopieren Sie einfach die Datei 'tuple-tub.php' in ein Verzeichnis innerhalb Ihres PHP-Include-Pfades. Über include 'tuple-tub.php'; binden Sie diese in Ihr Skript ein. Die Funktionen geben, sofern nicht anders angegeben, bei Erfolg true und im Fehlerfall false zurück.

3.1 Öffnen einer Datenbank

Vor dem ersten Zugriff muß eine Datenbank geöffnet werden. Unter Öffnen ist in diesem Zusammenhang das Erstellen einer Datenstruktur für das Caching zu verstehen. Diese Struktur wird allen anderen Funktionen jeweils als erstes Argument ($database) übergeben, und wird von der folgenden Funktion per Referenz geliefert:

function &tupletub_open($dirname)

Der String $dirname muß dabei zwingend mit einem / enden, da zum Öffnen einer Tabellendatei der Tabellenname an diesen String angehängt wird.

Wenn Sie den zurückgegebenen Wert an eine Variablen zuweisen, so sollte dies unbedingt per Referenz geschehen, da ansonsten alle gecacheten Tabellen kopiert werden!

3.2 Schließen einer Datenbank

Nach dem letzten Zugriff sollte die Datenbank wieder geschlossen werden. Hierbei werden alle gecacheten Tabellen aus dem Speicher entfernt, und die zugehörigen Dateien wieder geschlossen:

function tupletub_close(&$database)

3.3 Anlegen von Tabellen

Damit Daten abgelegt werden können, müssen zunächst Tabellen angelegt werden:

function tupletub_create_table(&$database, $tablename, &$columns)

Es werden dabei die oben erwähnte Datenbank, der Tabellenname und die darin enthaltenen Spalten übergeben. Die Spalten werden als ein mehrdimensionales Array übergeben. Der Spaltenname wird als Schlüssel eingesetzt, als Wert wird jeweils ein weiteres Array mit dem Schlüssel 'type' erwartet, mit dem der PHP-Typ spezifiziert wird. Folgendes Beispiel legt eine Tabelle mit dem Namen 'gaeste' und den Spalten 'name' und 'alter' an:

$columns = array(
	'name'	=> array('type' => 'string'),
	'alter'	=> array('type' => 'integer')
);
tupletub_create_table($database, 'gaeste', $columns);

3.4 Einfügen von Datensätzen

Mit der folgenden Funktion können Daten in die Tabellen eingefügt werden:

function tupletub_insert(&$database, $tablename, &$data)

Bei dem $data-Argument handelt es sich um ein Array mit den einzufügenden Daten, das als Schlüssel die Spaltennamen enthält:

$data = array(
	'name'	=> 'Fritz',
	'alter'	=> 34
);
tupletub_insert($database, 'gaeste', $data);

Jeder eingefügten Zeile wird zusätzlich noch eine eindeutige, numerische ID zugewiesen. Ab Version 1.1 ist diese immer ungleich 0. Um die ID des zuletzt eingefügten Datensatzes zu ermitteln, kann die Funktion tupletub_last_insert_id() verwendet werden:

$lastid = tupletub_last_insert_id($database);

Es wird dabei die verwendete Datenbank übergeben und die ID geliefert. Dieser Mechanismus wird beispielsweise verwendet, wenn die ID als Fremdschlüssel in einer weiteren Tabelle verwendet werden soll. Wurde nach dem Öffnen der Datenbank bisher kein Datensatz eingefügt, wird 0 zurückgegeben.

3.5 Auslesen von Daten

Zum Auslesen von Daten stehen zwei Funktionen bereit:

function &tupletub_select_by_id(&$database, $tablename, $id)
function &tupletub_select(
	&$database, $tablename, $filtercallback = '', $sortcallback = '')

Erstere liefert genau einen Datensatz mit der angegebenen ID. Die Rückgabe erfolgt in einem Array, dessen Schlüssel den Spaltennamen entsprechen.

Mit der zweiten Funktionen lassen sich mehrere Datensätze selektieren und gleichzeitig sortieren. Es wird dabei ein Array mit Datensätzen geliefert, das als Schlüssel die eindeutigen IDs und als Werte die Datensätze, wie oben angegeben, enthält. Die Auswahl der Datensätze und die Sortierung wird durch Callback-Funktionen bestimmt.

Die über $filtercallback angegebene Funktion dient zur Auswahl der Datensätze. Diese bekommt einen Datensatz übergeben und liefert, je nachdem, ob dieser in das Ergebnisarray geschrieben werden soll, true oder false. Wird als Callback-Funktion ein leerer String angegeben, werden alle Zeilen der Tabelle selektiert.

Über $sortcallback läßt sich die Sortierung festlegen. Der Callback-Funktion werden dabei zwei Datensätze übergeben. Soll der erste vor dem zweiten einsortiert werden, so muß hier -1 zurückgegeben werden, im umgekehrten Fall 1. Sind beide Datensätze gleich, so wird dies mit dem Wert 0 angezeigt. Soll keine Sortierung vorgenommen werden, so wird für $sortcallback ein leerer String angegeben.

Folgendes Beispiel gibt alle Gäste mit einem Alter von über 30 Jahren alphabetisch sortiert aus:

function alter_filter_callback($row)
	{ return $row['alter'] > 30; }

function name_sort_callback($row1, $row2)
	{ return strcoll($row1['name'], $row2['name']); }

$result = &tupletub_select(
	$database, 'gaeste', 'alter_filter_callback', 'name_sort_callback')

3.6 Ändern von Datensätzen

Mit der folgenden Funktion können einzelne Datensätze einer Tabelle geändert werden:

function tupletub_update_by_id(&$database, $tablename, $id, &$data)

Bei dem $data-Argument handelt es sich um ein Array mit den zu ersetzenden Werten, das als Schlüssel die Spaltennamen enthält. Es werden jeweils nur die Spalten geändert, zu denen ein Eintrag in diesem Array vorhanden ist. Folgendes Beispiel setzt das Alter in dem Datensatz mit der ID 1 auf 36.

$data = array(
	'alter'	=> 36
);
tupletub_update_by_id($database, 'gaeste', 1, $data);

Die ID eines Datensatzes läßt sich über die oben beschriebene Funktion tupletub_select() ermitteln.

3.7 Löschen von Datensätzen

function tupletub_delete_by_id(&$database, $tablename, $id)

Die Funktion löscht den Datensatz mit der angegebenen ID aus der Tabelle.

4 Änderungen zu Vorversionen

Version 1.1

• Als erste ID wird für Datensätze nun 1 anstatt 0 verwendet. Dies wurde geändert, um mit anderen DBMS konform zu gehen.
• Die zuletzt durch die Funktion tupletub_insert() generierte ID läßt sich mit der neuen Funktion tupletub_last_insert_id() abfragen.

Version 1.0.1

• Ein Bug, der den magic_quotes_runtime-Konfigurationsparameter nach Aufruf von Tuple-Tub-Funktion auf on gesetzt hat, wurde behoben. Jetzt wird jeweils die vorherige Einstellung wiederhergestellt.

5 Kontakt

Wenn Sie Fragen zu dem Skript stellen, oder einen Kommentar abgeben möchten, können Sie dies im Tuple-Tub-Forum tun. Bitte geben Sie bei Problemen immer die verwendeten PHP- und Skript-Versionen, sowie das verwendete Betriebssystem an!

Unterstützen Sie die Entwicklung weiterer, frei verfügbarer Skripte durch das Setzen eines Links zu http://www.internalscripts.de/ . Vielen Dank!

Anschrift des Autors

Fragen zur Benutzung des Skripts bitte im Forum stellen!