NoDiscard — Klasse · PHP-Referenz

Signatur

#[NoDiscard(string $message = '')]

Beschreibung

Das Attribut #[NoDiscard] kann auf Funktionen, Methoden und Klassen (deren Instanzen als Rückgabewert gelten) angewendet werden, um statischen Analysewerkzeugen und der PHP-Laufzeitumgebung mitzuteilen, dass der Rückgabewert nicht ignoriert werden sollte. Wird der Rückgabewert dennoch verworfen, gibt PHP eine entsprechende Warnung (E_WARNING) aus.

Typische Anwendungsfälle sind Funktionen, bei denen das Ignorieren des Rückgabewerts fast immer ein Programmierfehler ist — zum Beispiel bei Fehlerstatuscodes, Builder-Methoden, die ein neues Objekt zurückgeben, oder Sicherheitsfunktionen wie hash_hmac(). Das Attribut hilft dabei, solche Fehler frühzeitig zu erkennen.

Optional kann dem Attribut eine $message übergeben werden, die in der Warnmeldung erscheint und dem Entwickler einen konkreten Hinweis gibt, warum der Rückgabewert wichtig ist.

Das Attribut ist besonders nützlich in Bibliotheken und Frameworks, um API-Nutzer vor versehentlichem Verwerfen wichtiger Rückgabewerte zu schützen, ohne dabei Breaking Changes einzuführen.

Parameter

Name	Typ	Default	Beschreibung
$message	string	''	Optionale Meldung, die in der PHP-Warnung angezeigt wird, wenn der Rückgabewert verworfen wird. Sollte erklären, warum der Rückgabewert nicht ignoriert werden sollte.

Rückgabewert

Typ

Beispiele

Einfaches NoDiscard-Attribut auf einer Methode

<?php

use NoDiscard;

class QueryBuilder
{
    private array $conditions = [];

    #[NoDiscard('Das neue QueryBuilder-Objekt mit der Bedingung muss verwendet werden.')]
    public function where(string $condition): static
    {
        $clone = clone $this;
        $clone->conditions[] = $condition;
        return $clone;
    }

    public function getSQL(): string
    {
        return 'SELECT * FROM table'
            . (empty($this->conditions) ? '' : ' WHERE ' . implode(' AND ', $this->conditions));
    }
}

$qb = new QueryBuilder();

// Falsch: Rückgabewert wird verworfen — PHP erzeugt eine Warnung
$qb->where('id = 1');
echo $qb->getSQL(); // SELECT * FROM table  (Bedingung fehlt!)

// Korrekt: Rückgabewert wird verwendet
$qb2 = $qb->where('id = 1');
echo $qb2->getSQL(); // SELECT * FROM table WHERE id = 1

Warning: Das neue QueryBuilder-Objekt mit der Bedingung muss verwendet werden. SELECT * FROM table SELECT * FROM table WHERE id = 1

NoDiscard auf einer Funktion mit Fehlercode

<?php

use NoDiscard;

#[NoDiscard('Der Rückgabewert zeigt an, ob die Operation erfolgreich war.')]
function saveData(array $data): bool
{
    // Simuliertes Speichern
    if (empty($data)) {
        return false;
    }
    // ... Datenbankoperation ...
    return true;
}

// Falsch: Rückgabewert wird nicht geprüft — PHP erzeugt eine Warnung
saveData([]);

// Korrekt: Rückgabewert wird ausgewertet
$success = saveData(['name' => 'Max']);
if (!$success) {
    echo 'Fehler beim Speichern!';
} else {
    echo 'Erfolgreich gespeichert.';
}

Warning: Der Rückgabewert zeigt an, ob die Operation erfolgreich war. Erfolgreich gespeichert.

// Wichtig · Fallstricke

Verfügbarkeit: #[NoDiscard] ist ab PHP 8.4.0 verfügbar. In älteren PHP-Versionen wird das Attribut ignoriert oder führt zu einem Fehler, falls die Klasse nicht existiert.

Warnung vs. Fehler: Das Verwerfen eines mit #[NoDiscard] markierten Rückgabewerts erzeugt lediglich eine E_WARNING, keinen fatalen Fehler. Der Code wird weiter ausgeführt, was jedoch zu schwer nachvollziehbaren Bugs führen kann.

Statische Analyse: Werkzeuge wie PHPStan oder Psalm unterstützen möglicherweise eigene Annotationen für diesen Zweck (@return mit Hinweisen). #[NoDiscard] ist die native PHP-Lösung und sollte für neuen Code bevorzugt werden.

Anwendung auf Klassen: Wird #[NoDiscard] auf eine Klasse angewendet, gilt die Warnung für alle Funktionen und Methoden, die eine Instanz dieser Klasse zurückgeben.

Siehe auch

Attribute Deprecated Override