Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/decodelabs/exceptional
Better Exceptions for PHP
https://github.com/decodelabs/exceptional
exception-handling exceptions php
Last synced: 1 day ago
JSON representation
Better Exceptions for PHP
- Host: GitHub
- URL: https://github.com/decodelabs/exceptional
- Owner: decodelabs
- License: mit
- Created: 2020-09-29T10:33:15.000Z (over 4 years ago)
- Default Branch: develop
- Last Pushed: 2024-09-04T21:04:55.000Z (4 months ago)
- Last Synced: 2024-12-11T05:41:33.328Z (30 days ago)
- Topics: exception-handling, exceptions, php
- Language: PHP
- Homepage:
- Size: 115 KB
- Stars: 3
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Exceptional
[](https://packagist.org/packages/decodelabs/exceptional)
[](https://packagist.org/packages/decodelabs/exceptional)
[](https://packagist.org/packages/decodelabs/exceptional)
[](https://github.com/decodelabs/exceptional/actions/workflows/integrate.yml)
[](https://github.com/phpstan/phpstan)
[](https://packagist.org/packages/decodelabs/exceptional)
### Better Exceptions for PHP
Exceptional aims to offer a radically enhanced Exception framework that decouples the _meaning_ of an Exception from the underlying _implementation_ functionality.
_Get news and updates on the [DecodeLabs blog](https://blog.decodelabs.com)._
---
## Installation
Install via Composer:
```bash
composer require decodelabs/exceptional
```
## Usage
Exceptional exceptions can be used to greatly simplify how you generate and throw errors in your code, especially if you are writing a shared library.
Pass the name of your intended exception as a static call to the Exceptional base class and have a dynamic exception class created based on the most appropriate PHP Exception class along with a set of related interfaces for easier catching.
```php
use DecodeLabs\Exceptional;
// Create OutOfBoundsException
throw Exceptional::OutOfBounds('This is out of bounds');
// Implement multiple interfaces
throw Exceptional::{'NotFound,BadMethodCall'}(
"Didn't find a thing, couldn't call the other thing"
);
// You can associate a http code too..
throw Exceptional::CompletelyMadeUpMeaning(
message: 'My message',
code: 1234,
http: 501
);
// Implement already existing Exception interfaces
throw Exceptional::{'InvalidArgument,Psr\\Cache\\InvalidArgumentException'}(
message: 'Cache items must implement Cache\\IItem',
http: 500,
data: $item
);
// Reference interfaces using a path style
throw Exceptional::{'../OtherNamespace/OtherInterface'}('My exception');
```
Catch an Exceptional exception in the normal way using whichever scope you require:
```php
namespace MyNamespace;
try {
throw Exceptional::{'NotFound,BadMethodCall'}(
"Didn't find a thing, couldn't call the other thing"
);
} catch(
\Exception |
\BadMethodCallException |
Exceptional\Exception |
Exceptional\NotFoundException |
MyNamespace\NotFoundException |
MyNamespace\BadMethodCallException
) {
// All these types will catch
dd($e);
}
```
### Traits
Custom functionality can be mixed in to the generated exception automatically by defining traits at the same namespace level as any of the interfaces being implemented.
```php
namespace MyLibrary;
trait BadThingExceptionTrait {
public function getCustomData(): ?string {
return $this->params['customData'] ?? null;
}
}
class Thing {
public function doAThing() {
throw Exceptional::BadThing(
message: 'A bad thing happened',
data: [
'customData' => 'My custom info'
]
);
}
}
```
## Other information
- [Rationale for Exceptional](docs/Rationale.md)
- [An explanation of how the Exceptional interface works](docs/HowItWorks.md)