├── .phpunit-watcher.yml ├── .styleci.yml ├── CHANGELOG.md ├── LICENSE.md ├── README.md ├── composer.json ├── psalm.xml └── src └── FriendlyExceptionInterface.php /.phpunit-watcher.yml: -------------------------------------------------------------------------------- 1 | watch: 2 | directories: 3 | - src 4 | - tests 5 | fileMask: '*.php' 6 | notifications: 7 | passingTests: false 8 | failingTests: false 9 | phpunit: 10 | binaryPath: vendor/bin/phpunit 11 | timeout: 180 12 | -------------------------------------------------------------------------------- /.styleci.yml: -------------------------------------------------------------------------------- 1 | preset: psr12 2 | risky: true 3 | 4 | version: 8.1 5 | 6 | finder: 7 | exclude: 8 | - docs 9 | - vendor 10 | 11 | enabled: 12 | - alpha_ordered_traits 13 | - array_indentation 14 | - array_push 15 | - combine_consecutive_issets 16 | - combine_consecutive_unsets 17 | - combine_nested_dirname 18 | - declare_strict_types 19 | - dir_constant 20 | - fully_qualified_strict_types 21 | - function_to_constant 22 | - hash_to_slash_comment 23 | - is_null 24 | - logical_operators 25 | - magic_constant_casing 26 | - magic_method_casing 27 | - method_separation 28 | - modernize_types_casting 29 | - native_function_casing 30 | - native_function_type_declaration_casing 31 | - no_alias_functions 32 | - no_empty_comment 33 | - no_empty_phpdoc 34 | - no_empty_statement 35 | - no_extra_block_blank_lines 36 | - no_short_bool_cast 37 | - no_superfluous_elseif 38 | - no_unneeded_control_parentheses 39 | - no_unneeded_curly_braces 40 | - no_unneeded_final_method 41 | - no_unset_cast 42 | - no_unused_imports 43 | - no_unused_lambda_imports 44 | - no_useless_else 45 | - no_useless_return 46 | - normalize_index_brace 47 | - php_unit_dedicate_assert 48 | - php_unit_dedicate_assert_internal_type 49 | - php_unit_expectation 50 | - php_unit_mock 51 | - php_unit_mock_short_will_return 52 | - php_unit_namespaced 53 | - php_unit_no_expectation_annotation 54 | - phpdoc_no_empty_return 55 | - phpdoc_no_useless_inheritdoc 56 | - phpdoc_order 57 | - phpdoc_property 58 | - phpdoc_scalar 59 | - phpdoc_singular_inheritdoc 60 | - phpdoc_trim 61 | - phpdoc_trim_consecutive_blank_line_separation 62 | - phpdoc_type_to_var 63 | - phpdoc_types 64 | - phpdoc_types_order 65 | - print_to_echo 66 | - regular_callable_call 67 | - return_assignment 68 | - self_accessor 69 | - self_static_accessor 70 | - set_type_to_cast 71 | - short_array_syntax 72 | - short_list_syntax 73 | - simplified_if_return 74 | - single_quote 75 | - standardize_not_equals 76 | - ternary_to_null_coalescing 77 | - trailing_comma_in_multiline_array 78 | - unalign_double_arrow 79 | - unalign_equals 80 | - empty_loop_body_braces 81 | - integer_literal_case 82 | - union_type_without_spaces 83 | 84 | disabled: 85 | - function_declaration 86 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Yii Friendly Exception Change Log 2 | 3 | ## 1.2.0 under development 4 | 5 | - Chg #20: Bump minimal required PHP version to 7.4 (@vjik) 6 | - Chg #36: Change PHP constraint in `composer.json` to `7.4.* || 8.0 - 8.4` (@vjik) 7 | 8 | ## 1.1.0 October 26, 2021 9 | 10 | - Enh #13: Specify markdown support explicitly (@samdark) 11 | 12 | ## 1.0.2 August 20, 2020 13 | 14 | - Allow installing on PHP 8 (@samdark) 15 | 16 | ## 1.0.1 June 7, 2020 17 | 18 | - Fix #5: Extend Throwable (@xepozz) 19 | 20 | ## 1.0.0 March 4, 2020 21 | 22 | - Initial release. 23 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | Copyright © 2008 by Yii Software () 2 | All rights reserved. 3 | 4 | Redistribution and use in source and binary forms, with or without 5 | modification, are permitted provided that the following conditions 6 | are met: 7 | 8 | * Redistributions of source code must retain the above copyright 9 | notice, this list of conditions and the following disclaimer. 10 | * Redistributions in binary form must reproduce the above copyright 11 | notice, this list of conditions and the following disclaimer in 12 | the documentation and/or other materials provided with the 13 | distribution. 14 | * Neither the name of Yii Software nor the names of its 15 | contributors may be used to endorse or promote products derived 16 | from this software without specific prior written permission. 17 | 18 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 19 | "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 20 | LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 21 | FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 22 | COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 23 | INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 24 | BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 25 | LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 26 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27 | LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 28 | ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29 | POSSIBILITY OF SUCH DAMAGE. 30 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 |

2 | 3 | Yii 4 | 5 |

Yii Friendly Exception

6 |
7 |

8 | 9 | [![Latest Stable Version](https://poser.pugx.org/yiisoft/friendly-exception/v)](https://packagist.org/packages/yiisoft/friendly-exception) 10 | [![Total Downloads](https://poser.pugx.org/yiisoft/friendly-exception/downloads)](https://packagist.org/packages/yiisoft/friendly-exception) 11 | 12 | An exception interface that provides a friendly name and a possible solution. 13 | Error handlers may consider the interface to render additional information right at the error screen. 14 | 15 | ## Requirements 16 | 17 | - PHP 7.4 or higher. 18 | 19 | ## Installation 20 | 21 | The package could be installed with [Composer](https://getcomposer.org): 22 | 23 | ```shell 24 | composer require yiisoft/friendly-exception 25 | ``` 26 | 27 | ## General usage 28 | 29 | ### Implementing friendly exception 30 | 31 | To make exception friendly require this package and implement `FriendlyExceptionInterface`: 32 | 33 | ```php 34 | use Yiisoft\FriendlyException\FriendlyExceptionInterface; 35 | 36 | class RequestTimeoutException extends \RuntimeException implements FriendlyExceptionInterface 37 | { 38 | public function getName(): string 39 | { 40 | return 'Request timed out.'; 41 | } 42 | 43 | public function getSolution(): ?string 44 | { 45 | return <<<'SOLUTION' 46 | Likely it is a result of resource request is not responding in a timely fashion. Try increasing timeout. 47 | SOLUTION; 48 | } 49 | } 50 | ``` 51 | 52 | When returning solution consider the following best practices: 53 | 54 | 1. Make solution description as short as possible. 55 | 2. Do not use HTML tags. 56 | 3. Use [simple markdown](https://commonmark.org/help/). 57 | 58 | ### Handling friendly exception 59 | 60 | To make your exception handler render friendly exceptions: 61 | 62 | ```php 63 | use Yiisoft\FriendlyException\FriendlyExceptionInterface; 64 | 65 | class ThrowableHandler 66 | { 67 | public function handle(\Throwable $t) 68 | { 69 | if ($t instanceof FriendlyExceptionInterface) { 70 | // additional handling 71 | } 72 | // regular handling 73 | } 74 | } 75 | ``` 76 | 77 | Do not forget to [render markdown](https://github.com/commonmark/commonmark-spec/wiki/List-of-CommonMark-Implementations#php). 78 | 79 | ## Documentation 80 | 81 | - [Internals](docs/internals.md) 82 | 83 | If you need help or have a question, the [Yii Forum](https://forum.yiiframework.com/c/yii-3-0/63) is a good place for that. 84 | You may also check out other [Yii Community Resources](https://www.yiiframework.com/community). 85 | 86 | ## License 87 | 88 | The Yii Friendly Exception is free software. It is released under the terms of the BSD License. 89 | Please see [`LICENSE`](./LICENSE.md) for more information. 90 | 91 | Maintained by [Yii Software](https://www.yiiframework.com/). 92 | 93 | ## Support the project 94 | 95 | [![Open Collective](https://img.shields.io/badge/Open%20Collective-sponsor-7eadf1?logo=open%20collective&logoColor=7eadf1&labelColor=555555)](https://opencollective.com/yiisoft) 96 | 97 | ## Follow updates 98 | 99 | [![Official website](https://img.shields.io/badge/Powered_by-Yii_Framework-green.svg?style=flat)](https://www.yiiframework.com/) 100 | [![Twitter](https://img.shields.io/badge/twitter-follow-1DA1F2?logo=twitter&logoColor=1DA1F2&labelColor=555555?style=flat)](https://twitter.com/yiiframework) 101 | [![Telegram](https://img.shields.io/badge/telegram-join-1DA1F2?style=flat&logo=telegram)](https://t.me/yii3en) 102 | [![Facebook](https://img.shields.io/badge/facebook-join-1DA1F2?style=flat&logo=facebook&logoColor=ffffff)](https://www.facebook.com/groups/yiitalk) 103 | [![Slack](https://img.shields.io/badge/slack-join-1DA1F2?style=flat&logo=slack)](https://yiiframework.com/go/slack) 104 | -------------------------------------------------------------------------------- /composer.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "yiisoft/friendly-exception", 3 | "type": "library", 4 | "description": "An interface for friendlier exception", 5 | "keywords": [ 6 | "exception", 7 | "exceptions", 8 | "error handling", 9 | "friendly" 10 | ], 11 | "homepage": "https://www.yiiframework.com/", 12 | "license": "BSD-3-Clause", 13 | "support": { 14 | "issues": "https://github.com/yiisoft/friendly-exception/issues?state=open", 15 | "source": "https://github.com/yiisoft/friendly-exception", 16 | "forum": "https://www.yiiframework.com/forum/", 17 | "wiki": "https://www.yiiframework.com/wiki/", 18 | "irc": "ircs://irc.libera.chat:6697/yii", 19 | "chat": "https://t.me/yii3en" 20 | }, 21 | "funding": [ 22 | { 23 | "type": "opencollective", 24 | "url": "https://opencollective.com/yiisoft" 25 | }, 26 | { 27 | "type": "github", 28 | "url": "https://github.com/sponsors/yiisoft" 29 | } 30 | ], 31 | "require": { 32 | "php": "7.4.* || 8.0 - 8.4" 33 | }, 34 | "autoload": { 35 | "psr-4": { 36 | "Yiisoft\\FriendlyException\\": "src" 37 | } 38 | }, 39 | "autoload-dev": { 40 | "psr-4": { 41 | "Yiisoft\\FriendlyException\\Tests\\": "tests" 42 | } 43 | }, 44 | "config": { 45 | "sort-packages": true, 46 | "bump-after-update": "dev", 47 | "allow-plugins": { 48 | "infection/extension-installer": true, 49 | "composer/package-versions-deprecated": true 50 | } 51 | }, 52 | "require-dev": { 53 | "maglnet/composer-require-checker": "^3.8 || ^4.3", 54 | "phpunit/phpunit": "^9.6.22", 55 | "spatie/phpunit-watcher": "^1.23.6", 56 | "vimeo/psalm": "^4.30 || ^5.26.1 || ^6.8.8" 57 | }, 58 | "scripts": { 59 | "test": "phpunit --testdox --no-interaction", 60 | "test-watch": "phpunit-watcher watch" 61 | } 62 | } 63 | -------------------------------------------------------------------------------- /psalm.xml: -------------------------------------------------------------------------------- 1 | 2 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | -------------------------------------------------------------------------------- /src/FriendlyExceptionInterface.php: -------------------------------------------------------------------------------- 1 |