refactor: create EntitlementException hierarchy with subtypes #64

Open

Charon wants to merge 1 commit from feat/entitlement-exception-hierarchy into dev

Charon commented

2026-03-24 13:31:03 +00:00

Member

Fixes #19

Summary

Create 4 exception subclasses: LimitExceededException, PackageNotFoundException, FeatureNotFoundException, PackageSuspendedException
Add canOrFail() and canForNamespaceOrFail() throwing variants to EntitlementService
Replace firstOrFail() with explicit PackageNotFoundException in provisioning methods
Update docs/entitlements.md with Exception Hierarchy section, API reference for new methods, and updated Best Practices examples

Changes

File	Change
`Exceptions/EntitlementException.php`	Updated docblock to document hierarchy
`Exceptions/LimitExceededException.php`	New - thrown when feature limit exceeded
`Exceptions/PackageNotFoundException.php`	New - thrown when package code not found
`Exceptions/FeatureNotFoundException.php`	New - thrown when feature code not found
`Exceptions/PackageSuspendedException.php`	New - thrown when packages suspended
`Services/EntitlementService.php`	Added `canOrFail()`, `canForNamespaceOrFail()`, replaced `firstOrFail()`
`docs/entitlements.md`	Added Exception Hierarchy section, updated examples

Fixes #19 ## Summary - Create 4 exception subclasses: `LimitExceededException`, `PackageNotFoundException`, `FeatureNotFoundException`, `PackageSuspendedException` - Add `canOrFail()` and `canForNamespaceOrFail()` throwing variants to `EntitlementService` - Replace `firstOrFail()` with explicit `PackageNotFoundException` in provisioning methods - Update `docs/entitlements.md` with Exception Hierarchy section, API reference for new methods, and updated Best Practices examples ## Changes | File | Change | |------|--------| | `Exceptions/EntitlementException.php` | Updated docblock to document hierarchy | | `Exceptions/LimitExceededException.php` | New - thrown when feature limit exceeded | | `Exceptions/PackageNotFoundException.php` | New - thrown when package code not found | | `Exceptions/FeatureNotFoundException.php` | New - thrown when feature code not found | | `Exceptions/PackageSuspendedException.php` | New - thrown when packages suspended | | `Services/EntitlementService.php` | Added `canOrFail()`, `canForNamespaceOrFail()`, replaced `firstOrFail()` | | `docs/entitlements.md` | Added Exception Hierarchy section, updated examples |

Charon added 1 commit 2026-03-24 13:31:03 +00:00

refactor: create EntitlementException hierarchy with subtypes 2601392b8d

Create exception subclasses for fine-grained error handling:
- LimitExceededException: feature usage limit exceeded
- PackageNotFoundException: package code not found during provisioning
- FeatureNotFoundException: feature code not found during checks
- PackageSuspendedException: workspace packages suspended

Update EntitlementService:
- Add canOrFail() and canForNamespaceOrFail() throwing variants
- Replace firstOrFail() with explicit PackageNotFoundException in provisioning
- Import new exception types, remove unused ModelNotFoundException

Update docs/entitlements.md with Exception Hierarchy section, API reference
entries for new methods, and updated Best Practices examples.

Fixes #19

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

This pull request can be merged automatically.

You are not authorized to merge this pull request.

View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u origin feat/entitlement-exception-hierarchy:feat/entitlement-exception-hierarchy

git checkout feat/entitlement-exception-hierarchy

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git checkout dev

git merge --no-ff feat/entitlement-exception-hierarchy

git checkout feat/entitlement-exception-hierarchy

git rebase dev

git checkout dev

git merge --ff-only feat/entitlement-exception-hierarchy

git checkout feat/entitlement-exception-hierarchy

git rebase dev

git checkout dev

git merge --no-ff feat/entitlement-exception-hierarchy

git checkout dev

git merge --squash feat/entitlement-exception-hierarchy