Initial commit

Author: megyptm

.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: Exceptions CI
+
+on:
+  push:
+    branches: [ main, dev ]
+  pull_request:
+    branches: [ main, dev ]
+
+jobs:
+  quality:
+    name: Quality Checks (PHP ${{ matrix.php }})
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        php: [ "8.1", "8.2", "8.3", "8.4" ]
+
+    steps:
+      # -------------------------------------------------
+      # 1) Checkout
+      # -------------------------------------------------
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # -------------------------------------------------
+      # 2) Setup PHP
+      # -------------------------------------------------
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          tools: composer
+          coverage: none
+
+      # -------------------------------------------------
+      # 3) Validate composer.json
+      # -------------------------------------------------
+      - name: Validate composer.json
+        run: composer validate --strict
+
+      # -------------------------------------------------
+      # 4) Install dependencies
+      # -------------------------------------------------
+      - name: Install dependencies
+        run: composer install --no-interaction --prefer-dist --no-progress
+
+      # -------------------------------------------------
+      # 5) Dump optimized autoload
+      # -------------------------------------------------
+      - name: Optimize autoload
+        run: composer dump-autoload --optimize
+
+      # -------------------------------------------------
+      # 6) Run PHPStan (Level Max)
+      # -------------------------------------------------
+      - name: Run PHPStan
+        run: composer analyse
+
+      # -------------------------------------------------
+      # 7) Syntax Check (extra safety)
+      # -------------------------------------------------
+      - name: Lint PHP files
+        run: |
+          find src -type f -name "*.php" -print0 | xargs -0 -n1 php -l

BOOK/01_Introduction.md

@@ -0,0 +1,33 @@
+# Introduction
+
+`maatify/exceptions` is a strictly typed, immutable taxonomy for PHP application errors.
+
+## Purpose
+
+The primary goal of this library is to solve "Taxonomy Drift"—the tendency for applications to lose semantic meaning in their error handling over time.
+
+By enforcing a strict taxonomy and guarding override capabilities, this library ensures that:
+1.  **System errors remain System errors** (even when wrapped).
+2.  **Client errors remain Client errors** (even when re-thrown).
+3.  **Monitoring tools receive accurate signals** about system health.
+
+## Philosophy
+
+*   **Exceptions should be semantic:** "User not found" is a different category than "Database offline".
+*   **Taxonomy should be immutable:** A developer should not be able to arbitrarily change the category of an exception at runtime.
+*   **Severity should never be downgraded:** Critical failures must always bubble up as critical failures.
+
+## Scope
+
+This library provides:
+*   A base `MaatifyException` class.
+*   Strictly typed Enums for Categories and Error Codes.
+*   Concrete exception classes for common scenarios (Validation, Auth, System, etc.).
+*   Logic for safe overrides and escalation.
+
+## Non-Goals
+
+This library does *not* provide:
+*   HTTP handling or middleware (it is framework-agnostic).
+*   Logging implementations (it is PSR-3 compatible but does not implement a logger).
+*   Automatic error reporting (it provides the *data* for reporting, not the transport).

BOOK/02_Architecture.md

@@ -0,0 +1,39 @@
+# Architecture
+
+`maatify/exceptions` is built on a simple yet strict architecture:
+
+## Class Hierarchy
+
+1.  **`Throwable` (PHP Core Interface)**
+    *   **`ApiAwareExceptionInterface` (Contract)** - The public contract for all application exceptions.
+        *   **`MaatifyException` (Abstract Base Class)** - Implements `ApiAwareExceptionInterface` and enforces strict taxonomy rules.
+            *   **Concrete Exception Families** (e.g., `SystemMaatifyException`, `ValidationMaatifyException`)
+                *   **Specific Exceptions** (e.g., `DatabaseConnectionMaatifyException`, `InvalidArgumentMaatifyException`)
+
+## Key Design Invariants
+
+1.  **Immutability:** Exception categories are defined by the class type and cannot be changed at runtime.
+2.  **Strict Taxonomy:** Only predefined `ErrorCategoryEnum` values are allowed.
+3.  **Strict Typing:** All exception handling relies on PHP strict types.
+4.  **Escalation Logic:** Automatic severity calculation logic resides in the base `MaatifyException` constructor.
+
+## ApiAwareExceptionInterface
+
+The `ApiAwareExceptionInterface` defines the core contract for all exceptions:
+
+```php
+interface ApiAwareExceptionInterface extends Throwable
+{
+    public function getHttpStatus(): int;
+    public function getErrorCode(): ErrorCodeEnum;
+    public function getCategory(): ErrorCategoryEnum;
+    public function isSafe(): bool;
+    public function getMeta(): array;
+    public function isRetryable(): bool;
+}
+```
+
+*   **`isSafe()`**: Indicates if the exception message can be safely exposed to the client (e.g., Validation Errors).
+*   **`isRetryable()`**: Indicates if the request can be retried immediately (e.g., Rate Limiting).
+
+This interface guarantees that any conforming exception can be processed by a generic error handler (e.g., converting to JSON response).

BOOK/03_Taxonomy.md

@@ -0,0 +1,44 @@
+# Taxonomy
+
+The core of `maatify/exceptions` is its strict taxonomy system.
+
+## ErrorCategoryEnum
+
+The `ErrorCategoryEnum` defines the 9 core families of exceptions.
+
+| Category         | Description                                         |
+|------------------|-----------------------------------------------------|
+| `SYSTEM`         | Critical system failures (database, network, file). |
+| `RATE_LIMIT`     | Too many requests (client throttling).              |
+| `AUTHENTICATION` | Authentication failures (login required).           |
+| `AUTHORIZATION`  | Forbidden access (permission required).             |
+| `VALIDATION`     | Invalid input data (bad request).                   |
+| `BUSINESS_RULE`  | Domain-specific logic violation.                    |
+| `CONFLICT`       | Resource conflict (duplicate entry).                |
+| `NOT_FOUND`      | Resource not found (404).                           |
+| `UNSUPPORTED`    | Unsupported operation or method.                    |
+
+## ErrorCodeEnum
+
+The `ErrorCodeEnum` provides distinct error codes for specific scenarios.
+
+| Code                         | Usage                                                           |
+|------------------------------|-----------------------------------------------------------------|
+| `MAATIFY_ERROR`              | Generic system error.                                           |
+| `INVALID_ARGUMENT`           | Generic validation error.                                       |
+| `BUSINESS_RULE_VIOLATION`    | Generic business logic error.                                   |
+| `RESOURCE_NOT_FOUND`         | Resource not found.                                             |
+| `CONFLICT`                   | Resource conflict.                                              |
+| `ENTITY_IN_USE`              | Cannot delete entity because it is in use.                      |
+| `UNAUTHORIZED`               | Authentication required.                                        |
+| `SESSION_EXPIRED`            | Session expired.                                                |
+| `AUTH_STATE_VIOLATION`       | Account state prevents action (e.g., locked, password expired). |
+| `RECOVERY_LOCKED`            | Recovery mechanism locked due to excessive attempts.            |
+| `FORBIDDEN`                  | Access denied.                                                  |
+| `UNSUPPORTED_OPERATION`      | Operation not supported.                                        |
+| `DATABASE_CONNECTION_FAILED` | Database connection error.                                      |
+| `TOO_MANY_REQUESTS`          | Rate limit exceeded.                                            |
+
+## Strict Mapping
+
+The library strictly enforces which Error Codes can be used with which Categories. For example, you cannot use `DATABASE_CONNECTION_FAILED` with a `VALIDATION` category. Attempting to do so will result in a `LogicException`.

BOOK/04_Exception_Families.md

@@ -0,0 +1,67 @@
+# Exception Families
+
+Exceptions are categorized into 9 main families, each backed by an abstract base class.
+
+## 1. SystemMaatifyException
+
+*   **Category:** `SYSTEM`
+*   **Default Status:** 500
+*   **Usage:** For critical failures like database errors, filesystem failures, or external API outages.
+*   **Concrete:** `DatabaseConnectionMaatifyException`
+
+## 2. RateLimitMaatifyException
+
+*   **Category:** `RATE_LIMIT`
+*   **Default Status:** 429
+*   **Default `isRetryable()`:** `true`
+*   **Usage:** When a client exceeds the allowed request rate.
+*   **Concrete:** `TooManyRequestsMaatifyException`
+
+## 3. AuthenticationMaatifyException
+
+*   **Category:** `AUTHENTICATION`
+*   **Default Status:** 401
+*   **Usage:** When a user is not logged in or has an invalid session.
+*   **Concrete:** `UnauthorizedMaatifyException`, `SessionExpiredMaatifyException`
+
+## 4. AuthorizationMaatifyException
+
+*   **Category:** `AUTHORIZATION`
+*   **Default Status:** 403
+*   **Usage:** When a user is logged in but lacks permission.
+*   **Concrete:** `ForbiddenMaatifyException`
+
+## 5. ValidationMaatifyException
+
+*   **Category:** `VALIDATION`
+*   **Default Status:** 400
+*   **Usage:** For invalid client input (e.g., malformed email, missing field).
+*   **Concrete:** `InvalidArgumentMaatifyException`
+
+## 6. BusinessRuleMaatifyException
+
+*   **Category:** `BUSINESS_RULE`
+*   **Default Status:** 422
+*   **Usage:** For domain-specific logic (e.g., "Cannot cancel shipped order").
+*   **Concrete:** `BusinessRuleMaatifyException` (Abstract)
+
+## 7. ConflictMaatifyException
+
+*   **Category:** `CONFLICT`
+*   **Default Status:** 409
+*   **Usage:** For duplicate resource creation or data inconsistency.
+*   **Concrete:** `GenericConflictMaatifyException`
+
+## 8. NotFoundMaatifyException
+
+*   **Category:** `NOT_FOUND`
+*   **Default Status:** 404
+*   **Usage:** When a requested resource does not exist.
+*   **Concrete:** `ResourceNotFoundMaatifyException`
+
+## 9. UnsupportedMaatifyException
+
+*   **Category:** `UNSUPPORTED`
+*   **Default Status:** 409
+*   **Usage:** When an operation is valid but not supported in the current context.
+*   **Concrete:** `UnsupportedOperationMaatifyException`

BOOK/05_Override_Rules.md

@@ -0,0 +1,75 @@
+# Override Rules
+
+The `MaatifyException` base class allows developers to override default metadata (HTTP Status, Error Code) but enforces strict guardrails.
+
+## 1. Category Immutability
+
+You **cannot** override the category of an exception.
+
+*   `ValidationMaatifyException` will always be `VALIDATION`.
+*   `SystemMaatifyException` will always be `SYSTEM`.
+
+This prevents "Taxonomy Drift" where exceptions lose their semantic meaning.
+
+## 2. Error Code Constraints
+
+If you provide an `$errorCodeOverride` in the constructor:
+
+1.  The code **must exist** in the `ALLOWED_ERROR_CODES` mapping for that category.
+2.  If it does not match, a `LogicException` is thrown immediately.
+
+### Fallback Semantics
+
+The default policy validation is permissive for unconfigured categories:
+
+*   **Unconfigured category:** Allows **all** codes.
+*   **Configured category with empty list:** Allows **all** codes.
+*   **Configured category with codes:** Strictly enforces the allowed list.
+
+**Example:**
+*   `ValidationMaatifyException` allows `INVALID_ARGUMENT`.
+*   It forbids `DATABASE_CONNECTION_FAILED`.
+
+*(Note: Since `ValidationMaatifyException` is abstract, these rules apply to any concrete class extending it.)*
+
+## 3. HTTP Status Class Guard
+
+If you provide an `$httpStatusOverride`:
+
+1.  It **must match the default status class** (Client Error vs Server Error).
+2.  `4xx` defaults can be overridden with other `4xx` codes.
+3.  `5xx` defaults can be overridden with other `5xx` codes.
+4.  **Cross-class overrides are forbidden.** (e.g., 400 -> 500).
+
+This ensures that a client-side error (Validation) never accidentally reports a server-side failure (System) to monitoring tools.
+
+## 4. Policy Customization
+
+You can inject a custom `ErrorPolicyInterface` to override default rules (e.g., allow extra codes).
+
+```php
+// Create a policy with custom rules
+$customPolicy = DefaultErrorPolicy::withOverrides(
+    allowedOverrides: ['VALIDATION' => ['MY_CUSTOM_CODE']]
+);
+
+// Inject globally (PROCESS-WIDE)
+MaatifyException::setGlobalPolicy($customPolicy);
+MaatifyException::setGlobalEscalationPolicy($customEscalationPolicy);
+```
+
+### Resolution Precedence
+
+The library resolves policies in the following order:
+
+1.  **Escalated:** (Highest Priority) Logic derived from previous exception wrapping.
+2.  **Override:** Instance-specific overrides passed to the constructor.
+3.  **Default:** The active `ErrorPolicyInterface` (Global or Default).
+
+### ⚠️ Warning: Long-Running Processes
+
+In persistent environments (e.g., **Swoole**, **RoadRunner**), static global state persists across requests. Global policy setters (`setGlobalPolicy`, `setGlobalEscalationPolicy`) are **PROCESS-WIDE**.
+
+*   **Risk:** Setting a global policy in one request may affect subsequent requests.
+*   **Best Practice:** Set global policies only during application bootstrap, before handling any requests.
+*   **Cleanup:** Use `MaatifyException::resetGlobalPolicies()` to clear all static overrides.

BOOK/06_Escalation_Protection.md

@@ -0,0 +1,55 @@
+# Escalation Protection
+
+`maatify/exceptions` features a deterministic escalation mechanism.
+
+## The Problem: Swallowed Errors
+
+A common pattern in PHP is to wrap exceptions:
+
+```php
+try {
+    $db->connect(); // Throws 503 System Error
+} catch (Exception $e) {
+    // Attempting to wrap in a business rule exception
+    throw new class("Cannot process request", 0, $e) extends BusinessRuleMaatifyException {};
+}
+```
+
+This effectively **hides the system failure**. Monitoring tools see a 422 (Business Rule) instead of a critical 503 (System Failure).
+
+## The Solution: Automatic Escalation
+
+When wrapping an exception using `MaatifyException`:
+
+1.  **Category Severity Check:** The library compares the severity of the new exception against the previous one.
+2.  **HTTP Status Check:** The library compares the HTTP status codes.
+3.  **Result:** The final exception adopts the **higher severity** category and status.
+
+### Escalation Logic
+
+*   **Category:** If `previous_severity > current_severity`, the category is escalated.
+*   **HTTP Status:** Uses `max(current, previous)` to ensure the highest error class is preserved (e.g., 500 overrides 400).
+*   **Unknown Categories:** `severity()` returns **0** for unknown categories, treating them as lowest priority.
+
+### Severity Ranking (High to Low)
+
+1.  `SYSTEM` (90)
+2.  `RATE_LIMIT` (80)
+3.  `AUTHENTICATION` (70)
+4.  `AUTHORIZATION` (60)
+5.  `VALIDATION` (50)
+6.  `BUSINESS_RULE` (40)
+7.  `CONFLICT` (30)
+8.  `NOT_FOUND` (20)
+9.  `UNSUPPORTED` (10)
+
+### Example
+
+*   **Original:** `SystemMaatifyException` (Severity 90, Status 503)
+*   **Wrapper:** `BusinessRuleMaatifyException` (Severity 40, Status 422)
+
+**Final Outcome:**
+*   **Category:** `SYSTEM` (Escalated from BusinessRule)
+*   **Status:** 503 (Escalated from 422)
+
+This guarantees that critical errors are **never masked**.