Meilleures pratiques: Utilisation de @throws en php-doc, et comment il pourrait en être de la poignée

Disons que j'ai une classe avec une méthode comme ceci:

/*
 *
 * Loads the user from username.
 *
 * @param string $username The username
 *
 * @return UserInterface
 *
 * @throws userNotFoundException if the user is not found
 */
public function getUser($username)
{
    //someFunction return an UserInterface class if found, or null if not.
    $user = someFunction('SELECT ....', $username);
    if ($user === null) {
        throw new userNotFoundException();
    }

    return $user
}

Maintenant, disons que someFunction pourrait jeter une InvalidArgumentException /RuntimeException /PDOException pour XYZ raisons. Que dois-je faire? Et ce n'est pas?

Numéro 1

Ajouter toutes les exceptions possibles qui pourraient jeter someFunction en php-docs.

/*
 *
 * Loads the user from username.
 *
 * @param string $username The username
 *
 * @return UserInterface
 *
 * @throws userNotFoundException if the user is not found
 * @throws InvalidArgumentException
 * @throws ...
 */

Numéro 2

Ajouter un bloc try-catch pour s'assurer que la méthode doit lancer des exceptions documentée

/*
 *
 * Loads the user from username.
 *
 * @param string $username The username
 *
 * @return UserInterface
 *
 * @throws userNotFoundException if the user is not found
 * @throws RuntimeException 
 */
public function getUser($username)
{
    try {
        $user = someFunction('SELECT ....', $username);
    } catch (Exception $e) {
        throw new RuntimeException();
    }

    if ($user === null) {
        throw new userNotFoundException();
    }

    return $user
}

Numéro 3

Ne pas faire n'importe quoi.

  • Quelle est la différence de Nombre1 et Nombre2 en ce qui concerne la documentation? Êtes-vous demander à propos de les meilleures pratiques pour la documentation ou de la manipulation de l'exception?
  • Je dirais à la fois..
InformationsquelleAutor Federkun | 2013-03-23
  1. 12

    Personnellement je considère le traitement de @throws similaire à Java est cochée, les exceptions

    La façon dont cela fonctionne en Java c'est qu'au fond les exceptions qui héritent de RuntimeException peut être jeté et n'ont pas à être traitées. D'autres types d'exceptions doit avoir un bloc try-catch pour gérer. Ce code de gestion doit être en l'appelant.

    Essentiellement en PHP un peu comme ceci:

    Lorsqu'une méthode d'une @throws d'annotation, vous ont pour ajouter du code pour gérer les exceptions.

    Toutes les exceptions qui ne sont pas mentionnés sont en option pour le traitement dans le code appelant.

    Maintenant, je ne suis pas 100% suivre ce principe moi-même. L'ensemble de la gestion des exceptions chose est une sorte de au programmeur de préférence, mais c'est juste quelques pensées sur la façon dont je pense qu'il peut être manipulé d'une façon raisonnable.

    • oui, j'ai été à la recherche de la façon dont il pourrait être manipulé", merci pour le partage! Ainsi, le code d'origine que j'ai présenté devrait être bon, non? Si someFunction jeter aucune exception, qui doivent être traitées par l'application de la poignée
    • Yep, semble ok. Cependant, gardez à l'esprit que les exceptions ne doivent pas être utilisés pour le contrôle de flux. Je ne sais pas si votre code est juste un exemple, mais il me semble que si un utilisateur n'est pas trouvé serait un scénario commun, qui vous aurait généralement besoin de gérer - ainsi, il serait plus judicieux de rendre explicite, en retournant une valeur null.
    InformationsquelleAutor Jani Hartikainen
  2. 9

    En ce qui concerne la documentation, si une fonction explicitement déclenche une exception, alors il devrait être inclus dans la fonction de documentation. Ainsi, pour chaque throw déclaration, il devrait y avoir un correspondant @throws dans la documentation de PHP.

    en ce qui concerne la manipulation, s'il y a des opérations qui doivent être exécutées lorsque l'exception est levée, puis l'attraper. Sinon, laisser bouillonner -- à condition qu'il existe un catch déclaration de l'intention de traiter plus tard.

    Mise à jour:

    Quelques années plus tard, j'ai changé d'avis que l'on doit seulement faire une exception "bubble up" non modifiée lorsque l'exception est toujours pertinent pour le module de niveau d'abstraction. Les attraper et de les re-jeter des stratégies devraient être utilisées pour faire de l'exception plus de sens. Elle doit également faire d'erreur de manipulation plus sûre en évitant d'inutiles divulgation d'informations sur les modules sous-jacents à l'abstraction.

    /**
 * @throws UserNotFoundException
 */
public function getUser($username)
{
    try {
        $user = someFunction('SELECT ....', $username);
    } catch (DatabaseException $dbe) {

        /* Re-throw since a database exception may no longer be
         * meaningful to the caller.
         */
        throw new UserNotFoundException();
    }

    return $user
}
    • Votre mise à jour, c'est bien, je pense que c'est bénéfique pour distinguer aussi défauts et éventualités, où éventualités serait documentée, mais pas les défauts. Défauts naturellement bulle jusqu'à une sorte de faute de frontière (p. ex., application de niveau supérieur), où ils sont traités en tant que de besoin (transformé, ingestion, connecté, fuite, etc). Otoh, que, imprévus font partie d'un module d'interface et devrait donc être significatif pour l'appelant. Simplement bouillonnement éventualités est une forme de fuite de détails de mise en œuvre.
    InformationsquelleAutor Czar Pino
  3. 6

    À partir d'une documentation de maintenance de point de vue, je voudrais seulement ajouter de la @jeter lignes pour les exceptions qui sont spécifiquement jeté sinon, vous obtiendrez rapidement votre documentation de la date.

    InformationsquelleAutor acutesoftware
  4. 0

    Numéro deux, mais peut-être jeter avant de revenir depuis que jeter des actions se fera avant un retour...

    InformationsquelleAutor tfont