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 $_.

Synopsis de la classe

#[\Attribute]
final class NoDiscard {

/* Propriétés */

public readonly ?string $message;

/* Méthodes */

public __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();

?>

Voir aussi

Vue d'ensemble des attributs

Sommaire

NoDiscard::__construct — Construit une nouvelle instance de l'attribut NoDiscard