L'attribut NoDiscard

(PHP 8 >= 8.5.0)

Introduction

Cet attribut peut être utilisé pour indiquer que la valeur de retour d'une fonction ou d'une méthode ne doit pas être ignorée. Si la valeur de retour n'est utilisée d'aucune manière, un avertissement sera émis.

Cela est utile pour les fonctions où ne pas vérifier la valeur de retour est probablement un bogue.

Pour ignorer intentionnellement la valeur de retour d'une telle fonction, il est possible d'utiliser le cast (void) pour supprimer l'avertissement.

Note: Étant donné que les attributs sont conçus pour être rétrocompatibles, #[\NoDiscard] peut être ajouté aux fonctions et méthodes même lorsque PHP 8.4 ou inférieur est supporté, il ne fera simplement rien. Sur PHP 8.5 et supérieur, un avertissement sera émis si le résultat n'est pas utilisé. Pour supprimer l'avertissement sans utiliser (void), qui n'est pas supporté avant PHP 8.5, il est possible d'utiliser une variable comme $_.

Note: #[\NoDiscard] s'applique à la déclaration de fonction ou de méthode spécifique sur laquelle il est écrit, et l'avertissement est émis en fonction de la déclaration réellement appelée. Par conséquent, ajouter #[\NoDiscard] à une méthode d'interface ou à une méthode abstraite n'émet pas d'avertissement, car la méthode invoquée est la méthode d'implémentation ou de redéfinition. De même, une méthode qui redéfinit une méthode #[\NoDiscard] n'émet pas l'avertissement à moins d'être elle-même marquée avec l'attribut. À l'inverse, une méthode importée depuis un trait conserve l'attribut, car la méthode du trait est copiée dans la classe utilisatrice comme si elle y était déclarée.

Synopsis de la classe

#[\Attribute]
final class NoDiscard {
/* Propriétés */
public readonly ?string $message;
/* Méthodes */
public function __construct(?string $message = null)
}

Propriétés

message
Un message optionnel expliquant pourquoi la valeur de retour ne doit pas être ignorée.

Exemples

Exemple #1 Utilisation basique

<?php

/**
 * Traite tous les éléments donnés et retourne un tableau avec les résultats de
 * l'opération pour chaque élément. `null` indique un succès et une Exception
 * indique une erreur. Les clés du tableau de résultat correspondent aux clés du tableau $items.
 *
 * @param array<string> $items
 * @return array<null|Exception>
 */
#[\NoDiscard("as processing might fail for individual items")]
function bulk_process(array $items): array {
    $results = [];

    foreach ($items as $key => $item) {
        if (\random_int(0, 9999) < 9999) {
            // On prétend faire quelque chose d'utile avec $item,
            // ce qui réussira dans 99,99% des cas.
            echo "Processing {$item}", PHP_EOL;
            $error = null;
        } else {
            $error = new \Exception("Failed to process {$item}.");
        }

        $results[$key] = $error;
    }

    return $results;
}

bulk_process($items);

?>

La sortie de l'exemple ci-dessus en PHP 8.5 est similaire à :

Warning: The return value of function bulk_process() should either be used or intentionally ignored by casting it as (void), as processing might fail for individual items

Exemple #2 Ignorer intentionnellement la valeur de retour

<?php

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

// Supprimer l'avertissement avec (void) - PHP 8.5+
(void) some_command();

// Pour la compatibilité avec les versions de PHP antérieures à 8.5, utiliser une variable temporaire
$_ = some_command();

?>

Sommaire