What is a Hostname Route?

A Hostname Route matches requests based on the host part of the URL (e.g., admin.example.com, api.example.com, etc.), not just the path. It’s useful for multi-site, subdomain-based routing, or API versioning.

Use Case Examples

Full Example

Step 1: Host Entry

Edit your hosts file

  Open your system’s hosts file:

• Windows: C:\Windows\System32\drivers\etc\hosts
• Linux/macOS: /etc/hosts

Add this line to simulate a custom domain:

127.0.0.1   admin.localhost

Access your app via browser:

http://admin.localhost:8080/

In your Zend (Laminas) route config, use:

'route' => 'admin.localhost'

Step 2: Route Configuration (module/Application/config/module.config.php)

'router' => [
  'routes' => [
    'admin' => [
      'type' => \Laminas\Router\Http\Hostname::class,
      'options' => [
        'route' => 'admin.localhost',
        'defaults' => [
          'controller' => Controller\MainController::class,
          'action' => 'dashboard',
        ],
      ],
      'may_terminate' => true,
      'child_routes' => [
        'default' => [
          'type' => \Laminas\Router\Http\Literal::class,
          'options' => [
            'route'    => '/about',
            'defaults' => [
              'controller' => Controller\MainController::class,
              'action'     => 'about',
            ],
          ],
        ],
      ],
    ],
  ],
],

Step 3: Controller Setup (module\Application\src\Controller\MainController.php)

namespace Application\Controller;

use Laminas\Mvc\Controller\AbstractActionController;
use Laminas\View\Model\ViewModel;

class MainController extends AbstractActionController
{
    public function dashboardAction()
    {
        return new ViewModel();
    }
    public function aboutAction()
    {
        return new ViewModel();
    }
}

Step 4: View Files

File: view/application/main/dashboard.phtml

<div>Dashboard page</div>

File:view/application/main/about.phtml

<h2>About Page</h2>
<p>This is the static About page.</p>

Access in Browser