DX: unified factory, basePath, emit, docs

[alganet]

Remove the HttpFactories DTO and adopt a single
ResponseFactoryInterface&StreamFactoryInterface intersection type that flows through:

Router -> DispatchEngine -> DispatchContext -> Responder

Make basePath a mandatory string argument (first position) with trailing-slash normalization so "/" means root and "/app/" equals "/app".

Add Router::handle() implementing RequestHandlerInterface, and make process() properly delegate to the next handler on 404.

Add Respect\Rest\emit() helper for PSR-7 response emission.

Fix AuthBasic passing null to typed callback params on 401.

Rewrite docs/README.md feature guide to reflect the current API and add a comprehensive example/full.php exercising most features.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 68.18182% with 14 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.68%. Comparing base (d4ec823) to head (66529a7).
⚠️ Report is 1 commits behind head on master.

Files with missing lines	Patch %	Lines
src/emit.php	0.00%	12 Missing ⚠️
src/Router.php	87.50%	2 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master     #174      +/-   ##
============================================
- Coverage     98.08%   96.68%   -1.40%     
- Complexity      415      418       +3     
============================================
  Files            30       30              
  Lines          1043     1056      +13     
============================================
- Hits           1023     1021       -2     
- Misses           20       35      +15     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR refactors Respect\Rest to use a single PSR-17 factory (implementing both ResponseFactoryInterface and StreamFactoryInterface) throughout the core, removing the HttpFactories wrapper. It also expands PSR-15 integration by making Router a RequestHandlerInterface and updating middleware behavior to delegate on “no route matched” cases, plus adds an emit() helper and updates examples/docs accordingly.

Changes:

• Replace HttpFactories with a single intersection-typed PSR-17 factory across Router, DispatchEngine, DispatchContext, and Responder.
• Update Router base path handling (normalize trailing slash) and add PSR-15 handle()/middleware delegation behavior with new tests.
• Add Respect\Rest\emit() helper and refresh examples/docs to reflect the new public API.

Reviewed changes

Copilot reviewed 42 out of 42 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/Stubs/Negotiator.php	Updates stub context construction for new DispatchContext factory signature.
tests/Routines/WhenTest.php	Updates router/context setup after factory API change; removes HttpFactories usage.
tests/Routines/UserAgentTest.php	Replaces HttpFactories fixture with a single PSR-17 factory.
tests/Routines/ThroughTest.php	Replaces HttpFactories fixture with a single PSR-17 factory.
tests/Routines/RelTest.php	Updates router construction to new constructor signature.
tests/Routines/LastModifiedTest.php	Replaces HttpFactories with a single factory; updates context creation.
tests/Routines/ContentTypeTest.php	Replaces HttpFactories with a single factory in contexts.
tests/Routines/CallbackMediatorTest.php	Updates context creation to pass the unified factory.
tests/Routines/ByTest.php	Updates router/context setup after factory API change.
tests/Routines/AuthBasicTest.php	Updates router/context setup; removes test for 401 body-on-failure behavior.
tests/Routines/AcceptTest.php	Replaces HttpFactories with a single factory in contexts.
tests/Routines/AcceptLanguageTest.php	Replaces HttpFactories with a single factory in contexts.
tests/Routines/AcceptEncodingTest.php	Replaces HttpFactories with a single factory in contexts.
tests/Routines/AcceptCharsetTest.php	Replaces HttpFactories with a single factory in contexts.
tests/RoutinePipelineTest.php	Switches response creation and context construction to unified factory.
tests/Routes/StaticValueTest.php	Updates DispatchContext construction for new signature.
tests/Routes/ExceptionTest.php	Updates router construction to new constructor signature.
tests/Routes/ErrorTest.php	Updates router construction to new constructor signature.
tests/Routes/AbstractRouteTest.php	Updates router setup and Responder construction for new factory API.
tests/RouterTest.php	Adds base path normalization tests and PSR-15 delegation tests; updates router factory/basePath setup.
tests/ResponderTest.php	Updates Responder construction for unified factory API.
tests/Psr7InjectionTest.php	Updates router construction to new constructor signature.
tests/HttpFactoriesTest.php	Removes tests for HttpFactories (class removed).
tests/DispatchEngineTest.php	Updates engine construction/basePath handling to use unified factory and empty-string base path.
tests/DispatchContextTest.php	Updates context creation and responder injection for unified factory API.
src/Routines/LastModified.php	Switches response creation to use $context->factory.
src/Routines/AuthBasic.php	Switches response creation to use $context->factory; changes 401 handling flow.
src/Routines/AbstractSyncedRoutine.php	Switches PSR response injection to use $context->factory.
src/Routes/AbstractRoute.php	Switches PSR response injection to use $context->factory.
src/Router.php	Changes constructor signature (base path + unified factory), normalizes base path, adds handle(), and updates middleware process() behavior.
src/RouteProvider.php	Updates getBasePath() return type to string (empty string denotes “no base path”).
src/Responder.php	Refactors to a unified factory (ResponseFactoryInterface&StreamFactoryInterface).
src/HttpFactories.php	Removes the HttpFactories helper class.
src/emit.php	Adds Respect\Rest\emit(ResponseInterface): void helper for sending responses.
src/DispatchEngine.php	Refactors to unified factory and updates basePath empty-string semantics.
src/DispatchContext.php	Refactors to unified factory and updates responder/response draft creation.
phpcs.xml.dist	Excludes src/emit.php from global-function sniff (namespaced helper function).
example/README.md	Updates example instructions and adds full showcase reference.
example/index.php	Updates example to new router constructor + emit() usage.
example/full.php	Adds a comprehensive feature showcase example using emit() and new API.
docs/README.md	Updates docs for new constructor, PSR-15 usage, PSR-7 injection, and modernized examples.
composer.json	Autoloads src/emit.php via files to ensure the helper function is available.

---

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

You can also share your feedback on Copilot code review. Take the survey.