EH-001: Implement Extended Exception Hierarchy with Error Codes

[azaharizaman]

Overview

Create comprehensive exception hierarchy with error codes (1000-9999 taxonomy) and rich context for runtime recovery and developer debugging.

Requirements

• REQ-017: Comprehensive error handling and structured exceptions
• REQ-003: Network-agnostic error handling and exceptions
• CON-001: PHP 8.2+, PHPStan level 7

Implementation Checklist

1. Base BlockchainException Class

• Create src/Exceptions/BlockchainException.php
• Extend standard PHP Exception
• Add protected int $errorCode property
• Add protected ?ErrorContext $context = null property
• Implement getErrorCode(): int method
• Implement getErrorCategory(): string method (based on code range)
• Implement getContext(): ?ErrorContext method
• Implement setContext(ErrorContext $context): self method
• Add getHttpStatusCode(): int method for API mapping
• Add PHPDoc with error code taxonomy documentation

2. ErrorContext Class

• Create src/Exceptions/ErrorContext.php
• Add properties: timestamp, requestId, driverName, networkName
• Add parameters array for sanitized context data
• Add remediationSteps array for suggested fixes
• Add originalException for nested exception context
• Implement isDebugMode flag for context filtering
• Add toArray(): array method for serialization
• Add sanitize(array $data): array method to remove secrets
• All properties should be readonly or have private setters
• Add PHPDoc for all properties and methods

3. Network Exception Classes

• Create src/Exceptions/Network/ConnectionException.php (error code: 1000-1099)
  • Network connectivity failures, DNS resolution errors
• Create src/Exceptions/Network/TimeoutException.php (error code: 1100-1199)
  • Request timeout scenarios, with elapsed time in context
• Create src/Exceptions/Network/RateLimitException.php (error code: 7000-7099)
  • API rate limiting, include retry-after in context
• Create src/Exceptions/Network/NetworkException.php (error code: 1200-1299)
  • Blockchain network-specific errors (node unavailable, wrong chain)
• All extend BlockchainException
• Add specific context properties for each exception type

4. Transaction Exception Classes

• Enhance existing src/Exceptions/TransactionException.php (error code: 3000-3099)
  • Add error code support
  • Add context support
  • Keep existing transactionHash property
• Create src/Exceptions/Transaction/InsufficientFundsException.php (error code: 3100-3199)
  • Balance-related failures, include required and available amounts
• Create src/Exceptions/Transaction/ContractException.php (error code: 3200-3299)
  • Smart contract interaction errors, include contract address
• Create src/Exceptions/Transaction/SignatureException.php (error code: 3300-3399)
  • Transaction signing errors, no private key data in context

5. Configuration Exception Classes

• Enhance existing src/Exceptions/ConfigurationException.php (error code: 2000-2099)
  • Add error code support
  • Add context support with missing/invalid parameter details
• Enhance existing src/Exceptions/ValidationException.php (error code: 4000-4099)
  • Add error code support
  • Add validation error details in context

6. Driver Exception Classes

• Enhance existing src/Exceptions/UnsupportedDriverException.php (error code: 5000-5099)
  • Add error code support
  • Add list of available drivers in context
• Create src/Exceptions/Driver/UnsupportedOperationException.php (error code: 5100-5199)
  • Operation not supported by driver, include operation name and driver name

7. Internal Exception Classes

• Create src/Exceptions/Internal/InternalException.php (error code: 8000-8099)
  • Unexpected internal errors
• Create src/Exceptions/Internal/AssertionException.php (error code: 8100-8199)
  • Assertion failures, include assertion details

8. Error Code Constants

• Create src/Exceptions/ErrorCodes.php class with constants
  • Network errors: 1000-1999
  • Configuration errors: 2000-2999
  • Transaction errors: 3000-3999
  • Validation errors: 4000-4999
  • Driver errors: 5000-5999
  • Security errors: 6000-6999
  • Rate limit errors: 7000-7999
  • Internal errors: 8000-8999
• Add PHPDoc explaining each error code range

9. Unit Tests

• Create tests/Exceptions/BlockchainExceptionTest.php
  • Test error code getter
  • Test error category mapping
  • Test context attachment
  • Test HTTP status code mapping
• Create tests/Exceptions/ErrorContextTest.php
  • Test context creation and serialization
  • Test sensitive data sanitization
  • Test debug vs production mode filtering
• Create tests for all exception types
• Test exception inheritance hierarchy
• Test error code ranges and uniqueness

10. Documentation

• Create docs/error-codes.md with complete error code reference
• Add usage examples for each exception type
• Document best practices for exception handling
• Add migration guide from basic exceptions

Acceptance Criteria

• All exception types implement consistent error code interface
• ErrorContext properly sanitizes sensitive data
• Error codes are unique and follow taxonomy
• All exceptions have comprehensive PHPDoc
• Unit tests achieve 95%+ coverage
• PHPStan reports no errors
• Documentation includes all error codes with descriptions

Files Created/Modified

• src/Exceptions/BlockchainException.php
• src/Exceptions/ErrorContext.php
• src/Exceptions/ErrorCodes.php
• src/Exceptions/Network/*.php (4 files)
• src/Exceptions/Transaction/*.php (3 new + 1 enhanced)
• Enhanced: ConfigurationException.php, ValidationException.php, UnsupportedDriverException.php
• tests/Exceptions/ (comprehensive test suite)
• docs/error-codes.md

Dependencies

• Core Utilities (base exception classes)

Related

• Plan: plan/feature-exception-handling.md (Task 1)
• PRD: docs/prd/11-EXCEPTION-HANDLING-EPIC.md
• Epic: Exception Handling & Error Management