Exception Laravel Package

Technical Evaluation

Architecture fit

• hoa/exception is a standalone exception-construction library, not a framework integration. It does not hook into Laravel's Illuminate\Foundation\Exceptions\Handler; it only changes the shape and type of the objects you throw.
• Genuine capabilities worth examining: exception chaining (Hoa\Exception\Exception::chain), aggregation (Hoa\Exception\Group, which is IteratorAggregate/Countable/ArrayAccess), lazy construction (Hoa\Exception\Idle), and retry semantics.
• Overlap with Laravel-native tools is high: Handler::report/render, Reportable/Renderable contracts, ValidationException + MessageBag for aggregation, and the retry() helper for backoff. Net-new capability is narrow — roughly one marker interface and one aggregate class.
• Fit verdict: poor for greenfield Laravel services; tolerable only as a leaf dependency inside one legacy, bounded context.

Integration feasibility

• Composer-installable, but bootstrapped through Hoa\Consistency, which pulls a transitive Hoa subgraph (consistency, possibly protocol/ustring) and drags its maintenance debt along.
• The 2017-08-30 release predates PHP 7.2 object, 7.4 typed properties, 8.0 unions, 8.1 never, and 8.2 dynamic-property deprecation. Compatibility with the PHP 8.x versions modern Laravel requires must be proven, not assumed.
• Hoa defines its own Hoa\Exception\Throwable interface alongside \Exception. Because Hoa exceptions extend \Exception, Laravel's \Throwable catches will work — but dontReport, $internalDontReport, WithExceptions mapping, and withoutExceptionHandling() in tests will not know about Hoa-specific semantics without explicit wiring.
• Queue serialization is unverified: aggregated or chained Hoa exceptions must survive SerializesModels → failed_jobs → Horizon/Sentry payloads.

Technical risk: high

• Abandonment: repo is archived, last release seven years old, no security-response path. Score (1.26) and dependents (0) in the dataset reinforce this as a hard negative signal.
• Supply chain: archived transitive deps generate permanent SCA/Dependabot noise and require a documented policy exception.
• Behavioral: custom exception hierarchy can silently bypass report throttling, deduplication, and log-context enrichment configured centrally in the handler.
• Serialization: Group and deep chains can truncate or fail to serialize, degrading diagnostics at exactly the moment they matter.

Key questions

1. Which capability do we actually need — aggregation, retry, or lazy construction — and can ValidationException, retry(), and a ~100-line AggregateException cover it?
2. Has anyone run the suite against PHP 8.2/8.3/8.4 and the current Laravel major?
3. Does a thrown Hoa exception survive the full path: throw → report() → queue serialize → failed() → Sentry/Horizon payload?
4. Is Hoa already in the lockfile transitively (making this free), or is this a new branch?
5. Who owns the fork if a PHP 8 patch is required, and is vendoring acceptable under our licensing and SCA policy?

Integration Approach

Stack fit

• Laravel 10/11 on PHP 8.1–8.3: not recommended. Laravel 5.x/6.x on PHP 7.x legacy: plausible.
• If adopted, confine to a single bounded context (e.g., a batch-import/ETL module) and forbid Hoa types from leaking into controllers, jobs, or the public API contract.

Migration path

1. Spike branch: composer require hoa/exception in a throwaway app; run the PHP/Laravel matrix; assert autoload, inheritance, handler behavior, and queue round-trip.
2. Adapter layer: define app-owned App\Exceptions\AggregateException and App\Exceptions\RetryableException (marker interface). Consumers depend only on app types; Hoa becomes a private implementation detail.
3. Shadow-run the adapter against a native implementation to compare behavior under real traffic.
4. Decide keep-or-delete behind the same adapter. The likely outcome is deleting Hoa and keeping the adapter on native code.

Compatibility notes

• Verify Hoa's hoa:// stream wrapper and Hoa\Consistency bootstrap do not collide with Flysystem/S3/phar:// wrappers registered at boot.
• PHPUnit/Pest: ensure expectException(\Throwable::class) paths behave; Hoa's interfaces won't satisfy native type-hints.
• Larastan/PHPStan will flag Hoa's untyped docblocks; plan baseline ignores up front.

Sequencing

• Do not block on this. Position it as Phase 3 behind the exception-handling standardization work (centralized handler, error taxonomy, Sentry integration). If the taxonomy lands first, the case for Hoa largely evaporates.

Operational Impact

Maintenance

• Archived upstream means we own all patches. Budget 2–5 engineer-days for a PHP 8 port, plus a recurring tax at every PHP minor upgrade.
• Composer audit and Dependabot will flag it as unmaintained; requires a written exception in the SCA policy and a named owner.

Support

• No upstream channel, no CVE process; incident response is internal-only.
• Onboarding cost is real: chain, retry, silent, and Group are non-idiomatic, sparsely documented, and unfamiliar to Laravel engineers.

Scaling

• Runtime cost is negligible if Idle is used for control-flow-style cases.
• The scaling risk is observability, not CPU: Group exceptions and deep chains can produce oversized log/Sentry payloads and exceed ingestion limits. Truncation and sampling must be added in the handler.
• Queue workers: non-serializable or deeply chained exceptions can fail job serialization or produce unhelpful failed_jobs rows.

Failure modes

1. PHP minor upgrade breaks Hoa → fatal at boot or on throw. Highest likelihood, highest impact.
2. A Hoa exception escapes to the API boundary and serializes to a non-standard shape instead of Laravel's {message, errors, exception} contract.
3. Aggregated payloads exceed log ingestion limits → diagnostics lost precisely when needed.
4. Hoa\Consistency bootstrap interferes with stream wrappers or global state → intermittent, hard-to-reproduce failures.
5. SCA gate blocks a release because an archived dependency entered the tree.

Ramp-up

• Low for the API surface (about a day); high for the institutional cost of justifying a non-native exception layer.
• Recommendation: decline adoption. Capture the two genuinely useful patterns — a retryable marker interface and an exception aggregator — as ~100 lines of app code, and revisit only if a specific module proves it needs more.