dbConnect - MySQL Schnittstelle

dbConnect wurde durch dbConnect_LE ersetzt!

Das Ziel von dbConnect ist es Ihnen eine einfach zu bedienende und sichere Klasse zur Verfügung zu stellen, die alle MySQL Grundfunktionen für die einfache Entwicklung von eigenen Modulen beinhaltet.

Eigenschaften:

• einfaches Definieren, Anlegen und Löschen von Tabellen
• Einfügen, Aktualisieren, Löschen und Auswählen von Datensätzen
• einfache Integration beliebiger Felder Ihrer Tabellen in die Website Baker Suchfunktion
• Ausführen von beliebigen SQL Befehlen
• Verhindern von SQL Injections
• eine sichere Fehlerbehandlung schützt vor Überraschungen
• detailierte Fehlermeldungen
• Simulationsmodus zum einfachen Testen

Anforderungen

Anforderungen:

• dbConnect verwendet OOP Eigenschaften sowie die erweiterte Fehlerbehandlung von PHP 5 und ist nicht kompatibel zu PHP 4

Anwendung (Basis Funktionen)

Um die Funktionsweise von dbConnect zu verstehen sollten Sie sich das Beispielmodul dbConnect SAMPLE (install_sample.zip) im Ordner /sample installieren und sich die Quelldateien dazu im Orner /source ansehen.

Beginnen Sie mit der Datei class.sample.php:

dbConnect wird als Snippet installiert und steht im Frontend automatisch in allen Dateien zur Verfügung. Im Backend werden Snippets jedoch nicht automatisch eingebunden und müssen explizit aufgerufen werden.

if (!class_exists('dbConnect')) {
  // the class dbConnect does not exists, try to load class
  if (file_exists(WB_PATH.'/modules/dbconnect/include.php')) {
    require_once(WB_PATH.'/modules/dbconnect/include.php'); 
  }
  else {
    // class is not available
    die("Program execution stopped: This module needs the class dbConnect, please install and try again.");  
  } 
}

Das Codesegment überprüft ob die Klasse dbConnect existiert und versucht sie gegebenenfalls zu laden. Kann die Klasse nicht geladen werden wird die Programmausführung mit einer Fehlermeldung beendet.

Um Zugriff auf die Funktionen von dbConnect zu erhalten erzeugen Sie eine eigene Klasse die dbConnect erweitert und schreiben Sie einen Konstruktor __construct() dazu, der die Definition für Ihre Datenbanktabelle enthält und wesentliche Eigenschaften festlegt:

class sample_dbConnect extends dbConnect {  
  public function __construct() {
    parent::__construct();
    $this->setTableName('mod_sample_dbconnect');
    $this->setModuleDirectory('dbconnect_sample');
    $this->setModuleName('dbConnect SAMPLE');
    $this->addFieldDefinition('id',             "INT(11) NOT NULL AUTO_INCREMENT", true);
    $this->addFieldDefinition('section_id',     "INT(11) NOT NULL DEFAULT '0'");
    $this->addFieldDefinition('page_id',        "INT(11) NOT NULL DEFAULT '0'");
    $this->addFieldDefinition('simple_text',    "VARCHAR(255) NOT NULL DEFAULT ''", false, true);
    $this->addFieldDefinition('html_text',      "VARCHAR(255) NOT NULL DEFAULT ''", false, true, true);
    $this->addFieldDefinition('last_modified',  "INT(11) NOT NULL DEFAULT '0'");
    $this->setField_PageID('page_id');
    $this->setField_SectionID('section_id');
    $this->setAllowedHTMLtags('<p><i><b><em><strong>');
    $this->checkFieldDefinitions();  
  } // __construct()
} // class sample_dbConnect

parent::__construct() ruft den Konstructor von dbConnect auf und initialisiert die Klasse. Führen Sie diesen Aufruf vor allen anderen Anweisungen in Ihrem Konstruktor durch.

Alle Definitionen Ihrer Tabelle die Sie im folgenden durchführen, müssen konform zur SQL Syntax sein.

$this->setTableName('mod_sample_dbconnect') legt den Namen der Tabelle fest. Bitte beachten Sie hierbei die Website Baker Konvention, daß Tabellennamen von Modulen immer mit dem Päfix mod_ beginnen.

Die Aufrufe $this->setModuleDirectory('dbconnect_sample') und $this->setModuleName('dbConnect SAMPLE') teilen dbConnect das Unterverzeichnis Ihres Moduls im Verzeichnis /modules und den Namen Ihres Moduls mit. Diese Informationen werden von dbConnect benötigt um festgelegte Felder Ihrer Tabelle in die Website Baker Suchfunktion einzubinden. Wenn Sie die Suchfunktion in Ihrem Modul nicht benötigen, können Sie diese beiden Aufrufe weglassen.

Mit $this->addFieldDefinition() fügen Sie die Definition und zusätzliche Parameter für jedes einzelne Feld in Ihrer Datenbanktabelle ein:

    /**
     * Define FIELD in Table. Call this function for each field.
     *
     * @param STRING $field Identifer
     * @param STRING $type SQL Definition of Field Type
     * @param BOOLEAN $primaryKey set TRUE if this Field should be the primary key
     * @param BOOLEAN $makeSearchable set TRUE if this Field should be visible for the WB Search function
     * @param BOOLEAN $allowHTML set TRUE if the Field is allowed to contain HTML tags
     */
    public function addFieldDefinition($field, $type, $primaryKey=false, $makeSearchable=false, $allowHTML=false) 

Wie sie sehen sind $field und $type Pflichtparameter und $primaryKey, $makeSearchable sowie $allowHTML optionale Parameter, die mit dem Wert false vorbelegt sind.

$field ist der Name des Feldes und muß der SQL syntax entsprechen.

$type ist reine SQL Syntax und beschreibt den Feld Typ und weitere Eigenschaften.

Der erste optionale Parameter $primaryKey muß auf true gesetzt werden, wenn dieses Feld der Primärschlüssel der Datenbanktabelle ist.

Der zweite optionale Parameter $makeSearchable muß auf true gesetzt werden, wenn Sie möchten daß dieses Feld von der Website Baker Suchfunktion berücksichtigt wird. Wenn Sie diesen Parameter auf true setzen, müssen Sie dbConnect außerdem das Verzeichnis $this->setModuleDirectory(...) sowie den Namen $this->setModuleName(...) Ihres Modules mitteilen und Felder für die Aufnahme der  page_id sowie der section_id der jeweiligen Seite definieren. Die Namen dieser Felder teilen Sie dbConnect über $this->setField_PageID('page_id') und $this->setField_SectionID('section_id') mit.

Normalerweise entfernt dbConnect automatisch alle HTML Tags und CODE aus den übergebenen Daten um SQL Einspeisungen (SQL Injection) zu verhindern. Wenn Sie ein Feld benötigen in dem HTML Tags erlaubt sind, setzen Sie den dritten optionalen Parameter $allowHTML auf true.

Abschließend rufen Sie $this->checkFieldDefinitions() in Ihrem Konstruktor auf und dbConnect überprüft alle Felder auf logische Fehler und fehlende Informationen. Da der Konstruktor keine Fehlermeldung zurückgeben kann, werden Fehler ggf. festgehalten und mit dem nächsten Funktionsaufruf von dbConnect zurückgegeben.

Alle Funktionen von dbConnect, die eine SQL Abfrage durchführen (Sie erkennen diese Funktionen daran, daß sie mit sqlXxx beginnen) geben bei erfolgreicher Durchführung true und bei einem Fehler false zurück. Im Falle eines Fehlers können Sie die Fehlermeldung über $this->getError() abrufen.

Mit der Definition des Konstruktors für Ihre Nachfolgeklasse von dbConnect haben Sie alles getan um die Funktionen von dbConnect nutzen zu können.

Das erste, was wir jetzt tun, ist die Datenbanktabelle zu installieren. Bitte schauen Sie hierzu in die Datei install.php im Verzeichnis /sample.

// Load the unit with the required sample class
require_once(WB_PATH.'/modules/'.basename(dirname(__FILE__)).'/class.sample.php');
// create a new instance of sample_dbConnect();
$dbSample = new sample_dbConnect();
// now we install the table
if (!$dbSample->sqlCreateTable()) {
  // if an error occurs let $admin prompt the error message from dbConnect
  $admin->print_error($dbSample->getError()); 
}

Sie sehen: im Grunde beschränkt sich die Installation der Datenbanktabelle auf den Aufruf sqlCreateTable() 

Im Falle eines Fehlers wird die Fehlermeldung über $admin->print_error($dbSample->getError()); ausgegeben.

Wenn Sie nach der Installation der Datenbanktabelle die Website Baker Suchfunktion einbinden möchten genügt ein Aufruf von $dbSample->sqlAddSearchFeature().

// ... and install the WB Search feature for sample_dbConnect
if (!$dbSample->sqlAddSearchFeature()) {
  $admin->print_error($dbSample->getError()); 
}

Die Deinstallation funktioniert auf die gleiche Art und Weise jedoch in umgekehrter Reihenfolge - entfernen Sie zunächst die Website Baker Suchfunktion und löschen Sie anschließend die Datenbanktabelle - bitte werfen Sie einen Blick in die Beispieldatei uninstall.php im Verzeichnis /sample:

// Load the unit with the required sample class
require_once(WB_PATH.'/modules/'.basename(dirname(__FILE__)).'/class.sample.php');
// create a new instance of sample_dbConnect();
$dbSample = new sample_dbConnect();
// remove the WB search feature for sample_dbConnect
if (!$dbSample->sqlRemoveSearchFeature()) {
  $admin->print_error($dbSample->getError()); 
}
// delete table for sample_dbConnect
if (!$dbSample->sqlDeleteTable()) {
  $admin->print_error($dbSample->getError()); 
}

Die Verwendung von dbConnect um einen neuen Datensatz einzufügen wird in der add.php im Verzeichnis /sample demonstriert:

// create a new instance of sample_dbConnect();
$dbSample = new sample_dbConnect();
// create a new sample record
$data = array();
$data['section_id']     = $section_id;
$data['page_id']        = $page_id;
$data['simple_text']    = 'simple text sample...';
$data['html_text']      = '<p><em>HTML</em> text <strong>sample</strong>...</p>';
$data['last_modified']  = time();
// insert the new record into the sample_dbConnect table
if (!$dbSample->sqlInsertRecord($data)) {
  $admin->print_error($dbSample->getError()); 
}

Wenn Sie einen Datensatz auswählen möchten, gehen Sie wie folgt vor:

// tell dbConnect which fields should be selected
$where = array();
$where['section_id'] = $section_id;
// create an empty record which should contain the referenced data from table...
$data = array();
if (!$dbSample->sqlSelectRecord($where, $data)) {
  // error while executing SQL, prompt error...
  $admin->print_error($dbSample->getError()); 
}
if (sizeof($data) < 1) {
  // error: no data for this $section_id...
  $admin->print_error(sprintf(dbc_error_no_data, $section_id)); 
}

Wenn dbConnect ein SQL Abfrageergebnis zurückliefert geschieht dies grundsätzlich über ein referenziertes Array, wie zum Beispiel in der Funktion sqlSelectRecord():

   /**
     * SELECT record(s) matching to $where. Return records in $result,
     * $where must be transmitted as array in the form:
     * array("field_1" => "value_1", "field_2" => "value_2" [...]).
     * If $where is empty function return all records in table
     *
     * @param ARRAY $where
     * @param REFERENCE ARRAY $result
     * @return BOOL
     */
    public function sqlSelectRecord($where = array(), &$result = array()) {

Sie kennen nun bereits alle Grundfunktionen von dbConnect und können beginnen, die Klasse in Ihren eigenen Modulen einzusetzen.

Der folgende Abschnitt zeigt Ihnen ein paar zusätzliche Funktionen von dbConnect.

Zusätzliche Funktionen von dbConnect

Zusätzliche Funktionen von dbConnect

Gelegentlich werden Sie das SQL Abfrageergebnis in sortierter Form benötigen, hierzu verwenden Sie sqlSelectRecordOrderBy() anstatt sqlSelectRecord():

    /**
     * SELECT record(s) matching to $where ORDER BY $orderBy.
     * Return records in $result, $where must be transmitted as array in the form:
     * array("field_1" => "value_1", "field_2" => "value_2" [...]).
     * If $where is empty function return all records in table
     * $orderBy must be transmitted as simple array, containing the fieldnames.
     *
     * @param ARRAY $where
     * @param REFERENCE ARRAY $result
     * @param ARRAY $orderBy
     * @param BOOL $ascending
     * @return BOOL
     */
    public function sqlSelectRecordOrderBy($where, &$result, $orderBy, $ascending=true)

Die Sortierung erfolgt in der Reihenfolge der Felder, die Sie über das Array $orderBy festlegen.

Angenommen Sie haben eine Adressdatei und suchen alle Personen mit dem Nachnamen "Schmitt". Die Ausgabe soll nach Vorname und PLZ sortiert erfolgen:

$adressen = new dbAdressen();
$where = array();
$where['nachname'] = 'Schmitt';
$result = array();
$orderBy = array('Vorname', 'PLZ');
if (!$adressen->sqlSelectRecordOrderBy($where, $result, $orderBy)) {
  echo $adressen->getError(); }
print_r($result);

Um eine Beschreibung der Datenbanktabelle zu erhalten, z.B. beim Durchführen von Module Upgrades, verwenden Sie dei Funktion sqlDescribeTable():

    /**
     * DESCRIBE Table, returns $result ARRAY with fields:
     * [Field], [Type], [Null], [Key], [Default] and [Extra]
     * for each entry
     *
     * @param REFERENCE ARRAY $result
     * @return BOOLEAN
     */
    public function sqlDescribeTable(&$result)

Im Fall von Fehlern und während der Entwicklung von neuen Anwendungen ist es hilfreich, die SQL Abfrage, die von dbConnect an den Datenbankserver gesendet wird zu überprüfen. Um dies zu erreichen verwenden Sie die Funktion getSQL() um die vollständige Abfrage zu erhalten:

if (!$dbSample->sqlSelectRecord($where, $data)) {
  // error while executing SQL, prompt error...
  echo sprintf('<p>dbConnect Error: %s</p><p>SQL Query: %s</p>', $dbSample->getError(), $dbSample->getSQL()); 
}

Darüber hinaus können Sie dbConnect in einen Simulationsmodus umschalten. In diesem Fall erzeugt dbConnect die SQL Abfrage, führt sie aber nicht aus:

// switch simulation mode ON
$dbSample->simulation(true);
if (!$dbSample->sqlSelectRecord($where, $data)) {
  // error while executing SQL, prompt error...
  echo $dbSample->getError(); 
}
// Show the SQL query in any case:
echo $dbSample->getSQL();

Wenn Ihnen eine SQL Abfrage fehlt, verwenden Sie einfach die Funktion sqlExec() und übergeben ihr die gewünschte SQL Abfrage:

    /**
     * Execute $sqlCode and return $result if possible
     *
     * @param STRING $sqlCode
     * @param REFERENCE ARRAY $result
     * @return BOOLEAN
     */
    public function sqlExec($sqlCode, &$result)

Sie sehen: nichts ist unmöglich

Vielen Dank für Ihr Interesse!

Die aktuelle Version finden Sie auf der Download Seite.

dbConnect wurde durch dbConnect_LE ersetzt!