PdoEngine Documentation

Latest PdoEngine version: 1.1

Inhalt

Wichtiger Hinweis

Dieses Projekt ist nur aus Übungszwecken entstanden. Ich stelle es hier trotzdem öffentlich zur Verfügung. Für eine professionelle Lösung ist diese Library nicht geeignet.

Requirements

Diese Library baut auf der PDO Klasse auf und verwendet Prepared Statements für die Abfragen. Vergewissere dich also das du die PDO Extension aktiviert hast.

PHP: 7+

MySQL: 5.7+

Dateien

Die PdoEngine besteht aus folgenden Dateien:

Verzeichnis Dateiname Kurze Beschreibung
root autoload.php Der Autoloader
readme.html Diese Dokumentation, die du gerade ließt
/src/ Config.php Konfigurationsklasse
Connection.php Baut eine PDO Verbindung auf
PdoEngine.php Die Standardklasse der Library
PdoEngineBuilder.php Baut aus den gegeben Informationen eine Abfrage
PdoEngineStatement.php Führt Querys aus und gibt Ergebnisse zurück

Namespace

Alle Klassen befinden sich im Namespace Moritz\PdoEngine

Installation

Zuerst muss der Autoloader includet werden.

<?php

include 'path/to/pdoengine/autoload.php';

Anschließend empfiehlt es sich den Namespace durch dass use Schlüsselwort einzubinden. Dannach kann ein Objekt der PdoEngine instanziiert werden.

use Moritz\PdoEngine\PdoEngine;

$engine = new PdoEngine();

Wichtig zu erwähnen ist, dass es völlig normal ist wenn du nun einen Error bekommst. Der Error entsteht, weil der Konstruktor der PdoEngine beim instanziieren versucht eine Datenbankverbindung herzustellen.

Als kleinen Test kannst du dir nun einmal PdoEngine::VERSION ausgeben lassen.

Datenbank verknüpfen

Nachdem du die PdoEngine erfolgreich installiert hast, kannst du eine Datenbank verknüpfen

Es gibt zwei Wege eine Datenbankverknüpfung herzustellen. Der erste und deutlich einfachere Weg ist, die Datenbankinformationen einfach als Array dem Konstruktor zu übergeben.

$engine = new PdoEngine([
    'name' => 'dein_datenbankname',
    'username' => 'dein_datenbank_username',
    'password' => 'dein_datenbank_passwort',
    'host' => 'dein_datenbank_host',
]);

Wenn ein Parameter nicht übergeben wird, wird Automatisch der Standardwert genommen.

Der zweite Weg ist die Standardwerte in der Config.php (siehe Dateien) auszutauschen. Die folgende Tabelle zeigt alle möglichen, zu übergebenden Werte und deren Standardwert

Wert Standardwert Kurze Beschreibung
name 'database' Datenbank-Name
username 'username' Datenbank-Nutzername
host 'localhost' Datenbank-Host
password 'password' Datenbank-Passwort
charset 'utf8' Verbindungskollation
fetch_mode PDO::FETCH_OBJ Abrufmodus

Tabelle wählen

Bevor die ersten Abfragen gemacht werden können, muss PdoEngine noch wissen welche Tabelle ihr überhaupt abfragen wollt.

$engine->setTable('meine_tabelle');

//alternativ geht auch

$engine->table('meine_tabelle');

//beide schreibweisen bewirken dasselbe

Die Methode hat die eigene Klasse als Rückgabewert und kann somit verkettet werden.

Datenbank Querys

SELECT Query

Ein SELECT Query kann über die Methode get() oder select() ausgeführt werden.

Beispiel:

$result = $engine->table('users')->get(1);

Dieses Beispiel gibt nun alle Einträge der Tabelle users aus, welche die id 1 haben.

Weitere Konditionen können wie folgt als Array mitgegeben werden:

$engine->setTable('users');

// gibt alle User mit dem Vornamen John und dem Nachnamen Doe zurück
$result1 = $engine->select([
    'firstname' => 'John',
    'lastname' => 'Doe'
]);

// gibt nur den ersten User mit dem Username John zurück
$result2 = $engine->limit(1)->get([
    'username' => 'John'
]);

// gibt alle User zurück
$result3 = $engine->get();

Der Parameter der get() Methode kann sowohl ein einfacher String bzw. Integer als auch ein Array sein. Falls er ein String bzw. Integer ist, geht PdoEngine automatisch von der id Zeile aus. Die Standardzeile für die id kann in der Config.php verändert werden. Falls der Parameter ein Array ist, interpretiert PdoEngine den Key als Zeile und den Value als Zeilenwert. Der Parameter kann auch null betragen oder weggelassen werden. In dem Fall werden alle Einträge zurückgegeben.

INSERT INTO Query

Ein INSERT INTO Query kann über die Methode post() oder insert() ausgeführt werden.

Beispiel:

$params = [
    'username' => 'xxMustermannPVP_HDxx',
    'firstname' => 'Max',
    'lastname' => 'Mustermann',
    'created' => date('Y-m-d H:i:s')
];

$engine->table('users')->post($params);

Dieses Beispiel erstellt einen neuen Eintrag in der Tabelle users mit den in $params definierten werten. Auch hier interpretiert PdoEngine wieder den Key als Zeile und den Value als Zeilenwert. Da sie Id meißt durch ein Auto Increment gesetzt wird, ist sie in diesem Beispiel nicht dabei.

Der Rückgabewert dieser Methode ist ein Boolean. Sein Wert ist true wenn die Abfrage erfolgreich war. Sein Wert ist false wenn die Abfrage fehlschlug.

UPDATE Query

Ein UPDATE Query kann über die Methode patch() oder update() ausgeführt werden.

Beispiel:

$update = [
    'username' => 'JohnDoe23',
    'firstname' => 'John',
    'lastname' => 'Doe'
];

$engine->table('users');
$engine->patch($update, 1);

In diesem Beispiel wird der User mit der id 1 bearbeitet und bekommt die Werte, die in der $update Variable stehen, zugewiesen. PdoEngine interpretiert den Key als Zeile und den Value als Zeilenwert.

Beim Aufruf der patch() Methode können 2 Parameter übergeben werden. Der erste Parameter definiert die auszutauschenden Werte und der zweite Parameter dir Konditionen.

// setzt das Passwort vom User JohnDoe23 mit der Id 1 auf cool_new_password

$engine->table('users')->patch([
    'password' => 'cool_new_password',
], [
    'id' => 1,
    'username' => 'JohnDoe23'
]);


// andere schreibweise, selbes ergebnis

$new_values = array('password' => 'cool_new_password');
$where = array('id' => 1, 'username' => 'JohnDoe23');

$engine->setTable('users')->update($new_values, $where);

Der erste Parameter der patch() Methode ist immer ein Array. Der zweite Parameter hingegen kann sowohl ein String bzw. Integer als auch ein Array sein. Falls er ein String bzw. Integer ist, geht PdoEngine automatisch von der id Zeile aus. Falls er ein Array ist, interpretiert PdoEngine den Key als Zeile und die Value als Zeilenwert. Der zweite Parameter kann auch null sein oder weggelassen werden. In dem Fall werden alle Einträge bearbeitet.

Der Rückgabewert dieser Methode ist ein Boolean. Sein Wert ist true wenn die Abfrage erfolgreich war. Sein Wert ist false wenn die Abfrage fehlschlug.

DELETE FROM Query

Ein DELETE FROM Query kann über die Methode delete() ausgeführt werden.

Beispiel:

$engine->setTable('users');

// löscht den User mit der Id 1
$engine->delete(1);

// löscht alle User mit dem Username JohnDoe23
$engine->delete([
    'username' => 'JohnDoe23',
]);

// löscht alle User
$engine->delete();

Der Rückgabewert dieser Methode ist ein Boolean. Sein Wert ist true wenn die Abfrage erfolgreich war. Sein Wert ist false wenn die Abfrage fehlschlug.

Fetch Mode ändern

Der Fetch Mode kann zwischen Objekt und Array gewechselt werden.

// fetch mode Objekt
$engine->fetchMode('obj');
$engine->fetchMode('object');

// fetch mode Array
$engine->fetchMode('arr');
$engine->fetchMode('array');

Die Methode hat die eigene Klasse als Rückgabewert und kann somit verkettet werden.

Ergebnisse eingrenzen

Bei einem SELECT Query kann mit der limit() Methode ein Limit an Ergebnissen gesetzt werden.

$engine->setTable('users');

// Gibt nur den ersten Eintrag zurück
$engine->limit(1)->get();

// Gibt ab Eintrag 5 nur die nächsten 8 Einträge aus
$engine->limit(5, 8)->get();

Wichtig ist, dass die limit() Methode vor der get() Methode aufgerufen wird.

Um das Limit wider zu entfernen, muss der Parameter null sein oder weggelassen werden.

$engine->limit();

Die Methode hat die eigene Klasse als Rückgabewert und kann somit verkettet werden.

Ergebnisse sortieren

Bei einem SELECT Query können Ergebnisse mit der orderBy() oder der order() Methode sortiert werden.

$engine->setTable('users');

// es wird Alphabetisch nach der Spalte username sortiert
$engine->orderBy('username')->get();

// es wird Abwärtsortierend nach der id sortiert
$engine->order('id', 'desc')->get();

// es wird primär abwärtsortierend nach id sortiert
// sekundär aufwärtssortierend nach dem username sortiert
$engine->orderBy([
    'id' => 'desc',
    'username' => 'asc'
])->get();

Der erste Parameter dieser Methode kann ein String oder ein Array sein.
Wenn der erste Parameter ein String ist und der zweite Parameter nicht gegeben ist, so wird die Zeile im ersten Paremeter aufwärtssortierend sortiert. Wenn der erste Parameter ein String ist und der zweite Parameter gegeben ist, so wird die Zeile im ersten Paremeter nach der Sortierungsmethode im zweiten Parameter sortiert. Wenn der erste Parameter ein Array ist, wird beim Key von der zu sortierenden Zeile und bei der Value von der Sortierungsmethode ausgegangen.

Wichtig ist, dass die orderBy() Methode vor der get() Methode aufgerufen wird.

Um die Sortierung wieder zu entfernen, muss der erste Parameter null sein oder weggelassen werden.

$engine->orderBy();

Die Methode hat die eigene Klasse als Rückgabewert und kann somit verkettet werden.

Alle Methoden

Folgende Tabelle zeigt alle Methoden.

Methode Parameter Rückgabewert Kurze Beschreibung
setTable($table) table: string PdoEngine Objekt Abzufragende Tabelle setzen
fetchMode($mode) mode: ['obj'|'object'|'arr'|'array'] PdoEngine Objekt Abrufmodus ändern
options($option[, $value]) option: [string|array]
value: string
PdoEngine Objekt Mehrere Optionen oder eine spezielle Option der Datenbankverbindung ändern
orderBy([$column[, $sort]]) column: [array|string]
sort: string
PdoEngine Objekt Ergebnisse sortieren
limit([$start[, $step]]) start: int
step: int
PdoEngine Objekt Ergebnisse eingrenzen
get([$params]) params: [string|array] Array Informationen aus der Datenbank lesen
post([$params]) params: [string|array] Boolean Informationen in die Datenbank einfügen
patch([$params[, $conds]]) params: array
conds: [string|array]
Boolean Informationen in der Datenbank bearbeiten
delete([$params]) params: [string|array] Boolean Informationen aus der Datenbank löschen
lastInsertId([$name]) name: string String Id des zuletzt eingefügten Datensatzes bekommen

Alias Methoden

Folgende Tabelle zeigt alle Alias Methoden.

Alias Methode
table() setTable()
fetch() fetchMode()
order() orderBy()
select() get()
insert() post()
update() patch()