Adds a router to the built-in serve command

[markhuot]

When running ./craft serve PHP utilizes it's built-in web server. The built-in web server automatically serves static files with the appropriate mime-type and headers based on the file extension. So, a request to a .php file will route through PHP and return HTML. A request to a .css file will serve the static file with a CSS content-type header. This works really well for actual files on disk.

Unfortunately, if Craft is serving a virtual file (with an extension) through its own internal routing (via a module or otherwise) it will break. For example, insert the following in to a Module,

Event::on(
    UrlManager::class,
    UrlManager::EVENT_REGISTER_SITE_URL_RULES,
    function (RegisterUrlRulesEvent $event) {
        $event->rules['foo.json'] = ['template' => 'my-great-template'];
    }
);

This should serve the template out of the templates directory but instead you get a PHP error that foo.json does not exist. This is because PHP assumes the .json extension is a static file and not something that PHP would normally serve.

To work around this you can call the built in web server with a "router". Adding the router script allows the application code to make a determination if the request is static or not instead of assuming specific extensions are static.

This PR adds a router.php that checks the document root for a file before serving it. If the file does not exist in the filesystem it will fall back to Craft/PHP for serving the file (which mimics the recommended setup for Craft with popular web servers like Nginx).

Note: when running PHP's built in web-server we can be assured that $_SERVER['DOCUMENT_ROOT'] points where we want it too because the Yii serve console command does this for us.

Lastly, it's important to have a separate router.php instead of using index.php as the router. When you specify a router it is (essentially) prepended to all requests. A request to the homepage would (more or less) look like require 'router.php'; require 'index.php'; If the index was your router you end up with a recursive call that times out or just breaks because it tries to prepend index.php on to itself and you get errors with duplicate constants and the like.

--

Long story short: this makes php -S behave more like "production" in that 404'd files route through Craft/PHP.

[i-just]

Looks to be working as expected to me.

[brianjhanson]

Seems like a solid addition to me.

[brandonkelly]

Merged via 96cd72c. Thanks @markhuot!

[brandonkelly]

Craft 4.3.4 is out with this 🎉

[markhuot]

Woo! Made my day, thanks everyone.

I'm a big fan of `php craft serve` for local development and the newly added `router.php` makes it even more powerful when using custom routes. One more paper cut crossed off my list! https://t.co/isC68I95nI

— Mark (@markhuot) November 29, 2022