Manejo de Errores y Excepciones¶

Configuración¶

La configuración de errores se realiza en el archivo config/app.php de tu aplicación. Por defecto, CakePHP utiliza Cake\Error\ErrorTrap y Cake\Error\ExceptionTrap para manejar tanto errores de PHP como excepciones, respectivamente. La configuración de errores te permite personalizar el manejo de errores para tu aplicación. Las siguientes opciones son compatibles:

• errorLevel - int - El nivel de errores que te interesa capturar. Usa las constantes de error de PHP integradas y las máscaras de bits para seleccionar el nivel de error que te interesa. Consulta Advertencias de Obsolescencia para deshabilitar advertencias de obsolescencia.

• trace - bool - Incluir trazas para errores en los archivos de registro. Las trazas se incluirán en el registro después de cada error. Esto es útil para encontrar dónde/cuándo se están generando los errores.

• exceptionRenderer - string - La clase responsable de representar excepciones no capturadas. Si eliges una clase personalizada, debes colocar el archivo para esa clase en src/Error. Esta clase debe implementar un método render().

• log - bool - Cuando es true, las excepciones y sus trazas se registrarán en Cake\Log\Log.

• skipLog - array - Un array de nombres de clases de excepción que no deben ser registrados. Esto es útil para eliminar mensajes de registro comunes pero poco interesantes, como NotFoundExceptions.

• extraFatalErrorMemory - int - Establece el número de megabytes para aumentar el límite de memoria cuando se encuentra un error fatal. Esto permite espacio para completar el registro o el manejo de errores.

• logger (antes de la versión 4.4.0, usa errorLogger) - Cake\Error\ErrorLoggerInterface - La clase responsable de registrar errores y excepciones no controladas. Por defecto, es Cake\Error\ErrorLogger.

• errorRenderer - Cake\Error\ErrorRendererInterface - La clase responsable de representar errores. Se elige automáticamente en función del SAPI de PHP.

• ignoredDeprecationPaths - array - Una lista de rutas compatibles con la sintaxis Glob que deben ignorar errores de obsolescencia. Añadido en la versión 4.2.0

Por defecto, los errores de PHP se muestran cuando debug es true, y se registran cuando debug es false. El manejador de errores fatal se llamará independientemente del nivel de debug o la configuración de errorLevel, pero el resultado será diferente según el nivel de debug. El comportamiento predeterminado para errores fatales es mostrar una página de error interno del servidor (debug deshabilitado) o una página con el mensaje, archivo y línea (debug habilitado).

Advertencias de Obsolescencia¶

CakePHP utiliza advertencias de obsolescencia para indicar cuándo se ha marcado como obsoleta alguna característica. También recomendamos este sistema para su uso en tus plugins y código de aplicación cuando sea útil. Puedes activar advertencias de obsolescencia con deprecationWarning():

deprecationWarning('5.0', 'El método example() está obsoleto. Usa getExample() en su lugar.');

Al actualizar CakePHP o plugins, es posible que te encuentres con nuevas advertencias de obsolescencia. Puedes desactivar temporalmente las advertencias de obsolescencia de varias formas:

1. Usar la configuración Error.errorLevel con E_ALL ^ E_USER_DEPRECATED para ignorar todas las advertencias de obsolescencia.

2. Usar la opción de configuración Error.ignoredDeprecationPaths para ignorar advertencias con expresiones compatibles con la sintaxis Glob. Por ejemplo:

   'Error' => [
       'ignoredDeprecationPaths' => [
           'vendors/company/contacts/*',
           'src/Models/*',
       ],
   ],
   

   Ignoraría todas las advertencias de obsolescencia de tu directorio Models y el plugin Contacts en tu aplicación.

Cambiar el Manejo de Excepciones¶

El manejo de excepciones en CakePHP ofrece varias formas de personalizar cómo se manejan las excepciones. Cada enfoque te brinda diferentes niveles de control sobre el proceso de manejo de excepciones.

1. Escucha eventos Esto te permite recibir notificaciones a través de eventos de CakePHP cuando se han manejado errores y excepciones.

2. Plantillas personalizadas Esto te permite cambiar las plantillas de vista renderizadas como lo harías con cualquier otra plantilla en tu aplicación.

3. Controlador personalizado Esto te permite controlar cómo se renderizan las páginas de excepción.

4. ExceptionRenderer personalizado Esto te permite controlar cómo se realizan las páginas de excepción y el registro.

5. Crea y registra tus propios manejadores Esto te brinda control total sobre cómo se manejan, registran y representan los errores y excepciones. Utiliza Cake\Error\ExceptionTrap y Cake\Error\ErrorTrap como referencia cuando implementes tus manejadores.

Escuchar Eventos¶

Los manejadores ErrorTrap y ExceptionTrap activarán eventos de CakePHP cuando manejan errores. Puedes escuchar el evento Error.beforeRender para ser notificado de los errores de PHP. El evento Exception.beforeRender se desencadena cuando se maneja una excepción:

$errorTrap = new ErrorTrap(Configure::read('Error'));
$errorTrap->getEventManager()->on(
    'Error.beforeRender',
    function (EventInterface $event, PhpError $error) {
        // haz lo que necesites
    }
);

Dentro de un manejador Error.beforeRender, tienes algunas opciones:

• Detener el evento para evitar la representación.

• Devolver una cadena para omitir la representación y usar la cadena proporcionada en su lugar.

Dentro de un manejador Exception.beforeRender, también tienes algunas opciones:

• Detener el evento para evitar la representación.

• Establecer el atributo de datos exception con setData('exception', $err) para reemplazar la excepción que se está representando.

• Devolver una respuesta desde el evento para omitir la representación y usar la respuesta proporcionada en su lugar.

Plantillas Personalizadas¶

El atrapador de excepciones predeterminado representa todas las excepciones no capturadas que tu aplicación genera con la ayuda de Cake\Error\WebExceptionRenderer y tu ErrorController de la aplicación.

Las vistas de página de error están ubicadas en templates/Error/. Todos los errores 4xx usan la plantilla error400.php, y los errores 5xx usan la plantilla error500.php. Tus plantillas de error tendrán las siguientes variables disponibles:

• message El mensaje de la excepción.

• code El código de la excepción.

• url La URL de la solicitud.

• error El objeto de la excepción.

En modo de depuración, si tu error se extiende de Cake\Core\Exception\CakeException, los datos devueltos por getAttributes() se expondrán también como variables de vista.

// dentro de templates/Error/error400.php
$this->layout = 'mi_error';

Controlador Personalizado¶

La clase App\Controller\ErrorController se utiliza para la representación de excepciones de CakePHP para renderizar la vista de la página de error y recibe todos los eventos estándar del ciclo de vida de la solicitud. Al modificar esta clase, puedes controlar qué componentes se utilizan y qué plantillas se representan.

Si tu aplicación utiliza rutas con prefijo, puedes crear controladores de error personalizados para cada prefijo de enrutamiento. Por ejemplo, si tienes un prefijo Admin, podrías crear la siguiente clase:

namespace App\Controller\Admin;

use App\Controller\AppController;
use Cake\Event\EventInterface;

class ErrorController extends AppController
{
    /**
     * Callback beforeRender.
     *
     * @param \Cake\Event\EventInterface $event Evento.
     * @return void
     */
    public function beforeRender(EventInterface $event)
    {
        $this->viewBuilder()->setTemplatePath('Error');
    }
}

Este controlador solo se utilizaría cuando se encuentra un error en un controlador con prefijo y te permite definir lógica/plantillas específicas del prefijo según sea necesario.

ExceptionRenderer Personalizado¶

Si deseas controlar todo el proceso de representación y registro de excepciones, puedes utilizar la opción Error.exceptionRenderer en config/app.php para elegir una clase que representará las páginas de excepciones. Cambiar el ExceptionRenderer es útil cuando quieres cambiar la lógica utilizada para crear un controlador de error, elegir la plantilla o controlar el proceso general de representación.

Tu clase personalizada de ExceptionRenderer debe colocarse en src/Error. Supongamos que nuestra aplicación usa App\Exception\MissingWidgetException para indicar un widget faltante. Podríamos crear un ExceptionRenderer que represente páginas de error específicas cuando se maneja este error:

// En src/Error/AppExceptionRenderer.php
namespace App\Error;

use Cake\Error\WebExceptionRenderer;

class AppExceptionRenderer extends WebExceptionRenderer
{
    public function missingWidget($error)
    {
        $response = $this->controller->getResponse();

        return $response->withStringBody('Oops, ese widget está perdido.');
    }
}

// En config/app.php
'Error' => [
    'exceptionRenderer' => 'App\Error\AppExceptionRenderer',
    // ...
],
// ...

Lo anterior manejaría nuestro MissingWidgetException, y nos permitiría proporcionar lógica de visualización/manejo personalizado para esas excepciones de aplicación.

Los métodos de representación de excepciones reciben la excepción manejada como argumento y deben devolver un objeto Response. También puedes implementar métodos para agregar lógica adicional al manejar errores de CakePHP:

// En src/Error/AppExceptionRenderer.php
namespace App\Error;

use Cake\Error\WebExceptionRenderer;

class AppExceptionRenderer extends WebExceptionRenderer
{
    public function notFound($error)
    {
        // Haz algo con objetos NotFoundException.
    }
}

   // en src/Error/AppExceptionRenderer
   namespace App\Error;

   use App\Controller\SuperCustomErrorController;
   use Cake\Controller\Controller;
   use Cake\Error\WebExceptionRenderer;

   class AppExceptionRenderer extends WebExceptionRenderer
   {
       protected function _getController(): Controller
       {
           return new SuperCustomErrorController();
       }
   }

   // en config/app.php
   'Error' => [
       'exceptionRenderer' => 'App\Error\AppExceptionRenderer',
       // ...
   ],


// ...

Crear tus Propias Excepciones de Aplicación¶

Puedes crear tus propias excepciones de aplicación utilizando cualquiera de las excepciones SPL incorporadas, Exception en sí, o Cake\Core\Exception\Exception. Si tu aplicación contiene la siguiente excepción:

use Cake\Core\Exception\CakeException;

class MissingWidgetException extends CakeException
{
}

Podrías proporcionar errores de desarrollo detallados, creando templates/Error/missing_widget.php. Cuando estás en modo de producción, el error anterior se trataría como un error 500 y usaría la plantilla error500.

Las excepciones que son subclases de Cake\Http\Exception\HttpException, usarán su código de error como código de estado HTTP si el código de error está entre 400 y 506.

El constructor para Cake\Core\Exception\CakeException te permite pasar datos adicionales. Estos datos adicionales se interpolan en el _messageTemplate. Esto te permite crear excepciones ricas en datos que proporcionen más contexto sobre tus errores:

use Cake\Core\Exception\CakeException;

class MissingWidgetException extends CakeException
{
    // Los datos del contexto se interpolan en esta cadena de formato.
    protected $_messageTemplate = 'Parece que falta %s.';

    // También puedes establecer un código de excepción predeterminado.
    protected $_defaultCode = 404;
}

throw new MissingWidgetException(['widget' => 'Puntiagudo']);

Cuando se representa, tu plantilla de vista tendría una variable $widget establecida. Si lanzas la excepción como una cadena o usas su método getMessage(), obtendrás Parece que falta Puntiagudo..

Excepciones Incorporadas para CakePHP¶

use Cake\Http\Exception\NotFoundException;

public function ver($id = null)
{
    $articulo = $this->Articulos->findById($id)->first();
    if (empty($articulo)) {
        throw new NotFoundException(__('Artículo no encontrado'));
    }
    $this->set('articulo', $articulo);
    $this->viewBuilder()->setOption('serialize', ['

use Cake\Network\Exception\NotFoundException;

public function ver($id = null)
{
    $articulo = $this->Articulos->findById($id)->first();
    if (empty($articulo)) {
        throw new NotFoundException(__('Artículo no encontrado'));
    }
    $this->set('articulo', 'articulo');
    $this->viewBuilder()->setOption('serialize', ['articulo']);
}

"La respuesta DEBE incluir un encabezado Allow que contenga una lista de métodos válidos
para el recurso solicitado."

Manejo Personalizado de Errores de PHP¶

Por defecto, los errores de PHP se representan en la consola o en la salida HTML, y también se registran. Si es necesario, puedes cambiar la lógica de manejo de errores de CakePHP con la tuya propia.

namespace App\Error;

use Cake\Error\ErrorLoggerInterface;
use Cake\Error\PhpError;
use Psr\Http\Message\ServerRequestInterface;
use Throwable;

/**
 * Registra errores y excepciones no manejadas en `Cake\Log\Log`
 */
class ErrorLogger implements ErrorLoggerInterface
{
    /**
     * @inheritDoc
     */
    public function logError(
        PhpError $error,
        ?ServerRequestInterface $request,
        bool $includeTrace = false
    ): void {
        // Registra errores de PHP
    }

    /**
     * @inheritDoc
     */
    public function logException(
        ?ServerRequestInterface $request,
        bool $includeTrace = false
    ): void {
        // Registra excepciones.
    }
}

// src/Error/CustomErrorRenderer.php
namespace App\Error;

use Cake\Error\ErrorRendererInterface;
use Cake\Error\PhpError;

class CustomErrorRenderer implements ErrorRendererInterface
{
    public function write(string $out): void
    {
        // enviar el error renderizado al flujo de salida apropiado
    }

    public function render(PhpError $error, bool $debug): string
    {
        // Convertir el error en una cadena de salida.
    }
}