Cómo agregar una página de error 500 en un proyecto PHP

Es muy feo encontrarse con una página tipo

Cuando estás intentando encontrar lo que buscás, ¿cierto?

Es esa sensación de impotencia sobre todo.

Error 500.

Error interno del servidor.

Es la versión digital del «No sos vos, soy yo»…

O peor, algo como:

Ahí directamente te sentirías insultado…

Imaginate que lo mismo sienten los visitantes de tus sitios. O, más probablement, los visitantes de los sitios de tus clientes.

Claro que, por más que intentes, tener un sistema que no falle nunca jamás es bastante difícil. Especialmente cuando éste se haya en las versiones preliminares.

Pero, si bien no es práctico pasar días o meses retrasando la salida a producción hasta estar 120% seguro de que no hay ningún caso de borde escondido acechando detrás de la puerta, algo que va muy bien es hacer de la experiencia de encontrarse ante un error algo menos traumático.

Dependiendo del contexto podés ofrecer algo que cause gracia como:

Pero, más allá de la elegancia de este tratamiento de errores, hay algo muy importante: no dejar al visitante encerrado en un callejón sin salida.

Notá como, en el último ejemplo se preserva el menú desplegable, el link a volver a la página principal y la señal de notificaciones:

Definitivamente, una mejor experiencia, ¿cierto?

La pregunta infaltable: ¿Cómo podrías tener esto en tus aplicaciones?

Veamos algunas alternativas.

Configurar una página de error a través del webserver

La primera forma de lograr esto es usando la configuración del webserver.

La idea es que sea él quien, dependiendo del código HTTP que retorne tu aplicación, redirija el tráfico a un script definido a tal efecto.

Versión Apache

Si tu servidor es Apache podés usar un archivo .htaccess o, si tenés acceso directo a la configuración, hacerlo en la definición de tu VirtualHost.

Se trata de usar la directiva ErrorDocument, por ejemplo:

ErrorDocument 500 http://tudominio.com/errors/500.php

De este modo, cuando tu script principal retorne un código 500 el visitante será redirigido automáticamente al script errors/500.php y, una vez ahí, podés ponerle toda la estética de tu sitio, como si fuera una página más.

Versión NginX

En el caso de NginX la herramienta a usar será error_page:

error_page 500 /errors/500.php

Esta puede ser una solución aceptable, aunque muchas veces es mejor dejar la infraestructura lo más simple posible y manejar toda la funcionalidad desde la aplicación.

Configurar un error handler en php

PHP ofrece una herramienta muy interesante para estos casos: la función set_error_handler

Mediante esta función es posible establecer tu propio callback, el cual será invocado cuando se produzca un error.

Por ejemplo si tuvieras un código como:

<?php

trigger_error("Este es un error personalizado");

Al ejecutarlo verías esta salida:

PHP Notice:  Este es un error personalizado in /home/mauro/error_handler.php on line 3

Al agregarle el error_handler:

<?php

set_error_handler(function( int $errno, string $errstr, ?string $errfile, ?int $errline, array $errcontext = []) : bool {
        echo "Se produjo el error $errno: $errstr";

        return true;
});

trigger_error("Este es un error personalizado");

Y ejecutarlo verías:

Se produjo el error 1024: Este es un error personalizado

Es cierto, la diferencia no es grandiosa… pero eso depende de lo que pongas en el error_handler. Podrías enviar correos, enviar eventos a una cola o incluso, y esta es la parte más interesante, a diferencia de la opción anterior, generar páginas de error específicas para cada situación.

Otro detalle importante: la definición del error_handler deberías tomarla como algo similar al autoload. Es decir, si tu aplicación abarca muchos scripts, esta definición debería realizarse una única vez, en el que actúa como punto de entrada, probablemente index.php.