intellij - phpdocumentor download windows

Prácticas recomendadas: uso de @throws en php-doc y cómo podría manejarse

Question

Digamos que tengo una clase con un método como este:

/*
 *
 * 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
}

Ahora digamos que someFunction podría lanzar una InvalidArgumentException / RuntimeException / PDOException por razones XYZ. ¿Qué tengo que hacer? ¿Y qué no?

Numero 1

Agregue todas las excepciones posibles que podrían 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 ...
 */

Número 2

Agregue un bloque try-catch para asegurarse de que el método debe lanzar excepciones SOLO documentadas

/*
 *
 * 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
}

Numero 3

No hagas nada

Answer 1

Con respecto a la documentación, si una función lanza explícitamente una excepción, debe incluirse en la documentación de la función. Por lo tanto, para cada declaración de throw , debe haber un @throws correspondiente en la documentación de PHP.

Con respecto al manejo, si hay algunas operaciones que deben ejecutarse cuando se lanza la excepción, entonces cógela. De lo contrario, déjelo crecer, siempre que haya una instrucción catch que lo maneje más adelante.

Actualizar:

Unos años más tarde, he cambiado a la opinión de que solo se debe permitir que una excepción "salte" sin modificaciones cuando la excepción sigue siendo relevante para el nivel de abstracción del módulo. Las estrategias de captura y relanzamiento deben emplearse para que la excepción sea más significativa. También debería hacer que el manejo de errores sea más seguro al evitar la divulgación innecesaria de información sobre los módulos subyacentes a la abstracción.

/**
 * @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
}

Answer 2

Desde el punto de vista del mantenimiento de la documentación, solo agregaría las líneas @throw para las excepciones que se lanzan específicamente; de ​​lo contrario, rápidamente se quedará obsoleta.

Answer 3

Personalmente, consideraría tratar @throws similar a las excepciones comprobadas de Java

La forma en que esto funciona en Java es que básicamente se pueden lanzar excepciones que heredan de RuntimeException y no tienen que ser manejadas. Cualquier otro tipo de excepción debe tener un bloque try-catch para manejarlas. Este código de manejo debe estar en la persona que llama.

Básicamente en PHP un poco como este:

Cuando un método tiene una anotación @throws , debe agregar código para manejar sus excepciones.

Cualquier excepción que no se mencione es opcional para el manejo en el código de llamada.

Ahora, yo no sigo este principio al 100%. Todo lo relacionado con las excepciones de manejo depende de las preferencias del programador, pero esto es solo una reflexión sobre cómo creo que podría manejarse de una manera razonable.

Answer 4

Número dos , pero quizás lanzar antes de regresar ya que las acciones de lanzamiento ocurrirán antes de una devolución ...