Repository navigation
Refactor WebAppAdapter and web helpers to remove normal stop() usage #472
Description
Summary
Remove stop() from normal web response flow and make WebAppAdapter fully return-driven.
Goals
WebAppAdapter::start(): ?intremains unchangedWebAppAdapter::start()always returns0- normal web flow sends a returned
Response - web helper paths stop relying on
StopExecutionException
In scope
src/App/Adapters/WebAppAdapter.phpsrc/App/Traits/WebAppTrait.phpsrc/Http/Helpers/http.phpsrc/ResourceCache/ViewCache.php- web-specific short-circuit helpers such as 404 / redirect flow
Target start() shape
public function start(): ?int
{
if (request()->isMethod('OPTIONS')) {
$response = response()->setStatusCode(StatusCode::NO_CONTENT);
} else {
$this->loadModules();
$matchedRoute = $this->resolveRoute();
$this->loadLanguage();
$this->logDebugInfo();
$response = $this->setupViewCache()
->getCachedResponse(request()->getUri() ?? '');
if ($response === null) {
$response = (new MiddlewareManager($matchedRoute))
->applyMiddlewares(request(), response());
$response = (new RouteDispatcher())
->dispatch($matchedRoute, request(), $response);
}
}
$this->sendResponse($response);
return 0;
}Required helper shape
private function sendResponse(Response $response): void
{
$this->handleCors($response);
$response->send();
}Cached view contract
Current style is mutation plus boolean:
public function serveCachedView(string $uri, Response $response): boolTarget style should be:
public function getCachedResponse(string $uri): ?ResponseShort-circuit paths to replace
OPTIONSpage_not_found()- redirect helper flow
- cache-hit flow
Acceptance criteria
- normal web flow has no
try/catch StopExecutionException WebAppAdapter::start()returns0- normal web paths do not rely on
stop() - cached-view lookup returns
?Responsedirectly
Validation
WebAppAdaptertests- web helper tests
- full web path regression checks
Activity
armanist commentedon Apr 28, 2026
Architecture proposal update for
#472(based on deeper review):I believe we should avoid passing
Responsethrough middleware/dispatcher as a threaded mutable object. It creates ownership ambiguity and mixes two models (explicit pipeline vs DI-owned response).Recommended direction
Adopt a stricter PSR-15-style middleware shape and explicit adapter control flow:
QtMiddleware::apply(Request $request, Closure $next): ResponseMiddlewareManager::applyMiddlewares(Request $request): ?ResponseResponse=> middleware short-circuited (send it)null=> continue to route dispatchRouteDispatcher::dispatch(...): Responseremains strictWebAppAdapterdecides branch explicitly (cache hit / middleware short-circuit / dispatch), then sends exactly one final response.Why
Suggested
start()flow (high-level)OPTIONSby creating/sending response, return00middlewareResponse = applyMiddlewares(request())00If agreed, I can follow with a concrete implementation checklist (file-by-file) for safe rollout.
armanist commentedon Apr 28, 2026
Follow-up proposal update for
#472(clarifying terminal handler model):After review, I recommend replacing the earlier
?Responsemanager idea with a stricter and cleaner contract:QtMiddleware::apply(Request $request, Closure $next): ResponseMiddlewareManager::applyMiddlewares(Request $request, Closure $terminal): ResponseWhat is
$terminal?$terminalis the final handler executed after middleware chain completes.For
#472,$terminalis route dispatch (RouteDispatcher::dispatch(...)).Why this is better
?? response()return response()->...)Adapter shape (high-level)
If this direction is accepted, implementation can proceed in phases with minimal breakage.
[quantum-php#472] Align middleware templates and cron fixture style w…
[quantum-php#472] Use request Accept header for 404 content negotiation
[quantum-php#472] Remove unused page_not_found wrapper helper
[quantum-php#472] Clean middleware templates response usage and signa…
[quantum-php#472] Update template @SInCE tags to 3.0.0
[quantum-php#472] Enforce LF line endings for template files
[quantum-php#472] Removing --testdox flag from unit tests
[quantum-php#472] Add CI coverage debug logging for phpunit
[quantum-php#472] Enable xdebug coverage driver in CI
[quantum-php#472] Reduce CI coverage overhead and remove debug log pl…
[quantum-php#472] Enforce LF line endings for template files
[quantum-php#472] Remove --testdox flag from composer test script
[quantum-php#472] Remove UTF-8 BOM from all module template files
[quantum-php#472] Reuse view cache instance in web terminal flow
[quantum-php#472] Normalize template EOF newlines
[quantum-php#472] Fix template UTF-8 mojibake in es validation
[#472] Refactor web flow to explicit response pipeline
Merge pull request #477 from armanist/issue/472-web-flow-refactor
[quantum-php#470 quantum-php#471 quantum-php#472 quantum-php#473] Doc…