Pear Exception Laravel Package

Getting Started

pear/pear_exception is a lightweight, PSR-3 compatible exception class that extends PHP’s native Exception and adds a structured getMessage() with contextual details (like error code, file, line, and optional debugInfo()). It’s primarily used in legacy or hybrid codebases that still leverage PEAR-style error handling or need a clean, standardized exception base. Start by requiring it via Composer (composer require pear/pear_exception) and extending it for domain-specific exceptions. First use case: replacing generic Exception with PEAR_Exception in legacy PEAR-based code to maintain consistency and preserve structured error data.

Implementation Patterns

• Inheritance Chain: Create a base App_Exception extends PEAR_Exception, then subclass further (e.g., Validation_Exception, Database_Exception) to inject domain semantics.
• Debug Info: Override debugInfo() to redact sensitive data (e.g., passwords) or include context (e.g., user ID, request ID) without exposing internals in logs.
• Strict Error Handling: Use in combination with set_error_handler() that converts PHP errors to exceptions (e.g., set_error_handler(['PEAR_Exception', 'handleError'])), enabling modern try/catch for otherwise fatal errors.
• Legacy Integration: Bridge PEAR-style PEAR_ErrorStack or PEAR_Error by mapping error codes to PEAR_Exception instances during migration from older frameworks (e.g., legacy Horde, PHPUnit < 9).
• PHP 8.1+ Compatibility: With v1.0.2, the package now addresses PHP 8.1+ warnings, ensuring smoother integration in modern environments. Test thoroughly with typed properties and constructor promotion if using PHP 8+ features.

Gotchas and Tips

• No Active Maintenance: As of 2021, it’s unmaintained. Verify it meets your stability needs—consider symfony/serializer’s exception helpers or roll your own extends Exception if forward compatibility is critical.
• Namespace Collision: PEAR classes are global namespace. Avoid autoloading conflicts by not mixing PSR-4 autoloading with PEAR-style class loading (e.g., via PEAR_Config or legacy include_path hacks).
• getMessage() Override: getMessage() returns a formatted string (code + message), unlike native Exception. If logging tools expect raw messages, extract via ->getMessage() and parse or use getPrevious()/getTrace() carefully.
• ERROR_RETURN Quirk: This package was designed for PEAR’s error-return conventions (PEAR::raiseError() returns an error object, not throw). Use PEAR_Exception::raiseError() for non-throwing usage, but prefer exceptions for type safety in modern code.
• PHP 8+ Compatibility: While v1.0.2 fixes warnings for PHP 8.1+, test behavior with:
  • Typed properties and constructor promotion.
  • Named arguments in exception constructors.
  • The Error class (non-Exception errors) to ensure no regressions.
• Deprecation Risk: Given the lack of maintenance, plan for eventual migration to a more actively supported alternative (e.g., League\ErrorHandler or custom exceptions).