PHPackages maatify/exceptions - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [HTTP & Networking](/categories/http) 4. / 5. maatify/exceptions ActiveLibrary[HTTP & Networking](/categories/http) maatify/exceptions ================== Policy-driven, escalation-aware exception library for PHP applications. v1.1.0(2mo ago)0249↑68.7%[2 PRs](https://github.com/Maatify/exceptions/pulls)MITPHPPHP ^8.2CI passing Since Feb 27Pushed 2mo agoCompare [ Source](https://github.com/Maatify/exceptions)[ Packagist](https://packagist.org/packages/maatify/exceptions)[ Docs](https://github.com/Maatify/exceptions)[ RSS](/packages/maatify-exceptions/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (2)Dependencies (2)Versions (5)Used By (0) maatify/exceptions ================== [](#maatifyexceptions) [![Latest Version](https://camo.githubusercontent.com/c82801f6f4617f864373701c038c760a2467b9ede14afc42a2a9b2c8a79bdf91/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d6161746966792f657863657074696f6e732e7376673f7374796c653d666f722d7468652d6261646765)](https://packagist.org/packages/maatify/exceptions)[![PHP Version](https://camo.githubusercontent.com/4c572bf30425127afe45189b9620a39ff269856c9fa1d46381666fa53429190b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6d6161746966792f657863657074696f6e732e7376673f7374796c653d666f722d7468652d6261646765)](https://packagist.org/packages/maatify/exceptions)[![License](https://camo.githubusercontent.com/dd0aae7084610c481e675c84817445517626ffd4ec955fa1ac666bf055fc6dc3/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6d6161746966792f657863657074696f6e732e7376673f7374796c653d666f722d7468652d6261646765)](LICENSE) [![PHPStan](https://camo.githubusercontent.com/f85016b73718ab38275b913dafed1c1ce7f287c3c2ec319445bc29011149f408/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d4c6576656c2532304d61782d344538434145)](https://camo.githubusercontent.com/f85016b73718ab38275b913dafed1c1ce7f287c3c2ec319445bc29011149f408/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d4c6576656c2532304d61782d344538434145) [![Changelog](https://camo.githubusercontent.com/32f7664d004132f7e0fb111b5e01bd7270705d1e7247db502287d51910c04cb9/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4368616e67656c6f672d566965772d626c7565)](CHANGELOG.md)[![Security](https://camo.githubusercontent.com/a150750c8b2c6ca6209aa80bdf220d2f0950b984df64c1b859a46ee9152570f3/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f53656375726974792d506f6c6963792d696d706f7274616e74)](SECURITY.md) [![Monthly Downloads](https://camo.githubusercontent.com/25ba7fb4d2f75c214c3ffeab044695a10519e3a14d5597064ed6c80014cef8b0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646d2f6d6161746966792f657863657074696f6e733f6c6162656c3d4d6f6e74686c79253230446f776e6c6f61647326636f6c6f723d303041384538)](https://camo.githubusercontent.com/25ba7fb4d2f75c214c3ffeab044695a10519e3a14d5597064ed6c80014cef8b0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646d2f6d6161746966792f657863657074696f6e733f6c6162656c3d4d6f6e74686c79253230446f776e6c6f61647326636f6c6f723d303041384538)[![Total Downloads](https://camo.githubusercontent.com/acabf2d73770bea1a9517ff2496ee20898c73a44e5b05915b41f9bb13a23e894/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d6161746966792f657863657074696f6e733f6c6162656c3d546f74616c253230446f776e6c6f61647326636f6c6f723d324141394530)](https://camo.githubusercontent.com/acabf2d73770bea1a9517ff2496ee20898c73a44e5b05915b41f9bb13a23e894/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d6161746966792f657863657074696f6e733f6c6162656c3d546f74616c253230446f776e6c6f61647326636f6c6f723d324141394530) **Enterprise-grade, hardened exception handling library for PHP applications.** `maatify/exceptions` provides a strictly typed, immutable taxonomy for application errors, enforcing semantic correctness, security, and consistent HTTP mapping. It is designed to prevent "taxonomy drift" and ensure that critical system errors are never masked by lower-severity wrappers. --- 🚀 Key Features -------------- [](#-key-features) - **Strict Taxonomy:** Exceptions are categorized into 9 distinct families (System, Validation, Auth, etc.) backed by `ErrorCategoryEnum`. - **Guarded Overrides:** Prevents developers from accidentally mismatching error codes or HTTP statuses. - **Escalation Protection:** Automatically escalates severity when a critical exception is wrapped in a lighter one (e.g., a Database failure wrapped in a generic runtime exception will typically retain 500 status). - **Error Serialization:** Transforms any `Throwable` into a standardized, deterministic JSON response suitable for APIs. - **RFC7807 Support:** Built-in formatter for "Problem Details for HTTP APIs" compliance. - **Zero Dependencies:** Pure PHP implementation. No framework coupling. - **PSR-4 Compliant:** Ready for immediate Composer autoloading. --- Requirements ------------ [](#requirements) - PHP 8.2+ --- 📦 Installation -------------- [](#-installation) ``` composer require maatify/exceptions ``` --- 📖 Usage ------- [](#-usage) ### Basic Usage [](#basic-usage) Throwing a predefined exception: ``` use Maatify\Exceptions\Exception\Validation\InvalidArgumentMaatifyException; throw new InvalidArgumentMaatifyException('The email format is invalid.'); // Result: // Category: VALIDATION // HTTP Status: 400 // Error Code: INVALID_ARGUMENT ``` ### Advanced Usage (Wrapping) [](#advanced-usage-wrapping) When catching a low-level error and re-throwing, the library automatically handles severity escalation: ``` use Maatify\Exceptions\Exception\BusinessRule\BusinessRuleMaatifyException; use Maatify\Exceptions\Exception\System\DatabaseConnectionMaatifyException; try { // Simulate a critical database failure (System / 503) throw new DatabaseConnectionMaatifyException('Connection timeout'); } catch (DatabaseConnectionMaatifyException $e) { // Attempting to wrap it in a "softer" business exception // Note: BusinessRuleMaatifyException is abstract, so we use an anonymous class for this example throw new class('Unable to process order', 0, $e) extends BusinessRuleMaatifyException {}; } // RESULT: // The final exception will report: // Category: SYSTEM (Escalated from BusinessRule) // HTTP Status: 503 (Escalated from 422) // This ensures monitoring tools see the root cause (System Failure), not a generic Business Rule error. ``` ### Error Serialization [](#error-serialization) Convert any exception into a ready-to-send API response: ``` use Maatify\Exceptions\Application\Error\ErrorSerializer; use Maatify\Exceptions\Application\Error\DefaultThrowableToError; use Maatify\Exceptions\Application\Format\JsonErrorFormatter; $serializer = new ErrorSerializer( new DefaultThrowableToError(), new JsonErrorFormatter() ); try { // ... application logic } catch (\Throwable $t) { $response = $serializer->serialize($t); // Send to client http_response_code($response->getStatus()); header('Content-Type: ' . $response->getContentType()); echo json_encode($response->getBody()); } ``` --- 📚 Documentation --------------- [](#-documentation) Detailed documentation is available in the [BOOK/](BOOK/) directory: 1. [Introduction](BOOK/01_Introduction.md) 2. [Architecture](BOOK/02_Architecture.md) 3. [Taxonomy](BOOK/03_Taxonomy.md) 4. [Exception Families](BOOK/04_Exception_Families.md) 5. [Override Rules](BOOK/05_Override_Rules.md) 6. [Escalation Protection](BOOK/06_Escalation_Protection.md) 7. [Security Model](BOOK/07_Security_Model.md) 8. [Best Practices](BOOK/08_Best_Practices.md) 9. [Extending The Library](BOOK/09_Extending_The_Library.md) 10. [API Integration Guide](BOOK/10_API_Integration_Guide.md) 11. [Testing Strategy](BOOK/11_Testing_Strategy.md) 12. [Versioning Policy](BOOK/12_Versioning_Policy.md) 13. [Packagist Metadata](BOOK/13_Packagist_Metadata.md) --- 🛡️ Guarantees ------------- [](#️-guarantees) - **Category Immutability:** An exception's category is defined by its class and cannot be overridden at runtime. - **Status Class Safety:** You cannot force a 4xx exception to return a 5xx status code manually, or vice versa. - **Escalation Determinism:** Severity calculation is deterministic and side-effect free. - **Serialization Determinism:** The same input Throwable and Context will always yield the exact same output. --- ✅ Quality Status ---------------- [](#-quality-status) - PHP 8.2+ - PHPUnit 11 - 100% Code Coverage - Zero Warnings - Immutable Exception Design - Deterministic Escalation & Policy Engine --- 🪪 License --------- [](#-license) This library is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details. --- 👤 Author -------- [](#-author) Engineered by **Mohamed Abdulalim** ([@megyptm](https://github.com/megyptm)) Backend Lead & Technical Architect --- 🤝 Contributors -------------- [](#-contributors) Special thanks to the Maatify.dev engineering team and all open-source contributors. Contributions are welcome. --- Built with ❤️ by [Maatify.dev](https://www.maatify.dev) — Unified Ecosystem for Modern PHP Libraries ### Health Score 42 — FairBetter than 90% of packages Maintenance86 Actively maintained with recent releases Popularity17 Limited adoption so far Community6 Small or concentrated contributor base Maturity49 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~0 days Total 2 Last Release 71d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/1a885a0810f2762586520ab284c9019aaf0b650b53cdf2a6c13ea10931bb7795?d=identicon)[Maatify](/maintainers/Maatify) --- Top Contributors [![megyptm](https://avatars.githubusercontent.com/u/33574895?v=4)](https://github.com/megyptm "megyptm (6 commits)") --- Tags clean-architecturedomain-drivenerror-handlingescalationexceptionshttpmaatifymaatify-devmaatify-ecosystemphppolicytaxonomyhttpphpexceptionsdomainerror handlingPolicymaatifyescalation ### Code Quality TestsPHPUnit Static AnalysisPHPStan Type Coverage Yes ### Embed Badge ![Health badge](/badges/maatify-exceptions/health.svg) ``` [![Health](https://phpackages.com/badges/maatify-exceptions/health.svg)](https://phpackages.com/packages/maatify-exceptions) ``` ### Alternatives [hannesvdvreken/guzzle-debugbar A Guzzle middleware that logs requests to debugbar's timeline 76410.4k1](/packages/hannesvdvreken-guzzle-debugbar)[swoole-bundle/swoole-bundle Open/Swoole Symfony Bundle 6650.4k](/packages/swoole-bundle-swoole-bundle) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)