@@ -71,6 +71,7 @@ public function start():void {
7171// Before we start, we check if the current URI should be redirected. If it
7272// should, we won't go any further into the lifecycle.
7373 $ this ->redirect ->execute ();
74+
7475// The first thing done within the WebEngine lifecycle is start a timer.
7576// This timer is only used again at the end of the call, when finish() is
7677// called - at which point the entire duration of the request is logged out (and
@@ -86,7 +87,6 @@ public function start():void {
8687// usage, the globals are protected against accidental misuse.
8788 $ this ->protectGlobals ();
8889
89-
9090// The RequestFactory takes the necessary global arrays to construct a
9191// ServerRequest object. The $_SERVER array contains metadata about the request,
9292// such as headers and server variables. $_FILES contains any uploaded files,
@@ -101,9 +101,18 @@ public function start():void {
101101 $ this ->globals ["_POST " ] ?? [],
102102 );
103103
104- // TODO: Document what the Dispatcher's purpose is, and why it's important to
105- // attach to the class as a property (for error states to be able to display
106- // errors using the correct instance of the request, config, etc.)
104+ // The Dispatcher is a core component responsible for:
105+ // 1. Executing the application's routing logic to match the incoming request
106+ // 2. Running any middleware defined for the matched route
107+ // 3. Executing the appropriate page logic functions
108+ // 4. Generating and returning the HTTP response
109+ //
110+ // It's critical to store the Dispatcher as a class property because if an error
111+ // occurs during request processing, the error handling system needs access to
112+ // the same Dispatcher instance that has the original request context,
113+ // configuration, and other dependencies required to properly generate and
114+ // display error pages. This ensures errors can be handled consistently using
115+ // the application's error templates and logging mechanisms.
107116 $ this ->dispatcher = $ this ->dispatcherFactory ->create (
108117 $ this ->config ,
109118 $ request ,
0 commit comments