Skip to content

feat!: modernize error handling and HTTP integration for PHP 8.3 - #3

Open
coisa wants to merge 39 commits into
masterfrom
codex/error-handler-fire-tests
Open

coisa wants to merge 39 commits into
masterfrom
codex/error-handler-fire-tests

Conversation

@coisa

@coisa coisa commented Sep 15, 2026 •

Copy link
Copy Markdown
Owner

Modernize coisa/error-handler for PHP 8.3+ with a coherent 3.0 lifecycle, container and HTTP contract. Retain the package identity and CoiSA\ErrorHandler namespace.

  • Replace the internal container and framework adapters with one Interop provider using FastForward Container. Preserve inert discovery, cached process services, explicit fresh scopes and application overrides.
  • Define native callback ownership and reverse-order restoration, prevent recursive/failed-report retries, exit unsuccessfully after registered uncaught exceptions and accept matching interfaces or callables in all three constructor positions.
  • Report once before pure request-aware rendering. A cached negotiator selects plain text, JSON or Symfony HTML from the current request's Accept header, honoring quality/exclusions and merging Vary. The request argument is required for custom factories and direct calls.
  • Render Problem Details through Symfony Serializer. Production output contains no exception details; explicit debug omits trace arguments/objects. Symfony provides public/debug HTML; Whoops remains an optional explicit adapter and does not replace JSON when installed.
  • Add explicit Symfony CLI reporting through the same provider, using STDERR or raw application Console error output. Application reporters retain priority; no SAPI inference or additional native handler is installed.
  • Retain explicit output capture, bounded cleanup and primary-failure precedence. Correct optional callable discovery for PSR-14 delivery. Update complete recipes, source-matched site, migration/API guides, consumer skill and major release notes together.
  • Use FastForward Event Dispatcher and its real provider/configuration in event examples and functional composition. Its upstream subscriber/wrapper/failing-listener limitations are documented; no upstream fix is claimed here.

The Symfony constraints retain compatible majors and exclude proven native incompatibilities and vulnerable Accept-parser patches. VarDumper remains a transitive dependency. Optional Console and Whoops are not installed for core consumers.

Reconcile the owner's published 2.5.5 from master 09d15d11d7af4779c332e000ac084ede1d037ad0, preserving the released changelog and consumed-note state. Keep the existing changelog workflow; no release was consolidated or published by this work.

Validation

  • Local PHP 8.5.11: composer --no-plugins check passes formatting, PHPCS, 476 tests / 2,893 assertions and maximum PHPStan.
  • 27 bounded executable scenarios pass. Documentation verifies 15 excerpts, 83 links, 30 anchors and 19 complete recipes; a separate Markdown scan finds no missing local targets.
  • Parent PCOV 1.0.12 coverage is 95.02% (420/442 lines). JSON, HTML, negotiation and provider source have 100% line coverage. Native STDERR/syscall branches are exercised in bounded children without importing child coverage. The 80% policy and source scope remain unchanged.
  • The committed 85-file distribution matches source and excludes development assets. Runtime-only consumers are checked without plugins, scripts, Console or Whoops; production aliases reject E_ALL diagnostics instead of silently passing deprecations.
  • actionlint accepts CI. Native PHP CI passes all 14 jobs on head d5aa900b186b273d5ece8fe3a2f5b1c416a2d23b (tested merge 568a6b06024d27186268fe8210f07247ae7d306e): PHP 8.3–8.5 quality, five production graphs, four Symfony adapter combinations, coverage and its report. Hosted coverage is 95.02%, against 97.16% on the baseline, above the unchanged 80% floor.
  • Documentation, PHP style, changelog contribution, exact-head feedback, DCO and mergeability checks pass. All review threads are resolved; those checks do not constitute owner approval of this head.
  • Independent provider/CLI and HTML privacy/status probes found no additional actionable Error Handler defect. FastForward Event Dispatcher 1.0.0 has separate reproduced upstream defects; the exercised listener-provider recipe passes, without implying upstream compliance certification.

Issue boundaries

The five linked issues below describe the delivered major, including the newly approved negotiation scope of #8. #98 and #100 remain separate historical/operational investigations, not unimplemented 2.x features. Container extension composition is tracked separately upstream and is not silently included here.

Ready for the owner's code review. Auto-merge is disabled; merge, release, tags and publication remain owner decisions.

Closes #8
Closes #26
Closes #70
Closes #95
Closes #110

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 15, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-21T00:52:19.869163Z d5aa900 New commits
🔒 Security Review ✅ Completed 2026-10-21T00:54:36.353078Z d5aa900 New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
@coisa coisa changed the title Modernize for PHP 8.3–8.5 with fire tests and documentation Modernize PHP error handling with FastForward integration and fire tests Sep 16, 2026
Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
Comment thread src/ServiceProvider/ErrorHandlerServiceProvider.php Outdated
Comment thread src/ServiceProvider/ErrorHandlerServiceProvider.php Outdated
Comment thread src/ServiceProvider/ErrorHandlerServiceProvider.php Outdated
Comment thread src/ErrorHandler.php
Replace the standalone container and constructor-only factories with FastForward runtime integration while retaining explicit lifecycle factories and the Laminas adapter. Document all changed PHP declarations and cover autowiring, required renderer failures and reporter reset.

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ecede6434d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/ErrorHandler.php Outdated
Comment thread src/ErrorHandler.php
Assert failed construction after reaching required factories while allowing the original throwable or PSR-11 normalization. Document construction retries and validate both the locked 1.6.0 and highest 1.8.0 dependency sets.

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
@coisa coisa changed the title Modernize PHP error handling with FastForward integration and fire tests Modernize PHP error handling with FastForward autowiring and failure tests Oct 15, 2026

@coisa coisa left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed fb4652b3b4c3e6ead7b24e3453110eef9c3410b7 against
f7284cdf9bda3fadfe33f107d2c0fed3e38962cd. All four requested changes are
addressed. I found no remaining blockers within the documented interface-binding,
reporter-output and sequential-scope contracts.

The original architecture already separates handlers, reporters, PSR-14 and HTTP
composition well. The useful modernization work fixes concrete lifecycle/output
failures and improves validation. The approved simplification now removes the
standalone container and six local factories, reuses FastForward's alias/invokable
factories and relies on autowiring for constructor-only adapters. Three explicit
factories remain because they control optional handlers, reporter composition and
fresh middleware scopes. The Laminas adapter remains tested.

Two important upstream boundaries were verified during review. FastForward 1.6.0
can ignore a concrete renderer definition's PSR-11 construction failure and
rebuild it through autowiring. Required reporters/renderers must therefore use
explicit interface bindings in a single merged provider, application last.
FastForward 1.8.0 also normalizes ordinary application exceptions, and delegate
fallback can attempt construction more than once. Regression tests require the
failing factory to be reached and construction to fail; exception identity and
single construction attempts are not promised. The handler's no-retry behavior
after a reporter fails remains independently covered.

Validation: the locked 1.6.0 and isolated highest 1.8.0 installations both pass
the full check with 89 tests / 185 assertions, maximum source PHPStan,
formatting, 28 bounded failure scenarios and three HTTP responses. The real
provider suite covers 24 cases / 66 assertions. The dependency-free core and
production-only provider were also checked on PHP 8.4.26; both executable
examples retain exact output/exit contracts. Named PHP declarations in changed
files have PHPDoc, license headers are present, and 34 local documentation links
passed verification.

CI run 38670520152
passed all five PHP 8.3–8.5 dependency jobs on the reviewed head. Package versions
were preserved, while FastForward's required runtime graph grows the production
lock from 8 to 20 packages. Removed APIs and replacements are documented for the
next major. Existing default-branch development-dependency advisories are outside
the versions locked by this PR.

The worthwhile follow-up is in FastForward: distinguish configured-service
construction failures from absence and avoid silent concrete fallback. Additional
test-fixture static analysis and coverage measurement can be separate work.
FPM, Apache, Windows, concurrent scopes and remote reporter delivery still need
application-specific validation. No merge, release or Pages deployment was done.

Remove the native Laminas ConfigProvider and move remaining factories under ServiceProvider. Migrate composition tests to Interop and separate buffer cleanup in ThrowableStreamFactory without adding another class. Preserve renderer failure precedence with balanced-rendering and cleanup-only regressions.

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>

@coisa coisa left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Follow-up reviewed at c4cd54d4b2c511bdb68f404f30fb8c7b17849f0e.

Container integration is now Interop-only: ConfigProvider, Laminas discovery
metadata and the ServiceManager development dependency are removed. Both remaining
container factories moved to ServiceProvider\Factory, with imports, service
identifiers, PHPDoc and migration guidance updated. Reporter/event/listener/HTTP
behavior tests now use the Interop provider; only adapter-specific configuration
tests were retired. No compatibility aliases remain for the moved factories.

ThrowableStreamFactory keeps output capture and buffer cleanup in the same
class, extracting a private cleanup method. Characterization tests passed before
and after extraction. The renderer failure retains priority over cleanup failure,
caller-owned buffers are preserved, and cleanup still stops at non-removable
buffers or lack of progress. New regressions cover balanced successful nested
rendering and cleanup-only failure.

The full check passes with locked FastForward 1.6.0 and isolated highest 1.8.0:
70 tests / 168 assertions, maximum source PHPStan, formatting, 29 bounded
scenarios
and three HTTP responses. Production-only resolution verifies the
relocated factory creates fresh handlers and legacy APIs/ServiceManager are absent.
Only ServiceManager was removed from the lock; retained versions are unchanged.

CI run 38676464512
passed all five PHP 8.3–8.5 dependency jobs on this exact head. No remaining
blockers were found within the documented buffer and container contracts; the
previously documented FastForward fallback/exception-normalization limits remain.
No merge, release or deployment was performed.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c4cd54d4b2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/ErrorHandler.php Outdated
coisa added 3 commits October 15, 2026 09:46
Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
coisa added 3 commits October 15, 2026 10:25
Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
@coisa coisa changed the title Modernize PHP error handling with FastForward autowiring and failure tests Prepare next major with safe lifecycles and separate HTTP rendering Oct 15, 2026
Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
coisa added 4 commits October 16, 2026 17:35
Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
Normalize matching callables with the existing adapters while preserving interface precedence, defaults and explicit lifecycle ownership. Cover real FastForward configuration and align the source documentation and complete consumer examples.

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
@coisa coisa changed the title Draft reference for the remaining major modernization feat!: modernize error handling and HTTP integration for PHP 8.3 Oct 17, 2026
coisa added 6 commits October 17, 2026 12:50
Require FastForward 1.10 and update the development-tool minor lines while retaining PHPUnit and Symfony Process alternatives for PHP 8.3. Preserve compatible PSR ranges and the useful Whoops patch floor; require the fixed Nyholm patch for development recipes.

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
Skip the native structural autowiring failure only for optional callable discovery. Assert real event delivery and explicit factory causes while retaining the documented concrete-container fallback boundary. Refs #110.

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
(cherry picked from commit 39a661aa26db51ff1e1b7b2d7bad487ecd324aa5)
Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
Merge the owner-reviewed 2.x documentation maintenance while retaining the major's provider, lifecycle and HTTP contracts and its canonical consumer skill. Preserve the accepted maintenance Changeset.

Describe the accompanying API without temporary branch or publication framing, retain versioned migration guidance, and clarify that diagnostic reporter output is outside the PSR-7 response body. Keep PHP sources, tests, dependencies, configuration and workflows unchanged.

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
Fix callable filtering, installed-document links and checkout setup, clarify
stream and fatal-reporting contracts, and keep release guidance current.

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
* origin/master:
  chore(release): prepare next version of coisa/error-handler

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
Use the existing generic fallback when rendering leaves no capture above
the caller's entry depth, and verify caller bytes remain private.

Add regression coverage for partial callback ownership, fail-fast reporter
identity and native fatal metadata. Align PHPDoc, guides and consumer skill.

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
coisa added 2 commits October 17, 2026 20:13
Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
Preserve the reviewed PHP 8.3 API while adopting Fast Forward Changelog,
Composer-managed agent skills and the published Keep a Changelog history.
Convert both pending notes without consuming them or editing released notes.

Use the corrected optional Whoops 2.18.7 baseline and align its installation
guidance. Keep the legacy container, ConfigProvider and Node release tooling
removed from the major.

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
@github-actions

github-actions Bot commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

Changelog

✅ Contribution check passed.

Head: d5aa900b186b273d5ece8fe3a2f5b1c416a2d23b

Base: 09d15d11d7af4779c332e000ac084ede1d037ad0

Contribution: 3 new valid fragment(s). Policy: ordinary.

  • fix-optional-callable-event-composition.md — fixed, patch

    Skip structural autowiring failure for an unconfigured optional callable reporter so the default major aggregate still delivers PSR-14 events. Preserve configured reporter order and explicit factory failures, and document the container's remaining concrete fallback boundary.

  • modernize-error-handler.md — changed, major

    Modernize the library for PHP 8.3+ while retaining the package `coisa/error-handler` and namespace `CoiSA\ErrorHandler`. - Require PHP `^8.3`, with a tested CI matrix of PHP 8.3–8.5. - Require FastForward Container `^1.10` and expose the Interop service provider as the container entrypoint. Remove the standalone Container/ConfigProvider APIs, their package-specific exceptions and constructor-only factories. Keep explicit lifecycle/composition factories under `ServiceProvider\Factory`. - Keep construction and discovery inert. Preserve cached services and provide explicit fresh handler/middleware factories. Require reverse-order unregistration, retain one shutdown callback per handler and notify only the active o

  • request-aware-response-negotiation.md — changed, major

    Negotiate error responses from the current request through a single `ErrorHandlerServiceProvider`. Replace the JSON and Whoops profile providers with lazy Problem Details JSON, plain-text and Symfony HTML representations. Accept a required `ServerRequestInterface` alongside the original throwable in every response factory and forward it unchanged after one middleware report. Keep diagnostic output disabled by default. Explicit debug configuration enables JSON diagnostics and Symfony's detailed HTML, while production HTML remains a generic status page. Keep Whoops available only through explicit application composition, without changing the default based on installed optional packages. Respect Accept quality and exclusions, preserve existing Vary fields an

coisa added 2 commits October 20, 2026 17:43
Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
@coisa
coisa marked this pull request as ready for review October 20, 2026 20:51
coisa added 4 commits October 20, 2026 21:44
Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
…negotiation

* origin/master:
  chore(release): prepare 2.5.5 for publication

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant