Skip to content

datenbank-queries.md

Latest commit

 

History

History
712 lines (416 loc) · 18 KB

datenbank-queries.md

File metadata and controls

712 lines (416 loc) · 18 KB

Queries - rex_sql

Queries - rex_sql

Die Klasse rex_sql ist der Datenbankwrapper, über den REDAXO alle Datenbankzugriffe erzeugt und verwaltet. Die Klasse steht dem Entwickler für eigene Datenbankzugriffe zur Verfügung. Es wird empfohlen alle Datenbankzugriffe über diese Klasse vorzunehmen. Sowohl im Frontend als auch im Backend besteht eine aktive Datenbankverbindung, die für die Zugriffe genutzt werden kann.

Syntax

In der rex_sql Klasse werden häufig Parameter in der Form function($query, $params) verwendet. Es wird empfohlen die Werte an den Query über die params zu übergeben.

Beispiel:

$sql = rex_sql::factory();
$sql->setQuery('SELECT name, id FROM rex_article WHERE parent_id = :pid', ['pid'=>5]);

Rückgabewerte

Die meisten Funktionen geben das aktuelle rex_sql Objekt zurück.

getQueryType

getQueryType($qry)

Gibt den Typ der Abfrage $sql zurück oder false wenn die Abfrage keinen Typ enthält.

Mögliche Rückgabewerte sind SELECT, SHOW, UPDATE, INSERT, DELETE, REPLACE, CREATE, CALL, OPTIMIZE oder false. Die Syntax wird nicht geprüft.

datetime

datetime($timestamp = null)

Gibt einen Datumsstring im SQL Datetime Format (Y-m-d H:i:s) aus dem übergebenen Timestamp zurück. Standard ist die aktuelle Zeit.

setDBQuery

setDBQuery($query, array $params = [], array $options = [])

Setzt eine Abfrage ($query) ab und wechselt die DBID falls vorhanden.

Beispiel:

$sql = rex_sql::factory();
$sql->setDBQuery('SELECT id, name FROM rex_article WHERE id > :id',['id'=>5]);

setDebug

setDebug($debug = true)

Schaltet die Debug Funktion von rex_sql ein. Damit wird das rex_sql Objekt bei ausgeführter Query per dump() ausgegeben.

prepareQuery

prepareQuery($qry)

Erstellt aus einer übergebenen SQL Abfrage ein PDO Statement.

execute

execute(array $params = [], array $options = [])

Führt das vorbereitete Statement aus. Im Fehlerfall wird eine Exception vom Typ rex_sql_exception erzeugt. Mit dem Parameter $options kann das Pufferverhalten beeinflusst werden.

$sql = rex_sql::factory();
$sql->prepareQuery('SELECT id, name FROM rex_article WHERE id > :id');
$sql->execute(['id'=>10]);

Das Beispiel setzt eine Abfrage mit Platzhaltern. Die Werte für die Platzhalter werden mit execute übergeben. Damit lässt sich dann beispielsweise eine Abfrage mehrfach verwenden, indem die Parameter verändert werden.

setQuery

setQuery($query, array $params = [], array $options = [])

Setzt die SQL Query, übernimmt die Parameter, setzt das Objekt mit flush zurück und führt das Statement aus.

$res = $sql->setQuery('SELECT id, name FROM rex_article WHERE id > :id',['id'=>10]);

setTable

setTable($table)

Setzt den Tabellennamen und gibt das rex_sql Objekt zurück.

setRawValue

setRawValue($colName, $value)

Setzt den Raw Wert einer Tabelle und gibt das rex_sql Objekt zurück.

setValue

setValue($colName, $value)

Setzt einen einzelnen Wert value für eine Spalte colName und gibt das rex_sql Objekt zurück.

setArrayValue

setArrayValue($colName, array $value)

Setzt den Inhalt eines Arrays value für eine Spalte colName. Der Wert wird per json_encode codiert.

setDateTimeValue

setDateTimeValue($colName, $timestamp)

Formatiert einen timestamp in das SQL Datumsformat und setzt ihn für die Spalte columnName. Das rex_sql Objekt wird zurückgegeben.

setValues

setValues(array $valueArray)

Setzt ein Array als Inhalt. Der Schlüssel des Arrays muss dem passenden Feldnamen der Tabelle entsprechen.

setArrayValue

setArrayValue($colName, array $value)

Ein Array in der Datenbank ablegen. Der Wert von array wird per json_encode codiert. Siehe auch getArrayValue

setDateTimeValue

setDateTimeValue($colName, $timestamp)

Legt in der Spalte $colName einen Timestamp im Format Y-m-d H:i:s ab. Wird in $timestamp kein Wert übergeben, wird der aktuelle Unix Timestamp verwendet.

setValues

setValues(array $valueArray)

Ein assoziatives Array ablegen, wobei die keys den Feldnamen entsprechen, die values den Werten.

$sql->setValues(['vorname'=>'Rupert','nachname'=>'Neudeck']);

hasValues

hasValues()

Gibt true zurück, wenn das rex_sql Objekt Werte enthält, ansonsten false. Es sind keine Parameter erlaubt.

isValueOf

isValueOf($feld, $prop)

Prüft den Wert einer Spalte der aktuellen Zeile ob ein Wert enthalten ist. Wenn für $prop = "" übergeben wird, wird stets true zurückgegeben.

setWhere

setWhere($where, $whereParams = null)

Setzt die WHERE-Bedingung der Abfrage.

$sql->setWhere(['id' => 3, 'field' => '']); ergibt id = 3 AND field = '' $sql->setWhere([['id' => 3, 'field' => '']]); ergibt id = 3 OR field = ''

mit Parameter: $sql->setWhere('myid = :id OR anotherfield = :field', ['id' => 3, 'field' => '']); ergibt myid = 3 OR anotherfield = ''

Es wird nicht empfohlen den gesamten Where-String mit Parametern und Werten zu übergeben: $sql->setWhere('myid="35" OR abc="zdf"'); (deprecated)

getValue

getValue($colName)

Gibt den Wert von colName des aktuellen Datensatzes zurück. Wird für colName kein Wert übergeben, wird ein Fehler vom Typ rex_sql_exception generiert.

Wenn der Name des Feldes in der Form tablename.fieldname übergeben wurde, wird direkt auf den Tabellennamen zugegriffen. Andernfalls versucht die Funktion den Feldnamen in der Abfrage zu finden. Ist dieser nicht eindeutig, wird ein Fehler generiert.

getArrayValue

getArrayValue($colName)

Das in colName abgelegte Array wird per json_decode decodiert und zurückgegeben. Sie auch setArrayValue.

getDateTimeValue

getDateTimeValue($colName)

Gibt den in colName abgelegte als String abgelegten Datum-Zeit Wert als Unix Timestamp zurück. Siehe auch setDateTimeValue.

getRow

getRow($fetch_type = PDO::FETCH_ASSOC)

Gibt den Wert der aktuellen Zeile zurück. Über fetch_type kann festgelegt werden von welchem Typ das Ergebnis ist. So gibt PDO::FETCH_OBJ das Ergebnis als Objekt zurück. Standard ist PDO::FETCH_ASSOC, womit ein assoziatives Array zurückgegeben wird.

hasValue

hasValue($feldname)

Prüft, ob eine Spalte vorhanden ist. Gibt true zurück, wenn die Spalte gefunden wurde, flase, wenn sie nicht gefunden wurde. Die Funktion kann auch mit einem vorangestellten Alias aufgerufen werden: tablename.feldname.

in

in(array $values)

Bereitet ein Array von ints und/oder strings vor für den Einsatz in einem mysql IN (...) statement:

$sql = rex_sql::factory();
$sql->setQuery('SELECT * FROM my_table WHERE my_col IN ('.$sql->in(['foo', 'bar']).')');

isNull

isNull($feldname)

Prüft, ob das Feld mit dem Namen feldname null ist. Es wird true oder false zurückgegeben.

getRows

getRows()

Gibt die Anzahl der Zeilen für eine gesetze Abfrage zurück.

getFields

getFields()

Gibt die Anzahl der Spalten für eine gesetze Abfrage zurück.

getWhere

getWhere()

Gibt das aktuelle where Statement zurück.

select

select($fields = '*')

Setzt eine Select-Abfrage auf die aktuelle Tabelle mit dem aktuellen where Statement ab. Die Angabe von fields ist optional, Standard ist *.

update

update()

Setzt eine Update-Anweisung auf die angegebene Tabelle mit den gesetzten Werten (z.B. mit setValue oder setValues) und mit setWhere gesetzten WHERE Parametern ab.

insert

insert()

Setzt eine Insert-Anweisung auf die angegebene Tabelle mit den gesetzten Werten (z.B. mit setValue oder setValues). Bei Verstoß gegen eine NOT NULL Regel wird eine rex_sql_exception ausgelöst.

replace

replace()

Setzt eine Replace-Anweisung auf die angegebene Tabelle mit den gesetzten Werten (z.B. mit setValue oder setValues) und mit setWhere gesetzten WHERE Parametern ab.

delete

delete()

Setzt eine Delete-Anweisung auf die angegebene Tabelle mit den WHERE Parametern ab, die mit setWhere gesetzten wurden.

flush

flush()

Setzt alle Werte auf den Ursprungszustand zurück. Gibt das rex_sql Objekt zurück.

flushValues

flushValues()

Stellt alle Values, die mit setValue oder setValues gesetzt wurden, zurück.

hasNext

hasNext()

Gibt true zurück, wenn das Resultset einen weiteren Datensatz enthält, ansonsten false.

reset

reset()

Setzt den Cursor des Resultsets zurück zum Anfang. Identisch mit rewind.

getLastId

getLastId()

Gibt die letzte InsertId zurück.

getDBArray

getDBArray($query = null, array $params = [], $fetchType = PDO::FETCH_ASSOC)

Lädt das komplette Resultset in ein Array und gibt dieses zurück. Wechselt die DBID, falls vorhanden. Identisch mit getArray.

getArray

getArray($query = null, array $params = [], $fetchType = PDO::FETCH_ASSOC)

Lädt das komplette Resultset in ein Array und gibt dieses zurück. Wechselt die DBID, falls vorhanden. Identisch mit getDBArray.

Beispiel:

$array = rex_sql::factory()->getArray('SELECT * FROM rex_media');

getErrno

getErrno()

Gibt die zuletzt aufgetretene Fehlernummer zurück.

getMysqlErrno

getMysqlErrno()

Gibt die treiberspezifische MySql Fehlernummer zurück.

getError

getError()

Gibt ein Array mit Informationen des zuletzt aufgetretenen Fehlers zurück. Der Aufbau des Arrays entspricht folgendem Muster:

[0] => 5-stelliger Fehlercode
[1] => Fehlernummer des MySQL Treibers
[2] => Fehlerbeschreibung

hasError

hasError()

Prüft, ob ein Fehler aufgetreten ist. Bei einem Rückgabewert von true ist ein Fehler aufgetreten, bei false nicht.

setNewId

setNewId($field, $start_id = 0)

Setzt eine Spalte auf den nächstmöglichen auto_increment Wert. Um zu verhindern, dass das rex_sql Objekt verändert wird, wird in dieser Funktion ein eigenes rex_sql Objekt verwendet.

getFieldnames

getFieldnames()

Gibt die Spaltennamen des Resultsets zurück.

getTablenames

getTablenames()

Gibt die Tabellennamen des Resultsets zurück.

escape

escape($value)

Escaped den übergeben Wert für den DB Query.

escapeIdentifier

escapeIdentifier($name)

Escaped den übergebenen Wert und fügt Backticks am Anfang und am Ende dazu.

Aus "Das sind Backticks: ``" wird "``Das sind Backticks: `````"

addGlobalUpdateFields

addGlobalUpdateFields($user = null)

Standardfelder updatedate und updateuser setzen. updatedate ist der aktuelle Wert von time() als Date Time String (über setDateTimeValue). user ist standardmäßig der Login Name des aktuellen REDAXO Backend User oder ein übergebener String.

addGlobalCreateFields

addGlobalCreateFields($user = null)

Standardfelder createdate und createuser setzen. createdate ist der aktuelle Wert von time() als Date Time String (über setDateTimeValue). user ist standardmäßig der Login Name des aktuellen REDAXO Backend User oder ein übergebener String.

rewind

rewind()

Setzt den Cursor des Resultsets zurück zum Anfang. Identisch mit reset.

current

current()

Gibt das aktuelle rex_sql Objekt zurück.

key

key()

Gibt den aktuellen Wert des Zeigers im Resultset zurück.

next

next()

Setzt den Zeiger im Resultset um einen Datensatz vor.

valid

valid()

Gibt true zurück, wenn das Resultset einen weiteren Datensatz enthält, ansonsten false. Identisch mit hasNext.

showCreateTable

rex_sql::showCreateTable($table, $DBID = 1) (public static)

Erstellt das CREATE TABLE Statement um die Tabelle $table der Datenbankverbindung $DBID zu erstellen. Die Tabelle $table muss vorhanden sein, sonst wird ein Fehler ausgegeben.

showTables (deprecated)

rex_sql::showTables($DBID = 1, $tablePrefix = null) (public static)

Sucht alle Tabellen der Datenbankverbindung $DBID. Falls $tablePrefix gesetzt ist, werden nur dem Prefix entsprechende Tabellen gesucht. Es wird ein Array mit den Namen aller in der Datenbank vorhandenen Tabellen zurückgegeben.

Die Funktion ist seit Version 5.6.2 deprecated. Es wird die Verwendung der nicht statischen Funktion getTablesAndViews empfohlen.

getTables

$sql->getTables($tablePrefix = null)

Sucht alle Tabellen der Datenbankverbindung $DBID. Falls $tablePrefix gesetzt ist, werden nur dem Prefix entsprechende Tabellen gesucht. Als Rüclgabe erhält man ein Array der Tabellennamen.

getTablesAndViews

$sql->getTablesAndViews($tablePrefix = null)

Sucht alle Tabellen der Datenbankverbindung $DBID. Falls $tablePrefix gesetzt ist, werden nur dem Prefix entsprechende Tabellen gesucht. Es wird ein Array mit den Namen aller in der Datenbank vorhandenen Tabellen und Views zurückgegeben. Ersetzt die statische Funktion showTables.

showColumns

rex_sql::showColumns($table, $DBID = 1) (public static)

Gibt ein Array mit den Spalten der Tabelle $table zurück. Die Spalten werden ebenfalls als Array zurückgegeben.

 [
 [0] => [
  "name" => "pid",
  "type" => "int(11)",
  "null" => "NO",
  "key" => "PRI",
  "default" => null,
  "extra" => "auto_increment"
  ],
 [1] => [
  "name" => "id",
  "type" => "int(11)",
  "null" => "NO",
  "key" => "MUL",
  "default" => null,
  "extra" => ""
  ]
]

getServerVersion

getServerVersion($DBID = 1) (public static)

Gibt die Serverversion zurück.

factory

factory($DBID = 1) (public static)

Factory Methode. Erstellt eine neue Instanz des rex_sql Objekte und gibt diese zurück.

Standardmäßig wird auf die im System definierte Datenbankresource zugegriffen, die auch von REDAXO selbst genutzt wird. Optional unterstützt REDAXO eine weitere Datenbankquelle. Die Konfiguration kann in der Datei redaxo/data/core/config.yml eingetragen werden. Diese Datenbank ist dann über $sql2 = rex_sql::factory(2) angesprochen werden.

checkDbConnection

checkDbConnection($host, $login, $pw, $dbname, $createDb = false) (public static)

Prüft die übergebenen Zugangsdaten auf Gültigkeit und legt ggf. die Datenbank an.

Informationen über Datenbank-Version/-Typ einholen

Zusätzlich zu rex_sql::getServerVersion()gibt es zusätzlich zwei nicht-statische Methoden:

$sql->getDbType(): liefert entweder "MySQL" (=== rex_sql::MYSQL) oder "MariaDB" (=== rex_sql::MARIADB) $sql->getDbVersion(): liefert die vereinfachte Version im Format X.Y.Z

Letztere ist vor allem für MariaDB praktisch, da MariaDB vor ihre eigene Version immer "5.5.5-" setzt.

Beispiel

$sql = rex_sql::factory();
$dbVersion = $sql->getDbVersion();
$dbType = $sql->getDbType();

Ich würde die Methoden bei der utf8mb4-Umsetzung nutzen.