{"id":19833013,"url":"https://github.com/tinywan/webman-exception","last_synced_at":"2025-10-17T15:41:53.857Z","repository":{"id":39970963,"uuid":"466651369","full_name":"Tinywan/webman-exception","owner":"Tinywan","description":"exception handler library for webman plugin","archived":false,"fork":false,"pushed_at":"2025-02-07T02:22:18.000Z","size":118,"stargazers_count":16,"open_issues_count":5,"forks_count":7,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-26T22:57:32.562Z","etag":null,"topics":["composer","exception-handling","exceptions","handler","php","php-library","tinywan","webman","webman-framework","workerman"],"latest_commit_sha":null,"homepage":"https://www.workerman.net/webman","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/Tinywan.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":"2022-03-06T06:03:52.000Z","updated_at":"2025-04-09T10:20:53.000Z","dependencies_parsed_at":"2023-11-19T06:31:31.620Z","dependency_job_id":"e6093c61-74d8-4f6d-ba41-8183eab0b4b0","html_url":"https://github.com/Tinywan/webman-exception","commit_stats":{"total_commits":32,"total_committers":3,"mean_commits":"10.666666666666666","dds":0.0625,"last_synced_commit":"058f83250e3ea3471bc2cd28022f0c17ff581a20"},"previous_names":[],"tags_count":45,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tinywan%2Fwebman-exception","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tinywan%2Fwebman-exception/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tinywan%2Fwebman-exception/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tinywan%2Fwebman-exception/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Tinywan","download_url":"https://codeload.github.com/Tinywan/webman-exception/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251907170,"owners_count":21663227,"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":["composer","exception-handling","exceptions","handler","php","php-library","tinywan","webman","webman-framework","workerman"],"created_at":"2024-11-12T11:39:15.364Z","updated_at":"2025-10-17T15:41:48.797Z","avatar_url":"https://github.com/Tinywan.png","language":"PHP","readme":"# webman exception handler 异常插件\n\n[![Latest Stable Version](http://poser.pugx.org/tinywan/exception-handler/v)](https://packagist.org/packages/tinywan/exception-handler)\n[![Total Downloads](http://poser.pugx.org/tinywan/exception-handler/downloads)](https://packagist.org/packages/tinywan/exception-handler)\n[![Daily Downloads](http://poser.pugx.org/tinywan/exception-handler/d/daily)](https://packagist.org/packages/tinywan/exception-handler)\n[![License](http://poser.pugx.org/tinywan/exception-handler/license)](https://packagist.org/packages/tinywan/exception-handler)\n[![PHP Version Require](http://poser.pugx.org/tinywan/exception-handler/require/php)](https://packagist.org/packages/tinywan/exception-handler)\n[![exception-handler](https://img.shields.io/github/last-commit/tinywan/exception-handler/main)]()\n[![exception-handler](https://img.shields.io/github/v/tag/tinywan/exception-handler?color=ff69b4)]()\n\n## 安装\n\n```php\ncomposer require tinywan/exception-handler\n```\n\n## 配置\n\n`config/exception.php`\n\n```php\nreturn [\n    // 这里配置异常处理类\n    '' =\u003e \\Tinywan\\ExceptionHandler\\Handler::class,\n];\n```\n\u003e 多应用模式时，你可以为每个应用单独配置异常处理类，参见[多应用](https://www.workerman.net/doc/webman/multiapp.html)\n\n## 基本用法\n\n请求参数错误\n```php\nuse support\\Request;\nuse support\\Response;\nuse Tinywan\\ExceptionHandler\\Exception\\BadRequestHttpException;\n\nclass Token{\n    public function issueToken(Request $request): Response\n    {\n        $params = $request-\u003epost();\n        if (empty($params)) {\n            throw new BadRequestHttpException('账号或密码不能为空');\n        }\n    }\n}\n```\n以上异常抛出错误信息，如下格式：\n```json\nHTTP/1.1 400 Bad Request\nContent-Type: application/json;charset=utf-8\n\n{\n    \"code\": 0,\n    \"msg\": \"账号或密码不能为空\",\n    \"data\": {},\n}\n```\n\u003e 所有返回的异常信息将以json格式返回，以上为`返回简略的异常信息`\n\n所有的异常错误处理器根据配置文件 `config/app.php`中`debug`的值来调整错误显示， 当`debug`值为`true` (表示在调试模式)， 错误处理器会显示异常以及详细的函数调用栈和源代码行数来帮助调试，将返回详细的异常信息。 当`debug`值为`false`，只有错误信息会被显示以防止应用的敏感信息泄漏，将返回简略的异常信息。\n\n返回详细的异常信息\n```json\nHTTP/1.1 400 Bad Request\nContent-Type: application/json;charset=utf-8\n        \n{\n    \"code\": 0,\n    \"msg\": \"password不允许为空\",\n    \"data\": {\n        \"request_url\": \"POST //127.0.0.1:8888/oauth/issue-token\",\n        \"timestamp\": \"2022-03-06 15:19:12\",\n        \"client_ip\": \"172.18.0.1\",\n        \"request_param\": {\n            \"username\": \"webman\"\n        },\n        \"error_message\": \"password不允许为空\",\n        \"error_trace\": \"#0 /var/www/webman-admin/app/functions.php(68): Tinywan\\\\Validate\\\\Validate-\u003echeck(Array)\\n#1 /var/www/webman-admin/app/controller/Authentication.php(25): validate(Array, 'app\\\\\\\\common\\\\\\\\vali...')\\n#2 /var/www/webman-admin/vendor/workerman/webman-framework/src/App.php(234): app\\\\controller\\\\Authentication-\u003eissueToken(Object(support\\\\Request))\\n#3 /var/www/webman-admin/app/middleware/AccessControlMiddleware.php(26): Webman\\\\App::Webman\\\\{closure}(Object(support\\\\Request))\\n#4 /var/www/webman-admin/vendor/workerman/webman-framework/src/App.php(228): app\\\\middleware\\\\AccessControlMiddleware-\u003eprocess(Object(support\\\\Request), Object(Closure))\\n#5 /var/www/webman-admin/vendor/workerman/webman-framework/src/App.php(137): Webman\\\\App::Webman\\\\{closure}(Object(support\\\\Request))\\n#6 /var/www/webman-admin/vendor/workerman/workerman/Connection/TcpConnection.php(638): Webman\\\\App-\u003eonMessage(Object(Workerman\\\\Connection\\\\TcpConnection), Object(support\\\\Request))\\n#7 /var/www/webman-admin/vendor/workerman/workerman/Events/Select.php(295): Workerman\\\\Connection\\\\TcpConnection-\u003ebaseRead(Resource id #254)\\n#8 /var/www/webman-admin/vendor/workerman/workerman/Worker.php(2417): Workerman\\\\Events\\\\Select-\u003eloop()\\n#9 /var/www/webman-admin/vendor/workerman/workerman/Worker.php(1541): Workerman\\\\Worker-\u003erun()\\n#10 /var/www/webman-admin/vendor/workerman/workerman/Worker.php(1383): Workerman\\\\Worker::forkOneWorkerForLinux(Object(Workerman\\\\Worker))\\n#11 /var/www/webman-admin/vendor/workerman/workerman/Worker.php(1357): Workerman\\\\Worker::forkWorkersForLinux()\\n#12 /var/www/webman-admin/vendor/workerman/workerman/Worker.php(549): Workerman\\\\Worker::forkWorkers()\\n#13 /var/www/webman-admin/start.php(87): Workerman\\\\Worker::runAll()\\n#14 {main}\"\n    }\n}\n```\n增加异常扩展响应数据\n```php\nthrow new BadRequestHttpException('验证码错误',[\n    'data' =\u003e [\n        'data1' =\u003e '自定义响应数据1',\n        'data2' =\u003e '自定义响应数据2',\n    ]\n]);\n```\n\u003e 将会在响应的 `data` 增加自义定的扩展响应参数\n\n增加`data`的返回详细的异常信息\n```json\n{\n    \"code\": 0,\n    \"msg\": \"验证码错误\",\n    \"data\": {\n        \"request_url\": \"POST //127.0.0.1:8888/oauth/issue-token\",\n         ...\n        \"data1\": \"自定义响应数据1\",\n        \"data2\": \"自定义响应数据2\"\n    }\n}\n```\n\n## 如何自定义一个自己的异常类\n\n### 编写异常类\n\n假设自定义一个：`405 Method Not Allowed`（表示：请求行中指定的请求方法不能被用于请求相应的资源）\n\n自定义异常类只需要继承`Tinywan\\ExceptionHandler\\Exception\\BaseException`类即可\n\n```php\n\u003c?php\ndeclare(strict_types=1);\n\nnamespace support\\exception;\n\nuse Tinywan\\ExceptionHandler\\Exception\\BaseException;\n\nclass MethodNotAllowedException extends BaseException\n{\n    /**\n     * @var int\n     */\n    public int $statusCode = 405;\n\n    /**\n     * @var string\n     */\n    public string $errorMessage = '请求行中指定的请求方法不能被用于请求相应的资源';\n}\n```\n\n### 使用异常类\n\n```php\nuse support\\Request;\nuse support\\Response;\nuse support\\exception\\MethodNotAllowedException;\n\nclass Token{\n    public function issueToken(Request $request): Response\n    {\n        $params = $request-\u003epost();\n        if (empty($params)) {\n            throw new MethodNotAllowedException();\n        }\n    }\n}\n```\n\n使用postman请求截图\n\n![self-exception.png](self-exception.png)\n\n## 已支持插件异常类\n\n- [Validate 验证器插件](https://www.workerman.net/plugin/7) 异常类`JwtTokenException`\n- [JWT 权限认证插件](https://www.workerman.net/plugin/10) 异常类`ValidateException`\n\n## 内置异常类\n\n- 客户端异常类（HTTP Status 400）：BadRequestHttpException\n- 身份认证异常类（HTTP Status 401）：UnauthorizedHttpException\n- 资源授权异常类（HTTP Status 403）：ForbiddenHttpException\n- 资源不存在异常类（HTTP Status 404）：NotFoundHttpException\n- 路由地址不存在异常类（HTTP Status 404）：RouteNotFoundException\n- 请求限流在异常类（HTTP Status 429）：TooManyRequestsHttpException\n- 服务器内部错误异常类（HTTP Status 500）：ServerErrorHttpException\n\n[更多：https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Status](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Status)\n\n## 自定义异常 Response\n\n\u003e 使用场景\n- 每个项目有标准的统一输出，自定义返回内容\n- 前后端分离：前端要求返回的 `HTTP状态码`并不是 `429`，而是 `200` 或者其他\n- 响应的`body`不是 `{\"code\":0,\"msg\":\"Too Many Requests\"}`，而是 `{\"error_code\":200,\"message\":\"Too Many Requests\"}` 等其他内容\n\n### 自定义HTTP状态码\n\n编辑 `config/plugin/tinywan/exception-handler/app.php` 文件的 `status` HTTP 状态码\n\n### 自定义`body`返回内容\n\n编辑 `config/plugin/tinywan/exception-handler/app.php` 文件的 `body` 的字段\n\n**默认选项是**\n\n```json\n{\n\t\"code\": 0,\n\t\"msg\": \"Too Many Requests\",\n\t\"data\": null\n}\n```\n**自定义选项参考一**\n\n1、假设`status` HTTP 状态码设置为 `200`\n\n2、假设`body`的数组设为为\n\n```php\n'body' =\u003e [\n\t'error_code' =\u003e 200,\n\t'message' =\u003e '请求太多请稍后重试'\n]\n```\n\n则响应内容为\n```json\nHTTP/1.1 200 OK\nContent-Type: application/json;charset=UTF-8\n\n{\n\t\"error_code\": 200,\n\t\"message\": \"请求太多请稍后重试\"\n}\n```\n其他的可以根据自身业务自定义即可\n\n## 扩展自己的 Handler\n\n当项目需要自定义情况比较多的时候，很可能需要扩展 Handler，此时可以继承 `Tinywan\\ExceptionHandler\\Handler` 然后修改对应方法即可。\n\n\u003e 使用场景\n- response需要响应`xml`，而不是json格式，只需要覆盖`buildResponse`方法\n- 扩展其他Exception的响应，我只要覆盖`solveExtraException`\n- 要异常推送微信消息，我可以覆盖`triggerNotifyEvent`\n\n自定义异常 `ErrorHandler`\n\n```php\n\nnamespace support;\n\nuse Illuminate\\Validation\\ValidationException;\nuse Tinywan\\ExceptionHandler\\Handler;\nuse Webman\\Http\\Response;\n\nclass ErrorHandler extends Handler\n{\n    /**\n     * @inheritDoc\n     */\n    protected function solveExtraException(\\Throwable $e): void\n    {\n        // 当前项目下的异常扩展\n        if ($e instanceof ValidationException) {\n            $this-\u003eerrorMessage = $e-\u003evalidator-\u003eerrors()-\u003efirst();\n            $this-\u003eerrorCode = 422;\n            return;\n        }\n\n        parent::solveExtraException($e);\n    }\n\n    /**\n     * @inheritDoc\n     */\n    protected function triggerNotifyEvent(\\Throwable $e): void\n    {\n         // ... 这里省略触发其他错误推送渠道\n\n        parent::triggerNotifyEvent($e);\n    }\n\n    /**\n     * @inheritDoc\n     */\n    protected function buildResponse(): Response\n    {\n        // 构造自己项目下的响应\n        return json([\n            'code' =\u003e $this-\u003estatusCode, // 使用 statusCode 作为 code 返回\n            'msg' =\u003e $this-\u003eerrorMessage,\n            'data' =\u003e $this-\u003eresponseData,\n        ]);\n    }\n}\n```\n\n## 异常通知（钉钉机器人）\n\n![dingtalk.png](dingtalk.png)\n\n## Other\n\n### phpstan\n\n```phpregexp\nvendor/bin/phpstan analyse src\n```\n\n### vendor/bin/php-cs-fixer fix src\n\n```phpregexp\nvendor/bin/php-cs-fixer fix src\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftinywan%2Fwebman-exception","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftinywan%2Fwebman-exception","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftinywan%2Fwebman-exception/lists"}