From 598f2f7b0e42107039fed15f589923f56d0501b1 Mon Sep 17 00:00:00 2001 From: Bogdan Date: Mon, 21 Sep 2026 22:04:50 +0200 Subject: [PATCH] docs: clarify hostname and subdomain route options include the port The hostname and subdomain options are compared against the full HTTP_HOST value, including the port. Document that routes restricted by these options must include the port when the application is served on a non-standard port (e.g. localhost:8080, Docker, spark server). --- user_guide_src/source/incoming/routing.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/user_guide_src/source/incoming/routing.rst b/user_guide_src/source/incoming/routing.rst index 7dda8b687131..29a5f172f365 100644 --- a/user_guide_src/source/incoming/routing.rst +++ b/user_guide_src/source/incoming/routing.rst @@ -476,6 +476,15 @@ by passing the "hostname" option along with the desired domain to allow it on as This example would only allow the specified hosts to work if the domain exactly matched **accounts.example.com**. It would not work under the main site at **example.com**. +.. note:: + + The ``hostname`` option is compared against the full ``HTTP_HOST`` value of the + request, including the port when one is present. When your application is served + on a non-standard port (for example ``localhost:8080``, behind Docker, or when + using ``spark server``), you must include the port in the ``hostname`` option for + the routes to match. For example, ``['hostname' => 'localhost:8080']`` matches only + requests to ``localhost:8080``. + Restrict by Multiple Hostnames ------------------------------ @@ -502,6 +511,11 @@ that does not have any subdomain present, this will not be matched: Most domains should work fine but some edge case ones, especially with a period in the domain itself (not used to separate suffixes or www) can potentially lead to false positives. +.. note:: + + The ``subdomain`` option is also compared against the ``HTTP_HOST`` value, so when the application runs on a + non-standard port, the port must be included as well (for example ``sub.example.com:8080``). + Offsetting the Matched Parameters =================================