diff --git a/language/predefined/attributes.xml b/language/predefined/attributes.xml index 5167a43ab..a7ca63817 100644 --- a/language/predefined/attributes.xml +++ b/language/predefined/attributes.xml @@ -1,5 +1,5 @@ - + Vordefinierte Attribute @@ -13,6 +13,7 @@ &language.predefined.attributes.attribute; &language.predefined.attributes.allowdynamicproperties; &language.predefined.attributes.deprecated; + &language.predefined.attributes.nodiscard; &language.predefined.attributes.override; &language.predefined.attributes.returntypewillchange; &language.predefined.attributes.sensitiveparameter; diff --git a/language/predefined/attributes/nodiscard.xml b/language/predefined/attributes/nodiscard.xml new file mode 100644 index 000000000..d8aca5faf --- /dev/null +++ b/language/predefined/attributes/nodiscard.xml @@ -0,0 +1,185 @@ + + + + + Das Attribut NoDiscard + NoDiscard + + + +
+ &reftitle.intro; + + 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. + + + + 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. + + +
+ +
+ &reftitle.classsynopsis; + + + + #[\Attribute] + final + NoDiscard + + + &Properties; + + public + readonly + stringnull + message + + + &Methods; + + + + + +
+ +
+ &reftitle.properties; + + + message + + + Eine optionale Meldung, die erklärt, warum der Rückgabewert nicht + verworfen werden sollte. + + + + +
+ +
+ &reftitle.examples; + + Grundlegende Verwendung + + $items + * @return array + */ +#[\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); + +?> +]]> + + &example.outputs.85.similar; + + + + + + Rückgabewert absichtlich verwerfen + + +]]> + + +
+ +
+ &reftitle.seealso; + + Übersicht über die Attribute + +
+ +
+ + &language.predefined.attributes.nodiscard.construct; + +
+ diff --git a/language/predefined/attributes/nodiscard/construct.xml b/language/predefined/attributes/nodiscard/construct.xml new file mode 100644 index 000000000..e8b554330 --- /dev/null +++ b/language/predefined/attributes/nodiscard/construct.xml @@ -0,0 +1,54 @@ + + + + + + NoDiscard::__construct + Erstellt eine neue Instanz des Attributs NoDiscard + + + + &reftitle.description; + + public NoDiscard::__construct + stringnullmessage&null; + + + Erstellt eine neue Instanz von NoDiscard. + + + + + &reftitle.parameters; + + + message + + + Der Wert der Eigenschaft message. + + + + + + +