Add PSR-15 error-handling middleware.

[gustavofreze]

No description provided.

[github-advanced-security]

You are seeing this message because GitHub Code Scanning has recently been set up for this repository, or this pull request contains the workflow file for the Code Scanning tool.

What Enabling Code Scanning Means:

• The 'Security' tab will display more code scanning analysis results (e.g., for the default branch).
• Depending on your configuration and choice of analysis tool, future pull requests will be annotated with code scanning analysis results.
• You will be able to see the analysis results for the pull request's branch on this overview once the scans have completed and the checks have passed.

For more information about GitHub Code Scanning, check out the documentation.

[Copilot]

Pull request overview

This PR introduces a PSR-15 error-handling middleware for the tiny-blocks ecosystem, including a fluent exception-to-HTTP mapping API, optional structured logging (with correlation ID support), and a generic fallback response for unmapped exceptions.

Changes:

• Add ErrorMiddleware with configurable mapping composition, logging settings, and optional fallback vs rethrow behavior.
• Add exception-mapping primitives (ExceptionMappingTable, rule builder, matchers, resolvers) and MappedError/response translation.
• Add a full PHPUnit test suite plus standard tiny-blocks repo/tooling scaffolding (CI workflows, lint/static analysis config, docs, templates).

Reviewed changes

Copilot reviewed 81 out of 82 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
tests/Unit/UnmappedExceptions.php	Test mapping fixture that contributes an empty mapping table.
tests/Unit/MappedErrorTest.php	Unit coverage for MappedError validation and headers behavior.
tests/Unit/Internal/SubclassMatcherTest.php	Direct tests for internal subclass matcher behavior.
tests/Unit/Internal/MappingEntryTest.php	Direct tests for internal mapping entry resolution behavior.
tests/Unit/Internal/FixedMappedErrorResolverTest.php	Direct tests for internal fixed resolver behavior.
tests/Unit/Internal/ExactClassMatcherTest.php	Direct tests for internal exact-class matcher behavior.
tests/Unit/Internal/DynamicMappedErrorResolverTest.php	Direct tests for internal dynamic resolver behavior.
tests/Unit/Internal/AnyExactClassMatcherTest.php	Direct tests for internal “any of these classes” matcher behavior.
tests/Unit/ExceptionMappingTableTest.php	Unit coverage for exception mapping table composition and matching order.
tests/Unit/ExceptionMappingRuleTest.php	Unit coverage for rule builder (mapsTo / resolvesWith) behavior.
tests/Unit/ErrorMiddlewareTest.php	End-to-end unit coverage for middleware behavior, fallback, logging, headers, correlation ID.
tests/Unit/CapturingHandler.php	Test handler double to capture requests and return a fixed response.
src/MappedError.php	Value object describing a mapped HTTP error (code/status/message/headers) with status validation.
src/Internal/SubclassMatcher.php	Internal matcher for subclass-of matching.
src/Internal/MappingEntry.php	Internal pairing of matcher + resolver for mapping evaluation.
src/Internal/MappedResponse.php	Internal adapter from MappedError to a PSR-7 response.
src/Internal/MappedErrorResolver.php	Internal resolver contract for producing MappedError from a throwable.
src/Internal/FixedMappedErrorResolver.php	Internal resolver returning a fixed MappedError.
src/Internal/FallbackResponse.php	Internal fallback response builder for unmapped exceptions.
src/Internal/Exceptions/MappingNotConfigured.php	Internal exception for missing mapping configuration at build time.
src/Internal/ExceptionMatcher.php	Internal matcher contract.
src/Internal/ExactClassMatcher.php	Internal matcher for exact class matching.
src/Internal/ErrorOutcome.php	Internal orchestration for mapping, fallback, and logging decisions.
src/Internal/ErrorMiddlewareBuilder.php	Fluent builder for configuring middleware components.
src/Internal/ErrorLogger.php	Internal structured logger with correlation ID enrichment and optional detail logging.
src/Internal/DynamicMappedErrorResolver.php	Internal resolver invoking a closure factory.
src/Internal/AnyExactClassMatcher.php	Internal matcher for matching against a list of classes.
src/Exceptions/HttpStatusOutOfRange.php	Public exception for invalid mapped HTTP status.
src/ExceptionMappingTable.php	Public fluent mapping table API with composition and lookup semantics.
src/ExceptionMappingRule.php	Public intermediate rule builder for registering entries.
src/ExceptionMapping.php	Public consumer extension point for contributing mappings.
src/ErrorMiddleware.php	Public PSR-15 middleware that catches throwables and returns mapped or fallback responses.
src/ErrorHandlingSettings.php	Public settings value object controlling logging and error detail exposure.
SECURITY.md	Repository security policy and reporting instructions.
README.md	User-facing documentation and usage examples for mapping, composition, logging, and fallback.
phpunit.xml	PHPUnit configuration and coverage report outputs.
phpstan.neon.dist	PHPStan baseline configuration (max level) plus scoped ignores for known limitations.
phpcs.xml	PHPCS ruleset configuration (PSR-12).
Makefile	Docker-wrapped dev workflow targets for configure/review/tests.
infection.json.dist	Infection mutation testing configuration and 100% MSI thresholds.
composer.json	Package metadata, dependencies, autoloading, and standard scripts.
CLAUDE.md	Tiny-blocks ecosystem conventions index and validation commands.
.gitignore	Ignore vendor, reports, caches, and local overrides.
.github/workflows/codeql.yml	CodeQL workflow for security checks.
.github/workflows/ci.yml	CI workflow running composer validation, review, and tests.
.github/workflows/auto-assign.yml	Workflow to auto-assign issues and PRs.
.github/PULL_REQUEST_TEMPLATE.md	PR template with checklist and links.
.github/ISSUE_TEMPLATE/feature_request.md	Feature request issue template.
.github/ISSUE_TEMPLATE/bug_report.md	Bug report issue template.
.github/dependabot.yml	Dependabot configuration for Composer and GitHub Actions updates.
.github/copilot-instructions.md	Copilot task instructions pointing at CLAUDE/rules as source of truth.
.gitattributes	Packagist export-ignore configuration and LF normalization.
.editorconfig	Repository-wide formatting settings.
.claude/skills/tiny-blocks-create/SKILL.md	Skill doc for scaffolding/restoring canonical tiny-blocks repo files.
.claude/skills/tiny-blocks-create/assets/github/workflows/ci.yml	Canonical CI workflow asset.
.claude/skills/tiny-blocks-create/assets/github/PULL_REQUEST_TEMPLATE.md	Canonical PR template asset.
.claude/skills/tiny-blocks-create/assets/github/ISSUE_TEMPLATE/feature_request.md	Canonical feature request template asset.
.claude/skills/tiny-blocks-create/assets/github/ISSUE_TEMPLATE/bug_report.md	Canonical bug report template asset.
.claude/skills/tiny-blocks-create/assets/docs/SECURITY.md	Canonical SECURITY.md asset (with placeholders).
.claude/skills/tiny-blocks-create/assets/config/phpunit.xml	Canonical phpunit.xml asset.
.claude/skills/tiny-blocks-create/assets/config/phpstan.neon.dist	Canonical phpstan.neon.dist asset.
.claude/skills/tiny-blocks-create/assets/config/phpcs.xml	Canonical phpcs.xml asset.
.claude/skills/tiny-blocks-create/assets/config/Makefile	Canonical Makefile asset.
.claude/skills/tiny-blocks-create/assets/config/infection.json.dist	Canonical infection.json.dist asset.
.claude/skills/tiny-blocks-create/assets/config/composer.json	Canonical composer.json asset (with placeholders).
.claude/skills/tiny-blocks-create/assets/config/.gitignore	Canonical .gitignore asset.
.claude/skills/tiny-blocks-create/assets/config/.gitattributes	Canonical .gitattributes asset.
.claude/skills/tiny-blocks-create/assets/config/.editorconfig	Canonical .editorconfig asset.
.claude/skills/tiny-blocks-consume/SKILL.md	Skill doc for reusing existing tiny-blocks packages instead of re-implementing capabilities.
.claude/skills/tiny-blocks-consume/scripts/refresh-catalog.py	Script to regenerate the tiny-blocks package catalog from Packagist.
.claude/skills/tiny-blocks-consume/references/catalog.md	Generated catalog of published tiny-blocks packages.
.claude/skills/commit-message/SKILL.md	Skill doc for generating Conventional Commits messages (tiny-blocks format).
.claude/settings.json	Claude permissions and hooks configuration.
.claude/rules/php-library-tooling.md	Rules for canonical config/tooling files and invariants.
.claude/rules/php-library-testing.md	PHPUnit/Given-When-Then conventions and coverage discipline.
.claude/rules/php-library-modeling.md	Modeling conventions for types, exceptions, value objects, and complexity.
.claude/rules/php-library-github-workflows.md	Workflow structure and pinning conventions.
.claude/rules/php-library-documentation.md	README/docs structure and prose conventions.
.claude/rules/php-library-architecture.md	Public API boundary and Internal/ semantics.
.claude/hooks/php-prose-punctuation-conformance.py	Hook enforcing prose punctuation rules.
.claude/hooks/php-ordering-conformance.py	Hook enforcing deterministic ordering of members/parameters.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.