{"id":22764595,"url":"https://github.com/kuria/error","last_synced_at":"2025-04-14T23:13:30.926Z","repository":{"id":57009963,"uuid":"21107150","full_name":"kuria/error","owner":"kuria","description":"Makes handling and debugging PHP errors suck less","archived":false,"fork":false,"pushed_at":"2024-04-06T11:55:34.000Z","size":186,"stargazers_count":18,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-14T23:13:12.060Z","etag":null,"topics":["debug","debugger","error-handler","exception-handler","fatal","php","stack-trace"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kuria.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-06-22T22:18:12.000Z","updated_at":"2023-09-19T17:45:10.000Z","dependencies_parsed_at":"2024-04-06T12:44:34.290Z","dependency_job_id":null,"html_url":"https://github.com/kuria/error","commit_stats":{"total_commits":44,"total_committers":2,"mean_commits":22.0,"dds":"0.022727272727272707","last_synced_commit":"a89b6a71fd004a7c148c0ed470d8c044dd4bc904"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuria%2Ferror","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuria%2Ferror/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuria%2Ferror/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuria%2Ferror/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kuria","download_url":"https://codeload.github.com/kuria/error/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248975328,"owners_count":21192210,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["debug","debugger","error-handler","exception-handler","fatal","php","stack-trace"],"created_at":"2024-12-11T12:09:26.784Z","updated_at":"2025-04-14T23:13:30.909Z","avatar_url":"https://github.com/kuria.png","language":"PHP","readme":"Error handler\n#############\n\nMakes handling and debugging PHP errors suck less.\n\n.. image:: https://travis-ci.com/kuria/error.svg?branch=master\n   :target: https://travis-ci.com/kuria/error\n\n|Web error screen in debug mode|\n\n.. contents::\n   :depth: 2\n\n\nFeatures\n********\n\n- normal / debug mode\n- converts PHP errors (warnings, notices, etc.) into exceptions\n- respects the global ``error_reporting`` setting\n- handles uncaught exceptions and fatal errors (including parse and out-of-memory errors)\n- CLI error screen writes errors to stderr\n- web error screen renders errors for web browsers\n\n  - | normal mode shows a generic error message:\n    | |Web error screen in normal mode|\n\n  - | debug mode shows all available info:\n    | |Web error screen in debug mode|\n\n    - file paths and line numbers\n    - highlighted code previews\n    - stack traces\n    - argument lists\n    - output buffer (can be shown as HTML too)\n    - plaintext trace (for copy-paste)\n\n- event system that can be utilised to:\n\n  - implement logging\n  - suppress or force errors conditionally\n  - change or add content to the error screens\n\n\nRequirements\n************\n\n- PHP 7.1+\n\n\nUsage example\n*************\n\n.. code:: php\n\n   \u003c?php\n\n   use Kuria\\Error\\ErrorHandler;\n\n   $debug = true; // true during development, false in production\n   error_reporting(E_ALL); // configure the error reporting\n\n   $errorHandler = new ErrorHandler();\n   $errorHandler-\u003esetDebug($debug);\n   $errorHandler-\u003eregister();\n\n   // trigger an error to see the error handler in action\n   echo $invalidVariable;\n\n\nEvent system\n************\n\nError handler events\n====================\n\nPossible events emitted by the ``ErrorHandler`` class are listed in ``ErrorHandlerEvents``:\n\n\n``ErrorHandlerEvents::ERROR``\n-----------------------------\n\nEmitted when a PHP errors occurs.\n\nArguments:\n\n1. ``Kuria\\Error\\Exception\\ErrorException $exception``\n\n   - you may use the ``suppress()`` or ``force()`` method to suppress or force\n     the exception, respectivelly, regardless of the ``error_reporting`` PHP setting\n\n2. ``bool $debug``\n\n\n``ErrorHandlerEvents::EXCEPTION``\n---------------------------------\n\nEmitted when an uncaught exception or a fatal error is being handled.\n\nArguments:\n\n1. ``Throwable $exception``\n2. ``bool $debug``\n\n.. WARNING::\n\n   Avoid performing memory-intensive tasks in listeners of this event if\n   ``$exception`` is an instance of ``Kuria\\Error\\Exception\\OutOfMemoryException``.\n\n\n``ErrorHandlerEvents::FAILURE``\n-------------------------------\n\nEmitted when an uncaught exception or a fatal error could not be handled. This can happen\nwhen an ``exception`` event listener or the registered error screen throws an additional\nexception. Throwing another exception or causing a fatal error at this point will just\nkill the script.\n\nArguments:\n\n1. ``Throwable $exception``\n2. ``bool $debug``\n\n.. WARNING::\n\n   Avoid performing memory-intensive tasks in listeners of this event if\n   ``$exception`` is an instance of ``Kuria\\Error\\Exception\\OutOfMemoryException``.\n\n\nWeb error screen events\n=======================\n\nPossible events emitted by the ``WebErrorScreen`` class are listed in ``WebErrorScreenEvents``:\n\n\n``WebErrorScreenEvents::RENDER``\n--------------------------------\n\nEmitted when rendering in normal mode.\n\nReceives an array with the following keys:\n\n- ``\u0026title``: used in ``\u003ctitle\u003e``\n- ``\u0026heading``: used in ``\u003ch1\u003e``\n- ``\u0026text``: content of the default paragraph\n- ``\u0026extras``: custom HTML after the main section\n- ``exception``: the exception\n- ``output_buffer``: string\\|null\n\n\n``WebErrorScreenEvents::RENDER_DEBUG``\n--------------------------------------\n\nEmitted when rendering in debug mode.\n\nReceives an array with the following keys:\n\n- ``\u0026title``: used in ``\u003ctitle\u003e``\n- ``\u0026extras``: custom HTML after the main section\n- ``exception``: the exception\n- ``output_buffer``: string\\|null\n\n\n``WebErrorScreenEvents::CSS``\n-----------------------------\n\nEmitted when CSS styles are being output.\n\nReceives a single boolean value indicating debug mode.\n\n\n``WebErrorScreenEvents::JS``\n----------------------------\n\nEmitted when JavaScript code is being output.\n\nReceives a single boolean value indicating debug mode.\n\n\nCLI error screen events\n=======================\n\nPossible events emitted by the ``CliErrorScreen`` class are listed in ``CliErrorScreenEvents``:\n\n\n``CliErrorScreenEvents::RENDER``\n--------------------------------\n\nEmitted when rendering in normal mode.\n\nReceives an array with the following keys:\n\n- ``\u0026title``: first line of output\n- ``\u0026output``: error message\n- ``exception``: the exception\n- ``output_buffer``: string|null\n\n\n``CliErrorScreenEvents::RENDER_DEBUG``\n--------------------------------------\n\nEmitted when rendering in debug mode.\n\nReceives an array with the following keys:ng keys:\n\n- ``\u0026title``: first line of output\n- ``\u0026output``: error message\n- ``exception``: the exception\n- ``output_buffer``: string|null\n\n\nEvent listener examples\n=======================\n\nLogging\n-------\n\nLogging uncaught exceptions into a file:\n\n.. code:: php\n\n   \u003c?php\n\n   use Kuria\\Debug\\Error;\n   use Kuria\\Error\\ErrorHandlerEvents;\n\n   $errorHandler-\u003eon(ErrorHandlerEvents::EXCEPTION, function (\\Throwable $exception, bool $debug) {\n       $logFilePath = sprintf('./errors_%s.log', $debug ? 'dev' : 'prod');\n\n       $entry = sprintf(\n           \"[%s] %s: %s in file %s on line %d\\n\",\n           date('Y-m-d H:i:s'),\n           Error::getExceptionName($exception),\n           $exception-\u003egetMessage(),\n           $exception-\u003egetFile(),\n           $exception-\u003egetLine()\n       );\n\n       file_put_contents($logFilePath, $entry, FILE_APPEND | LOCK_EX);\n   });\n\n\nDisabling the \"@\" operator\n--------------------------\n\nThis listener causes statements like ``echo @$invalidVariable;`` to throw an exception regardless of the \"shut-up\" operator.\n\n.. code:: php\n\n   \u003c?php\n\n   use Kuria\\Error\\Exception\\ErrorException;\n   use Kuria\\Error\\ErrorHandlerEvents;\n\n   $errorHandler-\u003eon(ErrorHandlerEvents::ERROR, function (ErrorException $exception, bool $debug) {\n       $exception-\u003eforce();\n   });\n\n\nAltering the error screens\n--------------------------\n\n.. NOTE::\n\n   Examples are for the ``WebErrorScreen``.\n\n\nChanging default labels in normal mode:\n\n.. code:: php\n\n   \u003c?php\n\n   use Kuria\\Error\\Screen\\WebErrorScreen;\n   use Kuria\\Error\\Screen\\WebErrorScreenEvents;\n\n   $errorScreen = $errorHandler-\u003egetErrorScreen();\n\n   if (!$errorHandler-\u003eisDebugEnabled() \u0026\u0026 $errorScreen instanceof WebErrorScreen) {\n       $errorScreen-\u003eon(WebErrorScreenEvents::RENDER, function ($event) {\n           $event['heading'] = 'It is all your fault!';\n           $event['text'] = 'You have broken everything and now I hate you.';\n       });\n   }\n\n\n\nAdding a customized section to the debug screen:\n\n.. code:: php\n\n   \u003c?php\n\n   use Kuria\\Error\\Screen\\WebErrorScreen;\n   use Kuria\\Error\\Screen\\WebErrorScreenEvents;\n\n   $errorScreen = $errorHandler-\u003egetErrorScreen();\n\n   if ($errorHandler-\u003eisDebugEnabled() \u0026\u0026 $errorScreen instanceof WebErrorScreen) {\n       // add custom CSS\n       $errorScreen-\u003eon(WebErrorScreenEvents::CSS, function () {\n           echo '#custom-group {color: #f60000;}';\n       });\n\n       // add custom HTML\n       $errorScreen-\u003eon(WebErrorScreenEvents::RENDER_DEBUG, function (array $view) {\n           $view['extras'] .= \u003c\u003c\u003cHTML\n   \u003cdiv id=\"custom-group\" class=\"group\"\u003e\n    \u003cdiv class=\"section\"\u003e\n        Example of a custom section\n    \u003c/div\u003e\n   \u003c/div\u003e\n   HTML;\n          });\n      }\n\n\n.. |Web error screen in normal mode| image:: ./doc/web-error-screen.png\n.. |Web error screen in debug mode| image:: ./doc/web-error-screen-debug.png\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkuria%2Ferror","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkuria%2Ferror","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkuria%2Ferror/lists"}