{"id":22477548,"url":"https://github.com/maplephp/blunder","last_synced_at":"2025-08-02T13:31:07.305Z","repository":{"id":252746195,"uuid":"840642574","full_name":"MaplePHP/Blunder","owner":"MaplePHP","description":"Blunder is a pretty error handling framework for PHP","archived":false,"fork":false,"pushed_at":"2024-09-30T16:57:46.000Z","size":68,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-12-01T05:50:03.181Z","etag":null,"topics":["blunder","debugging-tool","error","error-handling","error-management","error-presentation","php","php-errors","pretty-error-interface"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MaplePHP.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2024-08-10T08:38:03.000Z","updated_at":"2024-09-30T16:49:59.000Z","dependencies_parsed_at":"2024-08-17T19:43:39.866Z","dependency_job_id":null,"html_url":"https://github.com/MaplePHP/Blunder","commit_stats":null,"previous_names":["maplephp/blunder"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaplePHP%2FBlunder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaplePHP%2FBlunder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaplePHP%2FBlunder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaplePHP%2FBlunder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MaplePHP","download_url":"https://codeload.github.com/MaplePHP/Blunder/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228476038,"owners_count":17926134,"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":["blunder","debugging-tool","error","error-handling","error-management","error-presentation","php","php-errors","pretty-error-interface"],"created_at":"2024-12-06T14:11:30.793Z","updated_at":"2025-08-02T13:31:07.295Z","avatar_url":"https://github.com/MaplePHP.png","language":"PHP","readme":"# MaplePHP Blunder\n\n![Screen dump on how blunder looks like](https://wazabii.se/github-assets/maplephp-blunder.png \"MaplePHP Blunder\")\n\n**Blunder is a pretty error handling framework for PHP.** It provides a pretty, user-friendly interface that simplifies \ndebugging with excellent memory management. Blunder offers various handlers, including HTML, JSON, XML, CLI, plain text, \nand silent modes, allowing flexible error presentation. Seamlessly integrating with tools like the PSR-7 and PSR-3 \ncompliant MaplePHP Log library, Blunder is an excellent choice for managing errors in PHP applications, helping users easily \nidentify and resolve issues.\n\nWith Blunder, you can easily control how errors are handled—whether you want to suppress specific severities, redirect them to \nlogging, or assign them to different handlers. For example, you can automatically log all Deprecated warnings while keeping \nWarnings visible for debugging. This level of customization ensures a smooth and efficient error-handling experience tailored \nto your needs.\n\n## Installation\nInstallation with composer\n\n```bash\ncomposer require maplephp/blunder\n```\n\n## Pretty Example\n\nHere is a simple example to load the pretty error interface:\n\n```php\nuse MaplePHP\\Blunder\\Run;\nuse MaplePHP\\Blunder\\Handlers\\HtmlHandler;\n\n$run = new Run(new HtmlHandler());\n$run-\u003eload();\n```\n\n## Handlers\n\nAll handlers utilize the namespace `MaplePHP\\Blunder\\Handlers\\[TheHandlerName]`.\n\n* **HtmlHandler**: A user-friendly and visually appealing handler.\n* **TextHandler**: Outputs a minified HTML text.\n* **PlainTextHandler**: Outputs minified plain text.\n* **JsonHandler**: Outputs errors as JSON.\n* **XmlHandler**: Outputs errors as XML.\n* **CliHandler**: Prompt handler for the command-line interface (CLI) \n* **SilentHandler**: Suppresses error output but can log errors to files. You can choose to output fatal errors if necessary.\n\n\n## Excluding Specific Error Severities from the Handler\n\nWith Blunder, you can exclude specific error severities from the handler. This allows you to control how certain errors are processed without affecting the overall error handling behavior.\n\n### 1. Exclude Severity Levels\nThis method removes the specified severities from Blunder’s handler, allowing them to be processed by PHP’s default error reporting.\n\n```php\n$run = new Run(new HtmlHandler());\n$run-\u003eseverity()-\u003eexcludeSeverityLevels([E_DEPRECATED, E_USER_DEPRECATED]);\n$run-\u003eload();\n```\n**Effect:**\n- `E_DEPRECATED` and `E_USER_DEPRECATED` will no longer be handled by Blunder.\n- PHP’s default error handling will take over for these severities.\n\n---\n\n### 2. Exclude and Redirect Severities\nInstead of letting PHP handle the excluded severities, you can redirect them to a custom function for further processing, such as logging.\n\n#### **Behavior:**\n- **`return true;`** → Completely suppresses errors of the excluded severities.\n- **`return false;`** → Uses PHP’s default error handler for the excluded severities.\n- **`return null|void;`** → Keeps using Blunder’s error handler as usual.\n\n```php\n$run = new Run(new HtmlHandler());\n$run-\u003eseverity()\n    -\u003eexcludeSeverityLevels([E_WARNING, E_USER_WARNING])\n    -\u003eredirectTo(function ($errNo, $errStr, $errFile, $errLine) {\n        error_log(\"Custom log: $errStr in $errFile on line $errLine\");\n        return true; // Suppresses output for excluded severities\n    });\n```\n\n**Example Use Case:**\n- Log warnings instead of displaying them.\n- Ensure deprecated notices are logged but not shown in production.\n\n---\n\n### 3. Redirect Excluded Severities to a New Handler\nYou can also redirect excluded severities to a completely different error handler.\n\n```php\n$run = new Run($errorHandler);\n$run-\u003eseverity()\n    -\u003eexcludeSeverityLevels([E_WARNING, E_USER_WARNING])\n    -\u003eredirectTo(function ($errNo, $errStr, $errFile, $errLine) {\n        return new JsonHandler();\n    });\n```\n**Effect:**\n- `E_WARNING` and `E_USER_WARNING` will be processed by `JsonHandler` instead of `HtmlHandler` or PHP’s default error handling.\n\n---\n\n**Note:**  \nYou can find a full list of available PHP error severities [here](https://www.php.net/manual/en/errorfunc.constants.php).\n\n---\n\n## Enabling or Disabling Trace Lines\nThis allows you to control the level of detail shown in error messages based on your debugging needs. \nYou can customize this behavior using the configuration:\n\n```php\n$handler = new CliHandler();\n\n// Enable or disable trace lines\n$handler-\u003eenableTraceLines(true); // Set false to disable\n\n$run = new Run($handler);\n$run-\u003eload();\n```\n\n### **Options:**\n- `true` → Enables trace lines (default in all cases except for in the CliHandler).\n- `false` → Disables trace lines, making error messages cleaner.\n\nThis allows you to control the level of detail shown in error messages based on your debugging needs.\n\n## Remove location headers\nThis will remove location headers and make sure that no PHP redirect above this code will execute. \n```php\n$run = new Run(new HtmlHandler());\n$run-\u003eremoveLocationHeader(true);\n$run-\u003eload();\n```\n\n## Setting the Exit Code for Errors\nTo make Blunder trigger a specific exit code when an error occurs. This is useful in unit testing and CI/CD, ensuring tests fail on errors.\n```php\n$run = new Run(new CliHandler());\n$run-\u003esetExitCode(1);\n$run-\u003eload();\n```\n\n## Event Handling\n\nYou can use Blunder's **event** functionality to handle errors, such as logging them to a file. The example below shows how to display a pretty error page in development mode and log errors in production.\n\n#### 1. Install MaplePHP Log\nWe use [MaplePHP Log](https://github.com/MaplePHP/Log) in the example, a PSR-3 compliant logging library.\n\n```bash\ncomposer require maplephp/log\n```\n\n#### 2. Create an Event\nHere is a complete example with explanatory comments.\n\n```php\n// Add the namespaces\nuse MaplePHP\\Blunder\\Run;\nuse MaplePHP\\Blunder\\Handlers\\HtmlHandler;\nuse MaplePHP\\Blunder\\Handlers\\SilentHandler;\nuse MaplePHP\\Log\\Logger;\nuse MaplePHP\\Log\\Handlers\\StreamHandler;\n\n// Bool to switch between dev and prod mode\n$production = true;\n\n// Initialize Blunder\n$handler = ($production ? new SilentHandler() : new HtmlHandler());\n$run = new Run($handler);\n\n// Create the event\n$run-\u003eevent(function($item, $http) use($production) {\n\n    if ($production) {\n        // Initialize the MaplePHP PSR-3 compliant log library\n        $log = new Logger(new StreamHandler(\"/path/to/errorLogFile.log\", StreamHandler::MAX_SIZE, StreamHandler::MAX_COUNT));\n        \n        // The code below uses \"getStatus\" to call PSR-3 log methods like $log-\u003eerror() or $log-\u003ewarning().  \n        call_user_func_array([$log, $item-\u003egetStatus()], [\n            $item-\u003egetMessage(),\n            [\n                'flag' =\u003e $item-\u003egetSeverity(),\n                'file' =\u003e $item-\u003egetFile(),\n                'line' =\u003e $item-\u003egetLine()\n            ]\n        ]);\n    }\n    \n});\n\n// Load the error handling, and done\n$run-\u003eload();\n```\n\n## HTTP Messaging\n\nThe Blunder `Run` class can take two arguments. The first argument is required and should be a class handler (`HandlerInterface`). The second argument is optional and expects an HTTP message class used to pass an already open PSR-7 response and `ServerRequest` instance instead of creating a new one for better performance.\n\n```php\n// $run = new Run(HandlerInterface, HttpMessagingInterface(ResponseInterface, ServerRequestInterface));\n$run = new Run(new HtmlHandler(), new HttpMessaging($response, $request));\n```\n\n## Exception Chaining\nWhen rethrowing an exception with a different type, PHP resets the file and line number to the location of the new `throw` statement. This can make debugging harder, as the error message will point to the wrong file instead of the original source of the exception.\n\nTo preserve the original exception’s file and line number while changing its type, you can use the **`preserveExceptionOrigin`** method provided by Blunder.\n\n#### Example: Preserving the Original Exception’s Location\n```php\ntry {\n    // An exception has been triggered inside dispatch()\n    $dispatch = $row-\u003edispatch();\n} catch (Throwable $e) {\n    // By default, rethrowing with a new exception class changes the error location\n    $exception = new RuntimeException($e-\u003egetMessage(), (int) $e-\u003egetCode());\n\n    // Preserve the original exception's file and line number\n    if (method_exists($e, \"preserveExceptionOrigin\")) {\n        $e-\u003epreserveExceptionOrigin($exception);\n    }\n\n    throw $exception;\n}\n```","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaplephp%2Fblunder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaplephp%2Fblunder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaplephp%2Fblunder/lists"}