feat: structured exception hierarchy#32
Merged
Merged
Conversation
ptondereau
force-pushed
the
feat/structured-exceptions
branch
from
3a06fce to
f3fadc2
Compare
ptondereau
changed the title
ptondereau
force-pushed
the
feat/structured-exceptions
branch
from
f3fadc2 to
4d073f7
Compare
Owner
Author
|
@shulard FYI, it should land for v0.5.0, it will ease the error hierarchy for production/dev monitoring |
|
Really nice work thank you for the ping ! |
ptondereau
force-pushed
the
feat/structured-exceptions
branch
from
4d073f7 to
5cdc490
Compare
Replace the flat `Invalid*` exception list with a deep typed hierarchy
rooted at `Biscuit\Exception\BiscuitException`. Every failure shape now
has its own concrete subclass so callers can use PHP's idiomatic
multi-catch instead of branching on a message string or an int code.
Hierarchy:
- BiscuitException (base, extends \Exception)
- KeyException -> PublicKeyException, PrivateKeyException
- DatalogException -> FactException, RuleException, CheckException,
PolicyException, TermException, ScopeException
- FormatException -> Base64Exception, BytesException,
SignatureException, SnapshotException
- BuildException -> BiscuitBuildException, BlockAppendException,
AuthorizerBuildException, ThirdPartyBlockAppendException
- AuthorizationException, ThirdPartyException, BuilderStateException
Structured payloads:
- AuthorizationException carries getMatchedPolicy() and
getFailedChecks() with concrete MatchedPolicy and FailedCheck value
objects.
- Every DatalogException subclass carries getParseErrors(),
getMissingParameters(), getUnusedParameters() populated from the
upstream LanguageError.
Rust side:
- BiscuitError enum + ResultExt trait centralise error tagging
through .key() / .datalog() / .format() / .build() / .third_party()
on any Result.
- Two macro_rules generators (marker_subclass! and datalog_subclass!)
keep the 16 subclass declarations DRY despite ext-php-rs not
auto-propagating methods between Rust-defined parent/child classes.
- From<BiscuitError> for PhpException dispatches each kind variant to
its concrete subclass.
Includes regenerated stubs, full UPGRADING.md migration guide with
per-class catch examples, and updated PHPUnit coverage (116 tests).
Closes #14
ptondereau
force-pushed
the
feat/structured-exceptions
branch
from
5cdc490 to
2dac331
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Address #14
Replaces the flat
Invalid*classes with a deep typed hierarchy rooted atBiscuit\Exception\BiscuitException. Every failure shape has its own concrete subclass, so callers use PHP multi-catch instead of branching on a message string or an int code.AuthorizationExceptionand everyDatalogExceptionsubclass carry structured payloads (matched policy + failed checks; parse errors + missing/unused parameters).Hierarchy
graph TD Ex["\Exception"] --> Biscuit[BiscuitException] Biscuit --> Key[KeyException] Biscuit --> Datalog[DatalogException] Biscuit --> Format[FormatException] Biscuit --> Build[BuildException] Biscuit --> Authz[AuthorizationException] Biscuit --> Third[ThirdPartyException] Biscuit --> Builder[BuilderStateException] Key --> PublicKeyException Key --> PrivateKeyException Datalog --> FactException Datalog --> RuleException Datalog --> CheckException Datalog --> PolicyException Datalog --> TermException Datalog --> ScopeException Format --> Base64Exception Format --> BytesException Format --> SignatureException Format --> SnapshotException Build --> BiscuitBuildException Build --> BlockAppendException Build --> AuthorizerBuildException Build --> ThirdPartyBlockAppendExceptionAll exceptions live in
Biscuit\Exception\. Catch the leaf for precise handling or the parent (KeyException,DatalogException,FormatException,BuildException, orBiscuitException) to catch a category.Breaking change. Full migration guide in
UPGRADING.md.