CRUD

Das Akronym CRUD steht für die Operationen Create, Read, Update und Delete, welche den SQL-Befehlen INSERT, SELECT, UPDATE und DELETE entsprechen. Die Models verfügen über Methoden, die diese Funktionalität objektorientiert abstrahieren, wodurch Entwicklern das Schreiben von SQL-Queries erspart bleibt.

Lesender Zugriff

Allgemeine Methoden

Folgende statische Methoden laden Model-Instanzen entweder aus dem Cache oder aus der Datenbank. Es wird also nur dann ein SELECT-Befehl ausgeführt, falls sich die gesuchten Objekte nicht bereits im Cache befinden.

• all() gibt eine Collection mit allen Instanzen eines Models zurück.
• find(int $id) gibt die Model-Instanz mit einer bestimmten id zurück oder null, falls kein Datenbankeintrag mit dieser id existiert.
• findOrFail(int $id) gibt die Model-Instanz mit einer bestimmten id zurück oder wirft eine Exception, falls kein Datenbankeintrag mit dieser id existiert.
• findMany(array $ids) gibt eine Collection von Model-Instanzen mit bestimmten $ids zurück.

use App\Models\Product;

$product = Product::find($id);

Select

Die statische Methode select() gibt eine Instanz der Klasse RHRZ\ORM\SQL\Select zurück, mit der ein SELECT-Befehl gebildet und ausgeführt werden kann. Im Gegensatz zu den Methoden des vorherigen Abschnitts findet bei select() immer eine Datenbankabfrage statt. Erst anschließend wird für jeden geladenen Datensatz geprüft, ob im Cache bereits ein Objekt mit der jeweiligen id existiert. Falls ja, wird die gecachte Model-Instanz in die Rückgabe-Collection aufgenommen, um die Einzigartigkeit zu wahren.

Where-Bedingungen

• where(string $column, mixed $value)
• whereNot(string $column, mixed $value)
• whereNull(string $column)
• whereNotNull(string $column)
• whereIn(string $column, array $values)
• whereNotIn(string $column, array $values)
• whereBetween(string $column, mixed $value1, mixed $value2)
• whereNotBetween(string $column, mixed $value1, mixed $value2)
• whereLike(string $column, mixed $value)
• whereNotLike(string $column, mixed $value)
• whereGreater(string $column, mixed $value)
• whereGreaterOrEqual(string $column, mixed $value)
• whereLess(string $column, mixed $value)
• whereLessOrEqual(string $column, mixed $value)
• whereRaw(string $condition, array $values = [])

Sonstige Methoden

• orderBy(string $order) gibt an, dass die Rückgabe durch das DBMS sortiert werden soll. Der Parameter $order erwartet eine gültige ORDER BY-Klausel bestehend aus Spaltennamen und ASC oder DESC.
• limit(int $limit, int $offset = null) gibt an, dass die Rückgabe durch das DBMS auf $limit Datensätze beschränkt werden soll, gegebenenfalls mit einem $offset.
• withDeleted() gibt an, dass die Abfrage auch Datensätze enthalten soll, die durch Soft-Delete gelöscht wurden.
• onlyDeleted() gibt an, dass die Abfrage ausschließlich Datensätze enthalten soll, die durch Soft-Delete gelöscht wurden.

Ausführen

Folgende Methoden führen den gebildeten SELECT-Befehl aus.

• fetch() gibt eine Collection zurück. Bereits gecachte Model-Instanzen bleiben unverändert, selbst wenn sich der Datenbankeintrag zwischenzeitlich verändert hat.
• refetch() gibt eine Collection zurück. Falls sich Datenbankeinträge zwischenzeitlich verändert haben, werden bereits gecachte Model-Instanzen aktualisiert.
• fetchFirst() gibt die erste Model-Instanz zurück oder null, falls die Abfrage keine Datensätze zurückgeliefert hat.
• fetchMax(string $column = 'id') ist eine Hilfsmethode für
  orderBy($column . ' DESC')->limit(1)->fetchFirst().
• fetchMin(string $column = 'id') ist eine Hilfsmethode für
  orderBy($column . ' ASC')->limit(1)->fetchFirst().

Beispiele

use App\Models\Product;

// select all products in category 1 ordered by descending price
Product::select()->where('category_id', 1)
    ->orderBy('price DESC')->fetch());

// select all products in categories 1, 2, 3
Product::select()->whereIn('category_id', [1, 2, 3])->fetch());

// select all products with a price < 50
Product::select()->whereLess('price', 50)->fetch());

// select the most expensive product
Product::select()->fetchMax('price'));

// select all products with a name starting with "a"
Product::select()->whereLike('name', 'a%')->fetch());

// select all products that don't have a description
Product::select()->whereNull('description')->fetch());

// select all products in categories 1, 2, 3
// with a price < 50 ordered by ascending price
Product::select()->whereRaw('category_id IN ??? AND price < ?',
    [[1, 2, 3], 50])->orderBy('price')->fetch());

Schreibender Zugriff

Insert

Neue Objekte werden über den Konstruktor des Models instanziiert. Nach dem Befüllen mit Daten kann das Objekt mit der Methode save() in der Datenbank persistiert werden. Der ORM generiert dafür einen INSERT-Befehl und setzt die Timestamp-Spalte created_at.

use App\Models\Category;
use App\Models\Product;

$product = new Product();
$product->category = Category::find(1);
$product->name = 'New Product';
$product->description = '...';
$product->price = '49.99';
$product->public = true;
$product->save();

Der für das neue Objekt erzeugte Primärschlüssel ist unmittelbar nach dem Speichern in der Eigenschaft id verfügbar. Erneutes Aufrufen der Methode save() erstellt keine weiteren Einträge in der Datenbank, sondern führt ein Update des existierenden Objekts durch.

Update

Um ein bereits in der Datenbank existierendes Objekt (also ein Objekt mit einer id) zu bearbeiten, wird dieses zunächst geladen. Nach dem Anpassen der Daten wird das Objekt mit der Methode save() gespeichert. Der ORM generiert dafür einen UPDATE-Befehl und setzt die Timestamp-Spalte updated_at.

use App\Models\Product;

$product = Product::find($id);
$product->price = '29.99';
$product->save();

Beim Speichern werden nur die Spalten überschrieben, deren Wert sich seit dem Laden des Objekts verändert hat. Falls keine Werte angepasst wurden, wird kein UPDATE ausgeführt, somit wird auch der Timestamp updated_at nicht aktualisiert.

Delete

Um ein Objekt aus der Datenbank zu entfernen, wird dieses zunächst geladen und dann mit der Methode delete() gelöscht. Der ORM generiert dafür einen DELETE-Befehl, es sei denn für das Model sind Soft-Deletes aktiviert.

use App\Models\Product;

$product = Product::find($id);
$product->delete();

Soft-Delete

Soft-Delete bedeutet, dass Datenbankeinträge bei Aufruf der Methode delete() nicht unwiederbringlich gelöscht werden, sondern lediglich die Timestamp-Spalte deleted_at gesetzt wird. Dies kann dazu beitragen, den versehentlichen Verlust von Daten zu verhindern. Soft-Deletes können in der Methode init des Models aktiviert werden.

$table->setSoftDelete(true);

Bei lesendem Zugriff werden Datenbankeinträge mit einem Wert in der Spalte deleted_at ignoriert, so als wären sie tatsächlich gelöscht worden. Sollen diese Einträge in besonderen Fällen dennoch geladen werden, können bei einem Select die Methoden withDeleted oder onlyDeleted verwendet werden.

Soft-Deletes wirken sich außerdem auf Fremdschlüsselbeziehungen aus, denn je nach Konfiguration der ForeignKeyColumn können referenzierte Objekte ebenfalls nur mit Soft-Delete gelöscht werden.

Restore

Durch Soft-Delete gelöschte Objekte (also Datenbankeinträge mit einem Wert in der Spalte deleted_at), können mit der Methode restore() wiederhergestellt werden. Dabei wird die Spalte deleted_at auf NULL gesetzt.

use App\Models\Product;

$product = Product::find($id);
$product->restore();