expression — Funktion · PHP-Referenz

Signatur

expression(string $expression, mixed ...$values): string

Beschreibung

expression() ist eine Hilfsfunktion im Kontext von Datenbank-Abfrage-Buildern (z. B. Laravel Query Builder / Eloquent), die es ermöglicht, rohe SQL-Ausdrücke zu kapseln und dabei gleichzeitig Werte sicher als gebundene Parameter zu übergeben. So kann man komplexe SQL-Konstrukte (Berechnungen, Funktionsaufrufe, CASE-Ausdrücke) verwenden, ohne auf Prepared Statements verzichten zu müssen.

Der übergebene $expression-String enthält Platzhalter (üblicherweise ?), die durch die nachfolgenden $values ersetzt werden. Die Werte werden dabei nicht direkt in den SQL-String interpoliert, sondern als gebundene Parameter übergeben – das verhindert SQL-Injection-Angriffe.

Typischer Anwendungsfall ist die Übergabe des Rückgabewerts an Methoden wie selectRaw(), whereRaw() oder orderByRaw(), die rohe Ausdrücke akzeptieren. So lassen sich z. B. Datumsfunktionen, Aggregierungen oder mathematische Operationen sicher und lesbar einbetten.

Sicherheit: Werte werden gebunden, nicht konkateniert.
Lesbarkeit: Komplexe SQL-Fragmente bleiben im Code nachvollziehbar.
Flexibilität: Kombination von rohem SQL mit dem Komfort des Query Builders.

Parameter

Name	Typ	Default	Beschreibung
$expression Pflicht	string		Der rohe SQL-Ausdruck als Zeichenkette. Kann Platzhalter (`?`) enthalten, die durch `$values` ersetzt werden.
$values	mixed	[]	Ein oder mehrere Werte, die sicher als gebundene Parameter an den Ausdruck übergeben werden. Die Reihenfolge entspricht den `?`-Platzhaltern im Ausdruck.

Rückgabewert

Typ

string

Beschreibung

Gibt ein Objekt oder eine Zeichenkette zurück, die den gekapselten SQL-Ausdruck mit gebundenen Parametern repräsentiert und direkt in Query-Builder-Methoden verwendet werden kann.

Beispiele

Roher Ausdruck mit gebundenem Parameter in einer WHERE-Klausel

<?php
// Beispiel mit Laravel Query Builder
use Illuminate\Support\Facades\DB;

$minPrice = 100;

$results = DB::table('products')
    ->where(DB::raw('price * quantity'), '>', DB::expression('?', [$minPrice]))
    ->get();

foreach ($results as $row) {
    echo $row->name . PHP_EOL;
}

// Alle Produkte, bei denen price * quantity > 100

Mathematischen Ausdruck sicher in SELECT einbetten

<?php
// Datumsformatierung mit gebundenem Format-Parameter
use Illuminate\Support\Facades\DB;

$format = '%Y-%m';

$results = DB::table('orders')
    ->select(
        'id',
        DB::expression("DATE_FORMAT(created_at, ?)", [$format])
    )
    ->get();

foreach ($results as $row) {
    echo $row->id . ': ' . $row->created_at . PHP_EOL;
}

// 1: 2024-03 // 2: 2024-04

// Wichtig · Fallstricke

Sicherheitshinweis: Auch wenn expression() Werte als gebundene Parameter übergibt, sollte der $expression-String selbst niemals direkt aus Benutzereingaben zusammengesetzt werden – andernfalls droht SQL-Injection. Nur die Werte stammen aus nicht vertrauenswürdigen Quellen, die SQL-Struktur muss immer fest im Code definiert sein.

Framework-Abhängigkeit: expression() ist keine native PHP-Funktion der Standardbibliothek, sondern Teil von Datenbank-Abstraktionsschichten wie Laravel (DB::expression()) oder ähnlichen Query Buildern. Die genaue Signatur und das Verhalten können je nach Framework variieren.

Bei der direkten Verwendung von PDO oder MySQLi stehen die Methoden PDO::prepare() und PDOStatement::bindParam() als natürliche Alternativen zur Verfügung.

Siehe auch

PDO::prepare PDOStatement::bindParam PDOStatement::bindValue PDO::quote