Einführung

Die PHP Data Objects(PDO)-Erweiterung stellt eine leichte, konsistente Schnittstelle bereit, um mit PHP auf Datenbanken zuzugreifen. Jeder Datenbanktreiber, der die PDO-Schnittstelle implementiert, kann spezifische Features als reguläre Funktionen der Erweiterung bereitstellen. Beachten Sie, dass Sie keine Funktionen der Datenbank mit PDO allein benutzen können. Sie müssen einen datenbankspezifischen PDO-Treiber benutzen, um auf eine Datenbank zuzugreifen.

PDO bietet eine Abstraktionsschicht für den Datenzugriff, das bedeutet, dass Sie, egal welche Datenbank Sie benutzen, dieselben Funktionen verwenden können, um Abfragen zu erstellen und Daten zu lesen. PDO bietet keine Abstraktion für Datenbanken. Es schreibt keine SQL-Abfragen um oder emuliert fehlende Features. Sie sollten eine komplette Abstraktionsschicht verwenden, wenn Sie diese Funktionalität benötigen.

PDO wird mit PHP 5.1 ausgeliefert und ist als PECL-Erweiterung für PHP 5.0 verfügbar. PDO benötigt die neuen OO-Features im Kern von PHP 5 und wird deswegen nicht mit früheren Versionen von PHP funktionieren.

Installation

Laufzeit Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

Hier eine kurze Erklärung der Konfigurationsoptionen:

PDO-Treiber

Die folgenden Treiber implementieren momentan die PDO-Schnittstelle:

Verbindungen und Verwaltung der Verbindungen

Verbindungen werden durch das Erstellen von Instanzen der PDO-Basisklase erzeugt. Es ist unerheblich, welchen Treiber Sie benutzen wollen. Sie benutzen immer den PDO-Klassennamen. Der Konstruktor erwartet Parameter zur Angabe der Datenbankquelle (auch bekannt als DSN) und optional für Benutzername und Passwort (falls vorhanden).

Beispiel 1. Mit MySQL verbinden <?php $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass); ?>

Wenn es Fehler bei der Verbindung gibt, wird eine Ausnahme vom Typ PDOException geworfen. Sie können die Ausnahme abfangen, wenn Sie sich selbst um die Fehlerbedingung kümmern wollen, oder Sie können es einer globalen Routine zur Ausnahmebehandlung überlassen, die Sie mit set_exception_handler() konfigurieren.

Beispiel 2. Verbindungsfehler behandeln <?php try {    $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);    foreach ($dbh->query('SELECT * from FOO') as $row) {      print_r($row);    }    $dbh = null; } catch (PDOException $e) {    print "Error!: " . $e->getMessage() . "<br/>";    die(); } ?>

Bei erfolgreicher Verbindung zur Datenbank wird eine Instanz der PDO-Klasse an Ihr Script zurückgegeben. Die Verbindung bleibt während der Lebensdauer des PDO-Objekts aktiv. Um die Verbindung zu beenden, müssen Sie das Objekt löschen, indem Sie sicherstellen, dass alle Referenzen darauf gelöscht werden - das erreichen Sie, indem Sie der Variable, die das Objekt beinhaltet, NULL zuweisen. Wenn Sie das nicht explizit tun, schließt PHP die verbindung automatisch, wenn Ihr Script endet.

Beispiel 3. Eine Verbindung schließen <?php $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass); // use the connection here // and now we're done; close it $dbh = null; ?>

Viele Webanwendungen profitieren von persistenten Verbindungen zum Datenbankserver. Persistente Verbindungen werden nicht am Ende des Scripts geschlossen, sondern werden gecachet und wieder benutzt, wenn ein anderes Script eine Verbindung mit denselben Daten anfordert. Der Cache an persistenten Verbindungen erlaubt Ihnen, den Overhead zu vermeiden, wenn jedes mal eine neue Verbindung geöffnet wird, sobald ein Script mit der Datenbank kommunizieren muss, was sich in einer schnelleren Anwendung widerspiegelt.

Beispiel 4. Persistente Verbindungen <?php $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass, array(   PDO::ATTR_PERSISTENT => true )); ?>

Transaktionen und auto-commit

Jetzt, wo Sie via PDO verbunden sind, müssen Sie sich bewusst machen, wie PDO Transaktionen verwaltet, bevor Sie anfangen, Abfragen auszuführen. Falls Sie noch niemit Transaktionen zu tun hatten, diese bieten 4 wichtige Features: Atomizität, Konsistenz (Consistency), Isolation und Dauerhaftigkeit (Durability) (ACID). Einfach gesagt wird alles in einer Transaktion, auch wenn es in Einzelschritten ausgeführt wird, garantiert in sicherer Weise in die Datenbank eingetragen, ohne Beeinträchtigung durch andere Verbindungen, wenn es abgeschickt wird. Aktivitäten in Transaktionen können auch automatisch annulliert werden (wenn Sie es noch nicht abgeschickt haben), was Fehlerbehandlung in Ihren Scripts einfacher macht.

Transaktionen werden typischerweise implementiert, indem Ihre Menge an Änderungen "aufgespart" wird und dann in einem Rutsch abgearbeitet werden. Das hat den netten Nebeneffekt, dass die Effizienz der Aktualisierungen drastisch erhöht wird. In anderen Worten können Transaktionen Ihre Scripts schneller und möglicherweise auch robuster machen. Aber Sie müssen sie korrekt verwenden, um davon zu profitieren.

Unglücklicherweise unterstützt nicht jede Datenbank Transaktionen, deswegen muss PDO in einem "auto-commit" genannten Modus laufen, wenn Sie die Verbindung zum ersten Mal öffnen. "Auto-commit" bedeutet, dass jede Abfrage, die Sie ausführen ihre eigene implizite Transaktion besitzt, wenn die Datenbank das unterstützt, oder keine Transaktion, wenn die Datenbank keine Transaktionen unterstützt. Wenn Sie eine Transaktion benötigen, müssen Sie eine mit der Methode PDO::beginTransaction() initiieren. Wenn der zu Grunde liegende Treiber keine Transaktionen unterstützt, wird eine PDOException geworfen (unbeachtet Ihrer Einstellungen zur Fehlerbehandlung: dies ist immer eine ernste Fehlerbedingung). Wenn Sie dann in einer Transaktion sind, können Sie PDO::commit() oder PDO::rollBack() benutzen, um die Transaktion abzuschließen, abhängig vom Erfolg des Codes, den Sie während der Transaktion ausgeführt haben.

Wenn das Script endet oder die Verbindung im Begriff ist, geschlossen zu werden und Sie eine Transaktion ausstehen haben, wird PDO automatisch einen Rollback durchführen. Dies ist eine Sicherheitsmaßnahme, um Inkonsistenzen in dem Fall, wo das Script unerwartet beendet wird, zu vermeiden - wenn Sie die Transaktion nicht explizit ausgeführt haben, wird angenommen, dass etwas schiefgegangen ist, deswegen wird zur Sicherheit ein Rollback durchgeführt.

Beispiel 5. Mehrere Abfragen in einer Transaktion Im folgenden Beispiel nehmen wir an, dass wir einen Satz von Einträgen für einen neuen Angestellten eintragen wollen, dem die ID-Nummer 23 zugeordnet wurde. Zusätzlich zur Angabe der Basisdaten für diese Person müssen wir auch ihr Gehalt festhalten. Es ist ziemlich einfach, zwei getrennte Aktualisierungen durchzuführen, aber indem wir sie in PDO::beginTransaction() und PDO::commit() einschließen, garantieren wir, dass niemand anderes diese Änderungen sieht, bis sie komplett sind. Wenn etwas schiefgeht, wird der catch-Block alle seit Beginn der Transaktion durchgeführten Änderungen rückgängig machen und dann eine Fehlermeldung ausgeben. <?php try {   $dbh = new PDO('odbc:SAMPLE', 'db2inst1', 'ibmdb2',      array(PDO::ATTR_PERSISTENT => true));   echo "Connected\n";   $dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);   $dbh->beginTransaction();   $dbh->exec("insert into staff (id, first, last) values (23, 'Joe', 'Bloggs')");   $dbh->exec("insert into salarychange (id, amount, changedate)      values (23, 50000, NOW())");   $dbh->commit();   } catch (Exception $e) {   $dbh->rollBack();   echo "Failed: " . $e->getMessage(); } ?>

Sie sind nicht darauf beschränkt, Änderungen in einer Transaktion durchzuführen. Sie können auch komplexe Abfragen ausführen um Daten zu erhalten, und diese Informationen etwa dazu benutzen, mehr Änderungen und Abfragen zu erzeugen. Während die Transaktion aktiv ist, kann garantiert niemand anderes Änderungen durchführen, während Sie bei der Arbeit sind. Um ehrlich zu sein, stimmt das nicht 100%, aber es ist für den Anfang ausreichend, falls Sie noch nie von Transaktionen gehört haben.

Prepared Statements und Stored Procedures

Viele der ausgereifteren Datenbanken unterstützen das Konzept der Prepared Statements. Was ist das? Sie können sie sich als eine Art von kompiliertem Template für SQL vorstellen, das durch variable Parameter angepasst werden kann. Prepared Statements haben zwei wichtige Vorteile:

• Die Abfrage muss nur einmal geparset (oder vorbereitet) werden, kann dann aber mehrere Male mit denselben oder anderen Parametern ausgeführt werden. Wenn die Abfrage vorbereitet wird, kann die Datenbank ihre Vorgehensweise zur Ausführung der Abfrage analysieren, kompilieren und optimieren. Für komplexe Abfragen kann dieser Vorgang genug Zeit benötigen, dass es Ihre Anwendung merklich verlangsamt, wenn Sie dieselbe Abfrage oft mit verschiedenen Parametern wiederholen. Mit einem Prepared Statement vermeiden Sie den Zyklus der Analyse/Kompilierung/Optimierung. Kurz gesagt benötigen Prepared Statements weniger Ressourcen und laufen deswegen schneller.

• Die Parameter für Prepared Statements müssen nicht maskiert werden. Der Treiber übernimmt das für Sie. Wenn Ihre Anwendung ausschließlich Prepared Statements benutzt, können Sie sicher sein, dass keine SQL-Injection auftreten wird. (Wenn Sie aber trotzdem andere Teile der Abfrage aus nicht zuverlässigen Eingaben generieren, sind Sie immer noch gefährdet.)

Prepared Statements sind so nützlich, dass sie das einzige Feature sind, das PDO auch für Treiber emulieren wird, die diese nicht unterstützen. Das garantiert, dass Sie unabhängig von den Möglichkeiten der Datenbank dieselbe Art des Datenzugriffs nutzen können.

Beispiel 6. Wiederholte Inserts mit Prepared Statements Dieses Beispiel führt eine INSERT-Abfrage durch, indem ein name und ein value für die benannten Platzhalter eingesetzt werden. <?php $stmt = $dbh->prepare("INSERT INTO REGISTRY (name, value) VALUES (:name, :value)"); $stmt->bindParam(':name', $name); $stmt->bindParam(':value', $value); // insert one row $name = 'one'; $value = 1; $stmt->execute(); // insert another row with different values $name = 'two'; $value = 2; $stmt->execute(); ?>

Beispiel 7. Wiederholte Inserts mit Prepared Statements Dieses Beispiel führt eine INSERT-Abfrage durch, indem ein name und ein value für die positionsabhängigen ?-Platzhalter eingesetzt werden. <?php $stmt = $dbh->prepare("INSERT INTO REGISTRY (name, value) VALUES (?, ?)"); $stmt->bindParam(1, $name); $stmt->bindParam(2, $value); // insert one row $name = 'one'; $value = 1; $stmt->execute(); // insert another row with different values $name = 'two'; $value = 2; $stmt->execute(); ?>

Beispiel 8. Abfragen von Daten mit Prepared Statements Dieses Beispiel ruft Daten basierend auf einem Schlüsselwert ab, der von einem Formular geliefert wird. Die Benutzereingabe wird automatisch maskiert, deswegen gibt es kein Risiko eines SQL-Injection-Angriffs. <?php $stmt = $dbh->prepare("SELECT * FROM REGISTRY where name = ?"); if ($stmt->execute(array($_GET['name']))) {   while ($row = $stmt->fetch()) {    print_r($row);   } } ?>

Wenn es der Datenbanktreiber unterstützt, können Sie auch Parameter für die Ausgabe einführen, ähnlich der Eingabe. Ausgabeparameter werden typischerweise benutzt, um Werte von Stored Procedures abzurufen. Ausgabeparameter sind etwas komplexer in der Verwendung als Eingabeparameter, weil Sie wissen müssen, wie groß ein gegebener Parameter sein könnte, wenn Sie ihn einführen. Wenn der Wert sich als größer herausstellt als die vorgeschlagene Größe, wird ein Fehler ausgelöst.

Beispiel 9. Eine Stored Procedure mit einem Ausgabeparameter aufrufen <?php $stmt = $dbh->prepare("CALL sp_returns_string(?)"); $stmt->bindParam(1, $return_value, PDO::PARAM_STR, 4000); // call the stored procedure $stmt->execute(); print "procedure returned $return_value\n"; ?>

Sie können auch Parameter angeben, die Werte für Eingabe und Ausgabe enthalten. Die Syntax ist ähnlich den Ausgabeparametern. In diesem nächsten Beispiel wird die Zeichenkette 'hello' der Stored Procedure übergeben und wenn diese etwas zurückgibt, wird 'hello' durch den Rückgabewert der Stored procedure ersetzt.

Beispiel 10. Eine Stored Procedure mit einem Eingabe-/Ausgabe-Parameter aufrufen <?php $stmt = $dbh->prepare("CALL sp_takes_string_returns_string(?)"); $value = 'hello'; $stmt->bindParam(1, $value, PDO::PARAM_STR|PDO::PARAM_INPUT_OUTPUT, 4000); // call the stored procedure $stmt->execute(); print "procedure returned $value\n"; ?>

Fehler und Fehlerbehandlung

PDO bietet Ihnen die Wahl unter 3 verschiedenen Strategien zur Fehlerbehandlung, um Ihrem Stil der Anwendungsentwicklung gerecht zu werden.

• PDO::ERRMODE_SILENT

  Das ist die Standardmethode. PDO setzt einfach den Fehler-Code, damit Sie ihn mit den Methoden PDO::errorCode() und PDO::errorInfo() sowohl im Statement- als auch im Datenbank-Objekt überprüfen können. Wenn der Fehler aus einem Aufruf eines Statement-Objekts hervorging, würden Sie die Methoden PDOStatement::errorCode() oder PDOStatement::errorInfo() des Objekts aufrufen. Wenn der Fehler aus einem Aufruf des Datenbank-Objekts hervorging, würden Sie diese Methoden des Datenbank-Objekts aufrufen.

• PDO::ERRMODE_WARNING

  Zusätzlich zum Setzen des Fehler-Codes wird PDO eine traditionelle E_WARNING-Nachricht ausgeben. Diese Einstellung ist nützlich während des Debuggens/Testens, wenn Sie sehen wollen, welche Probleme aufgetreten sind, ohne den Ablauf der Anwendung zu unterbrechen.

• PDO::ERRMODE_EXCEPTION

  Zusätzlich zum Setzen des Fehler-Codes wirft PDO eine PDOException und setzt deren Eigenschaften so, dass sie den Fehler-Code und Fehlerinformationen widergeben. Diese Einstellung ist auch nützlich während des Debuggens, da sie das Script am Ort des Fehlers gewissermaßen "sprengt" und sehr schnell mögliche Problemstellen in Ihrem Code aufzeigt. (Zur Erinnerung: Transaktionen bekommen automatisch einen Rollback, wenn eine Ausnahme das Script beendet.)

  Diese Einstellung ist auch nützlich, da Sie ihre Fehlerbehandlung klarer als mit traditionellen PHP-Warnungen strukturireren können und mit weniger Code und Verschachtelung als im stillen Modus mit expliziter Überprüfung des Rückgabewertes jedes einzelnen Datenbankaufrufes.

  Unter Ausnahmen finden Sie weitere Informationen über Ausnahmen in PHP.

PDO benutzt Fehler-Codes nach SQL-92 SQLSTATE. Individuelle PDO-Treiber sind selbst verantwortlich, ihre nativen Fehler-Codes in die entsprechenden SQLSTATE-Pendants umzuwandeln. Die Methode PDO::errorCode() gibt einen einzelnen SQLSTATE-Code zurück. Wenn Sie genauere Informationen über einen Fehler benötigen, bietet PDO auch die Methode PDO::errorInfo(), die ein Array zurückgibt, das den SQLSTATE-Code, den treiberspezifischen Fehler-Code und die treiberspezifische Fehlermeldung enthält.

Large Objects (LOBs)

Es könnte an irgendeinem Punkt in Ihrer Anwendung passieren, dass Sie eine "große" Menge an Daten in Ihrer Datenbank ablegen müssen. Groß bedeutet typischerweise "etwa 4kb oder mehr", obwohl manche Datenbanken spielend bis zu 32kb bearbeiten können, bevor das als "groß" zählt. Large Objects können aus Text oder Binärdaten bestehen. PDO erlaubt Ihnen, mit diesem großen Datentyp zu arbeiten, indem Sie PDO::PARAM_LOB als Typ in Ihren Methodenaufrufen von PDOStatement::bindParam() oder PDOStatement::bindColumn() benutzen. PDO::PARAM_LOB veranlasst PDO, die Daten als Stream zu behandeln, so dass Sie diese mit Hilfe der PHP Streams-API bearbeiten können.

Beispiel 11. Ein Bild aus einer Datenbank anzeigen Dieses Beispiel weist das LOB der Variable namens $lob zu und sendet es mittels fpassthru() an den Browser. Weil das LOB als Stream dargestellt wird, können Funktionen wie fgets(), fread() und stream_get_contents() damit benutzt werden. <?php $db = new PDO('odbc:SAMPLE', 'db2inst1', 'ibmdb2'); $stmt = $db->prepare("select contenttype, imagedata from images where id=?"); $stmt->execute(array($_GET['id'])); $stmt->bindColumn(1, $type, PDO::PARAM_STR, 256); $stmt->bindColumn(2, $lob, PDO::PARAM_LOB); $stmt->fetch(PDO::FETCH_BOUND); header("Content-Type: $type"); fpassthru($lob); ?>

Beispiel 12. Ein Bild in eine Datenbank einfügen Dieses Beispiel öffnet eine Datei und übergibt das File-Handle an PDO, damit sie als LOB eingefügt wird. PDO wird sein Möglichstes tun, den Inhalt der Datei auf möglichst effiziente Weise in die Datenbank zu bekommen. <?php $db = new PDO('odbc:SAMPLE', 'db2inst1', 'ibmdb2'); $stmt = $db->prepare("insert into images (id, contenttype, imagedata) values (?, ?, ?)"); $id = get_new_id(); // some function to allocate a new ID // assume that we are running as part of a file upload form // You can find more information in the PHP documentation $fp = fopen($_FILES['file']['tmp_name'], 'rb'); $stmt->bindParam(1, $id); $stmt->bindParam(2, $_FILES['file']['type']); $stmt->bindParam(3, $fp, PDO::PARAM_LOB); $stmt->beginTransaction(); $stmt->execute(); $stmt->commit(); ?>

Beispiel 13. Ein Bild in eine Datenbank einfügen: Oracle Oracle erfordert eine leicht unterschiedliche Syntax, um ein LOB aus einer Datei einzufügen. Es ist auch unumgänglich, dass Sie diesen Insert innerhalb einer Transaktion durchführen, andernfalls wird Ihr frisch eingefügtes LOB mit einer Länge von 0 als Teil des impliziten commits, der beim Ausführen der Abfrage passiert, gespeichert. <?php $db = new PDO('oci:', 'scott', 'tiger'); $stmt = $db->prepare("insert into images (id, contenttype, imagedata) " .   "VALUES (?, ?, EMPTY_BLOB()) RETURNING imagedata INTO ?"); $id = get_new_id(); // some function to allocate a new ID // assume that we are running as part of a file upload form // You can find more information in the PHP documentation $fp = fopen($_FILES['file']['tmp_name'], 'rb'); $stmt->bindParam(1, $id); $stmt->bindParam(2, $_FILES['file']['type']); $stmt->bindParam(3, $fp, PDO::PARAM_LOB); $stmt->beginTransaction(); $stmt->execute(); $stmt->commit(); ?>

Vordefinierte Klassen

Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.