Custom PHP Error Handler

error-handler.php

<?php
/**
 * Custom PHP Exception/Error Handler
 *
 * @see debug_error_handler
 *
 * @author Daniel Wilson <hello@danw.io>
 * @since 0.0.1
 */

/**
 * Class WarningException
 *
 * Thrown by the debug_error_handler when handling an E_WARNING exception
 *
 * @see E_WARNING
 * @see ErrorException
 * @see debug_error_handler
 */
class WarningException              extends ErrorException {}

/**
 * Class ParseException
 *
 * Thrown by the debug_error_handler when handling an E_PARSE exception
 *
 * @see E_PARSE
 * @see ErrorException
 * @see debug_error_handler
 */
class ParseException                extends ErrorException {}

/**
 * Class NoticeException
 *
 * Thrown by the debug_error_handler when handling an E_NOTICE exception
 *
 * @see E_NOTICE
 * @see ErrorException
 * @see debug_error_handler
 */
class NoticeException               extends ErrorException {}

/**
 * Class CoreErrorException
 *
 * Thrown by the debug_error_handler when handling an E_CORE_ERROR exception
 *
 * @see E_CORE_ERROR
 * @see ErrorException
 * @see debug_error_handler
 */
class CoreErrorException            extends ErrorException {}

/**
 * Class CoreWarningException
 *
 * Thrown by the debug_error_handler when handling an E_CORE_WARNING exception
 *
 * @see E_CORE_WARNING
 * @see ErrorException
 * @see debug_error_handler
 */
class CoreWarningException          extends ErrorException {}

/**
 * Class CompileErrorException
 *
 * Thrown by the debug_error_handler when handling an E_COMPILE_ERROR exception
 *
 * @see E_COMPILE_ERROR
 * @see ErrorException
 * @see debug_error_handler
 */
class CompileErrorException         extends ErrorException {}

/**
 * Class CompileWarningException
 *
 * Thrown by the debug_error_handler when handling an E_COMPILE_WARNING exception
 *
 * @see E_COMPILE_WARNING
 * @see ErrorException
 * @see debug_error_handler
 */
class CompileWarningException       extends ErrorException {}

/**
 * Class UserErrorException
 *
 * Thrown by the debug_error_handler when handling an E_USER_ERROR exception
 *
 * @see E_USER_ERROR
 * @see ErrorException
 * @see debug_error_handler
 */
class UserErrorException            extends ErrorException {}

/**
 * Class UserWarningException
 *
 * Thrown by the debug_error_handler when handling an E_USER_WARNING exception
 *
 * @see E_USER_WARNING
 * @see ErrorException
 * @see debug_error_handler
 */
class UserWarningException          extends ErrorException {}

/**
 * Class UserNoticeException
 *
 * Thrown by the debug_error_handler when handling an E_USER_NOTICE exception
 *
 * @see E_USER_NOTICE
 * @see ErrorException
 * @see debug_error_handler
 */
class UserNoticeException           extends ErrorException {}

/**
 * Class StrictException
 *
 * Thrown by the debug_error_handler when handling an E_STRICT exception
 *
 * @see E_STRICT
 * @see ErrorException
 * @see debug_error_handler
 */
class StrictException               extends ErrorException {}

/**
 * Class RecoverableErrorException
 *
 * Thrown by the debug_error_handler when handling an E_RECOVERABLE_ERROR exception
 *
 * @see E_RECOVERABLE_ERROR
 * @see ErrorException
 * @see debug_error_handler
 */
class RecoverableErrorException     extends ErrorException {}

/**
 * Class DeprecatedException
 *
 * Thrown by the debug_error_handler when handling an E_DEPRECATED exception
 *
 * @see E_DEPRECATED
 * @see ErrorException
 * @see debug_error_handler
 */
class DeprecatedException           extends ErrorException {}

/**
 * Class UserDeprecatedException
 *
 * Thrown by the debug_error_handler when handling an E_USER_DEPRECATED
 *
 * @see E_USER_DEPRECATED
 * @see ErrorException
 * @see debug_error_handler
 */
class UserDeprecatedException       extends ErrorException {}

/**
 * Custom PHP Exception/Error Handler
 *
 * Allows throwing otherwise recoverable exceptions based on E_* error types
 *
 * To be used whilst debugging ONLY
 *
 *
 * Based on https://www.php.net/manual/en/function.set-error-handler.php#112881 by:
 * @author Elad Yosifon <elad.yosifon@gmail.com>
 *
 * Modified as Gist https://gist.github.com/Danw33/ad4819094e124cfef9b87e7f80e8450e by:
 * @author Daniel Wilson <hello@danw.io>
 *
 * @since 0.0.1
 *
 * @param int    $err_severity Level of the error raised, as an integer.
 * @param string $err_msg      The error message, as a string.
 * @param string $err_file     (Optional) The filename that the error was raised in, as a string.
 * @param int    $err_line     (Optional) The line number the error was raised at, as an integer.
 * @param array  $err_context  (Optional) The symbol table that was active when the error occurred. (Deprecated in PHP 7.2)
 *
 * @return bool|null True when error handled / False to fall back to internal handler
 *
 * @throws CompileErrorException     on E_COMPILE_ERROR
 * @throws CompileWarningException   on E_COMPILE_WARNING
 * @throws CoreErrorException        on E_CORE_ERROR
 * @throws CoreWarningException      on E_CORE_WARNING
 * @throws DeprecatedException       on E_DEPRECATED
 * @throws ErrorException            on E_ERROR
 * @throws NoticeException           on E_NOTICE
 * @throws ParseException            on E_PARSE
 * @throws RecoverableErrorException on E_RECOVERABLE_ERROR
 * @throws StrictException           on E_STRICT
 * @throws UserDeprecatedException   on E_USER_DEPRECATED
 * @throws UserErrorException        on E_USER_ERROR
 * @throws UserNoticeException       on E_USER_NOTICE
 * @throws UserWarningException      on E_USER_WARNING
 * @throws WarningException          on E_WARNING
 */
function debug_error_handler( int $err_severity, string $err_msg, ?string $err_file, ?int $err_line, ?array $err_context ) : ?bool {
	// Error was suppressed with the @-operator, fall back to PHP internal error handler
	if ( 0 === error_reporting() ) { return false; }

	// Log to the configured error_log (usually debug.log)
	error_log(' !!! Debug Error Handler: Caught Error level ' . $err_severity . ' with message "' . $err_msg . '" in "' . $err_file . '" on line ' . $err_line . ' at ' . microtime() . ' !!! ' );

	// Log in NewRelic if available
	if ( extension_loaded('newrelic') ) {
		newrelic_notice_error(...func_get_args());
	}

	// Throw a catchable exception
	switch ( $err_severity ) {
		case E_ERROR:               throw new ErrorException            ($err_msg, 0, $err_severity, $err_file, $err_line);
		case E_WARNING:             throw new WarningException          ($err_msg, 0, $err_severity, $err_file, $err_line);
		case E_PARSE:               throw new ParseException            ($err_msg, 0, $err_severity, $err_file, $err_line);
		case E_NOTICE:              throw new NoticeException           ($err_msg, 0, $err_severity, $err_file, $err_line);
		case E_CORE_ERROR:          throw new CoreErrorException        ($err_msg, 0, $err_severity, $err_file, $err_line);
		case E_CORE_WARNING:        throw new CoreWarningException      ($err_msg, 0, $err_severity, $err_file, $err_line);
		case E_COMPILE_ERROR:       throw new CompileErrorException     ($err_msg, 0, $err_severity, $err_file, $err_line);
		case E_COMPILE_WARNING:     throw new CompileWarningException   ($err_msg, 0, $err_severity, $err_file, $err_line);
		case E_USER_ERROR:          throw new UserErrorException        ($err_msg, 0, $err_severity, $err_file, $err_line);
		case E_USER_WARNING:        throw new UserWarningException      ($err_msg, 0, $err_severity, $err_file, $err_line);
		case E_USER_NOTICE:         throw new UserNoticeException       ($err_msg, 0, $err_severity, $err_file, $err_line);
		case E_STRICT:              throw new StrictException           ($err_msg, 0, $err_severity, $err_file, $err_line);
		case E_RECOVERABLE_ERROR:   throw new RecoverableErrorException ($err_msg, 0, $err_severity, $err_file, $err_line);
		case E_DEPRECATED:          throw new DeprecatedException       ($err_msg, 0, $err_severity, $err_file, $err_line);
		case E_USER_DEPRECATED:     throw new UserDeprecatedException   ($err_msg, 0, $err_severity, $err_file, $err_line);
	}

	// Don't execute PHP internal error handler
	return true;
}
set_error_handler('debug_error_handler');