Das Attribut NoDiscard

(PHP 8 >= 8.5.0)

Einführung

Dieses Attribut kann verwendet werden, um zu kennzeichnen, dass der Rückgabewert einer Funktion oder Methode nicht verworfen werden sollte. Wenn der Rückgabewert in keiner Weise verwendet wird, wird eine Warnung ausgegeben.

Dies ist nützlich bei Funktionen, bei denen die fehlende Prüfung des Rückgabewerts wahrscheinlich ein Fehler ist.

Um den Rückgabewert einer solchen Funktion absichtlich zu verwerfen, kann ein (void)-Cast verwendet werden, um die Warnung zu unterdrücken.

Hinweis: Da Attribute auf Abwärtskompatibilität ausgelegt sind, kann #[\NoDiscard] auch dann zu Funktionen und Methoden hinzugefügt werden, wenn PHP 8.4 oder älter unterstützt werden muss; es hat dann lediglich keine Wirkung. Unter PHP 8.5 und neuer wird eine Warnung ausgegeben, wenn das Ergebnis unbenutzt bleibt. Um die Warnung ohne Verwendung von (void) zu unterdrücken, das vor PHP 8.5 nicht unterstützt wird, kann beispielsweise eine Variable wie $_ verwendet werden.

Klassenbeschreibung

#[\Attribute]
final class NoDiscard {
/* Eigenschaften */
public readonly ?string $message;
/* Methoden */
public function __construct(?string $message = null)
}

Eigenschaften

message
Eine optionale Meldung, die erklärt, warum der Rückgabewert nicht verworfen werden sollte.

Beispiele

Beispiel #1 Grundlegende Verwendung

<?php

/**
* Verarbeitet alle angegebenen Elemente und gibt ein Array mit den
* Ergebnissen der Operation für jedes Element zurück. `null` bedeutet
* Erfolg und eine Exception bedeutet einen Fehler. Die Schlüssel des
* Ergebnisarrays entsprechen den Schlüsseln des $items-Arrays.
*
* @param array<string> $items
* @return array<null|Exception>
*/
#[\NoDiscard("da die Verarbeitung einzelner Elemente fehlschlagen kann")]
function bulk_process(array $items): array {
$results = [];

foreach ($items as $key => $item) {
if (\random_int(0, 9999) < 9999) {
// Simuliere das etwas Sinnvolles mit $item passiert,
// was in 99,99 % der Fälle erfolgreich ist.
echo "Verarbeite {$item}", PHP_EOL;
$error = null;
} else {
$error = new \Exception("Verarbeitung von {$item} fehlgeschlagen.");
}

$results[$key] = $error;
}

return $results;
}

bulk_process($items);

?>

Das oben gezeigte Beispiel erzeugt mit PHP 8.5 eine ähnliche Ausgabe wie:

Warning: The return value of function bulk_process() should either be used or intentionally ignored by casting it as (void), da die Verarbeitung einzelner Elemente fehlschlagen kann

Beispiel #2 Rückgabewert absichtlich verwerfen

<?php

#[\NoDiscard]
function some_command(): int {
return 1;
}

// Warnung mit (void) unterdrücken - PHP 8.5+
(void) some_command();

// Für Kompatibilität mit PHP-Versionen vor 8.5 eine temporäre Variable verwenden
$_ = some_command();

?>

Inhaltsverzeichnis