MySQLHandler

Diese Komponente ist veraltet. Ab dem Release 1.10 sollte nur noch der connectionManager eingesetzt werden. Die Dokumentation der Features gilt jedoch auch für den MySQLx-Treiber.
Der MySQLHandler dient zur Abstraktion einer MySQL-Datenbank gegen die Anwendung. Er nimmt dem Entwickler die Sorge um Datenbank-Spezifika wie Konfiguration, Verbindungsaufbau und standardisiertes Ausführen von Statements ab. Für letzteres stehen dabei zwei Methoden zur Verfügung: Einerseits kann per executeTextStatement() jedes beliebige SQL-Statement ausgeführt werden, möchte der Entwickler die Statements in seiner Anwendung mehrfach und an unterschiedlichen Stellen verwenden, so können Statements ebenso in externe Statement-Dateien ausgelagert und per executeStatement() ausgeführt werden. Die hier relevanten Parameter können in der API-Dokumentation nachgelesen werden.


1. Allgemeine Verwendung

Um den MySQLHandler nutzen zu können muss dieser zuerst per
PHP-Code
import('core::database','MySQLHandler');
in die Applikation eingebunden werden. Anschließend kann mit dem Code-Fragment
PHP-Code
$SQL = &$this->__getServiceObject('core::database','MySQLHandler');
eine Referenz auf den Service erzeugt werden. Da hier die private Methode __getServiceObject() Verwendung findet ist sichergestellt, dass der angefragte Service nur einmal innerhalb der Anwendung erzeugt wird. Dies hat nicht nur einen verwaltungstechnischen, sondern im Fall des Datenbankzugriffs vor allem performancetechnische Vorteile. Intern müssen beispielsweise Datenbank-Verbindungen nur einmal hergestellt und Konfigurationen nur einmal gelesen werden.

Zur Konfiguration der Komponente muss die Konfigurationsdatei
Code
/apps/config/core/database/{CONTEXT}/{ENVIRONMENT}_connections.ini
vorhanden sein. {CONTEXT} ist dabei der Context der aktuellen Applikation, {ENVIRONMENT} der Wert der Umgebungsvariable aus der Registry. Details hierzu können im Kapitel Konfiguration nachgelesen werden. Diese konfiguriert den zu benutzenden Server, Benutzerdaten und die Datenbank. Eine typische Konfigurationsdatei hat folgenden Inhalt:
APF-Konfiguration
[MySQL] DB.Host = "" DB.User = "" DB.Pass = "" DB.Name = "" DB.DebugMode = "true|false" DB.Charset = "" DB.Collation = ""
Falls der Parameter DB.DebugMode auf den Wert true eingestellt ist, legt der MySQLHandler ein Logfile an und notiert Fehler, die während der Benutzung auftreten.

Die Parameter DB.Charset und DB.Collation dienen dazu, den Zeichensatz und die Zeichenbehandlung der MySQL-Verbindung zu definieren. Mit dem Parameter DB.Charset werden die MySQL-Variablen
  • character_set_client
  • character_set_connection
  • character_set_results
gesetzt, DB.Collation beeinflusst
  • collation_connection
  • collation_database
Die beiden Parameter sind optional und können bei Bedarf auch wechselseitig gesetzt werden, das Vorhandensein beider ist nicht erforderlich.

Um nun Daten aus einer Datenbank zu lesen können folgende Zeilen in die Applikation eingebaut werden:
PHP-Code
$select = 'SELECT somefield, anotherfield FROM mytable WHERE somefield = \'somevalue\';'; $result = $SQL->executeTextStatement($select);
Die mit dem Select angefragten Daten können anschließend mit einer while-Schleife abgeholt werden:
PHP-Code
while($data = $SQL->fetchData($result)){ // ... // }

2. Statement-Auslagerung

Soll das gezeigte Statement ausgelagert werden, um von einer weiteren Applikation oder der selben an anderer Stelle verwendet zu werden, so kann die Methode executeStatement() dafür herangezogen werden. Dazu muss das Select in einer Datei mit dem Namen
Code
{ENVIRONMENT}_{StatementDateiName}.sql
abgelegt werden. Der MySQLHandler sucht diese Datei dann im Ordner
Code
{Namespace}/{CONTEXT}
ähnlich zur Benennung der üblichen Konfigurationsdateien. Unter der Annahme, dass das Statement einem Modul unter dem Namespace modules::testmodule "gehört", die Umgebungsvariable nicht angepasst wurde und der Context der Applikation "sites::demosite" lautet muss die Datei den Namen
Code
DEFAULT_mystatement.sql
tragen und im Ordner
Code
/apps/config/modules/testmodule/sites/demosite
abgelegt sein. Um das Statement auszuführen muss die Methode executeStatement() wie folgt verwendet werden:
PHP-Code
$params = array( 'somefield' => 'somevalue' ); $result = $SQL->executeStatement('modules::testmodule','mystatement',$params);
Der dritte Parameter der Methode executeStatement() dient dazu Platzhalter im Statement zu füllen. Platzhalter werden mit "[" einem Namen und "]" gekennzeichnet. Der in den Klammern stehende Name ist gleichzeitig der Name des Platzhalters, der im Parameter-Array verwendet wird. Führt man das obige Beispiel weiter, so hat die Datei DEFAULT_mystatement.sql folgende Gestalt:
Code
SELECT somefield, anotherfield FROM mytable WHERE somefield = '[somefield]';
Ein Anwendungsbeispiel findet sich im Kontaktformular-Tutorial unter Kapitel 4.3.


3. Debugging

Oft ist es notwendig, die gegen die Datenbank abgesetzten Statements zu monitoren. Hierzu bietet der MySQLHandler in den Methoden executeTextStatement() und executeStatement() jeweils einen optionalen Parameter, der es ermöglicht, Statement-Logging zu aktivieren. Details hierzu können der API-Dokumentation entnommen werden.


4. Weitere Features

Der MySQLHandler besitzt weitere Tools zur Unterstützung der Implementierung. Bei Inserts wird die LAST_INSERT_ID automatisch eingelesen und vorgehalten. Diese kann nach dem Ausführen eines Inserts per getLastID() ausgelesen werden.

Darüber hinaus bietet der MySQLHandler Methoden wie getNumRows() und getAffectedRows() um die Ergebnis-Menge eines Selects oder Updates abfragen zu können und fetchData() um Daten von der MySQL abholen zu können.