Laravel 13 custom domains guide

1. Match a hostname to a customer locally

Laravel exposes the request’s Host through $request->getHost(). Add a small preview route with middleware that matches each hostname to customer data. This lets you test the feature alongside your existing routes.

Start with two .test names. Run php artisan make:middleware ResolveLocalTenant, then replace the generated handle method with this temporary map.

app/Http/Middleware/ResolveLocalTenant.php

The examples call a customer’s account a Tenant. Use your existing account, workspace, or organization model wherever you see that name.

public function handle(Request $request, Closure $next): Response
{
    $tenants = [
        'alpha.test' => ['name' => 'Alpha Publishing'],
        'beta.test' => ['name' => 'Beta Studio'],
    ];

    $host = strtolower(rtrim($request->getHost(), '.'));
    abort_unless(isset($tenants[$host]), 404);

    $request->attributes->set('tenant', $tenants[$host]);

    return $next($request);
}

routes/web.php

use Illuminate\Http\Request;

Route::get('/__domain-preview', function (Request $request) {
    return view('tenant', [
        'tenant' => $request->attributes->get('tenant'),
    ]);
})->middleware('tenant.local');

Add the alias inside your existing withMiddleware callback in bootstrap/app.php:

$middleware->alias([
    'tenant.local' => App\Http\Middleware\ResolveLocalTenant::class,
]);

Create resources/views/tenant.blade.php with a small preview. Keep Blade's normal escaped output:

<h1>{{ $tenant['name'] }}</h1>

If your app or web server filters allowed hosts, admit alpha.test, beta.test, and unknown.test for this check. Run the server in one terminal and the curl requests in another:

php artisan serve --host=127.0.0.1 --port=8084
curl --resolve alpha.test:8084:127.0.0.1 http://alpha.test:8084/__domain-preview
curl --resolve beta.test:8084:127.0.0.1 http://beta.test:8084/__domain-preview
curl --resolve unknown.test:8084:127.0.0.1 -i http://unknown.test:8084/__domain-preview

Checkpoint: Alpha and Beta show different content, while the unknown host returns 404. No DNS or certificate setup is needed.

2. Save each customer’s domains

Move the map into an app-owned table. The hostname is globally unique, and each row belongs to one tenant. A UUID generation gives delayed checks a stable identity even if database IDs can be reused elsewhere.

Schema::create('custom_domains', function (Blueprint $table): void {
    $table->id();
    $table->uuid('generation')->unique();
    $table->foreignId('tenant_id')->constrained();
    $table->string('hostname')->unique();
    $table->string('status')->default('pending');
    $table->timestamps();
});

Normalize before every read or write: trim and lowercase the hostname, remove one trailing dot, convert internationalized labels to ASCII, and reject schemes, paths, ports, IP addresses, wildcards, local names, and malformed labels.

Add a CustomDomain model with tenant() as a belongsTo relationship, and Tenant::domains() as hasMany. Allow mass assignment of generation, hostname, and status, then create through the signed-in tenant relationship. Laravel’s web middleware already checks the token produced by @csrf; keep the form on your normal app hostname.

public function store(Request $request): RedirectResponse
{
    $tenant = $request->user()->tenant;
    $hostname = DomainName::normalize(
        $request->validate(['hostname' => ['required', 'string']])['hostname']
    );

    $tenant->domains()->create([
        'generation' => (string) Str::uuid(),
        'hostname' => $hostname,
        'status' => 'pending',
    ]);

    return back();
}

The browser does not send a trusted tenant ID. Scope every list, update, and removal through the authenticated tenant relationship.

Checkpoint: each customer can reserve a valid hostname, duplicates fail at the database, and cross-customer IDs do not grant access.

3. Connect DNS and HTTPS

The hostname is safely reserved in Laravel. The next step is to point it at the server, hosting platform, or reverse proxy that receives traffic for your app. Give the customer the exact DNS record from that setup.

• For a subdomain such as docs.example.com, use a CNAME pointing at a stable hostname you operate.
• The apex, or root, is example.com. A records point to IPv4 addresses. To support customer apex domains, give customers a stable IPv4 address that keeps routing to your app.
• Many DNS providers do not flatten CNAME records at the apex, so customer onboarding should not depend on that feature.
• Add an AAAA record when your receiving service also provides stable IPv6.

A reverse proxy is a server in front of Laravel that accepts browser traffic and forwards it to the app. Whether you use one or a hosting platform, it needs to accept the customer hostname and preserve the original Host header.

You’ll probably want to check that DNS points directly or indirectly to the service receiving traffic for your app. Tools and managed services can make DNS setup and HTTPS much easier; see the bonus section below for one option.

HTTPS is handled before Laravel receives the request. The receiving service must issue a certificate for every customer hostname and renew it before it expires. Once DNS reaches that service and the certificate is ready, your server-side integration can move the row from pending to active.

curl -I https://customer.example

Checkpoint: the customer hostname reaches your receiving service over HTTPS, with its original Host intact.

4. Serve the customer’s pages

Replace the temporary map with an exact Eloquent lookup. Unknown, pending, and removing hosts must return 404 rather than falling back to a default tenant.

app/Http/Middleware/ResolveTenantDomain.php

public function handle(Request $request, Closure $next): Response
{
    $hostname = DomainName::normalizeRequestHost($request->getHost());

    $domain = CustomDomain::query()
        ->with('tenant')
        ->where('hostname', $hostname)
        ->where('status', 'active')
        ->firstOrFail();

    $request->attributes->set('tenant', $domain->tenant);
    $response = $next($request);
    $response->headers->set('Cache-Control', 'private, no-store');
    $response->headers->set('Vary', 'Host');

    return $response;
}

Have normalizeRequestHost share the configured-domain canonicalization from step two, including lowercase, IDNA conversion, label checks, and trailing-dot removal. Generate this middleware as in step one and register it as tenant.domain in the same alias map. Replace the preview route with the public catch-all below, after your normal app routes. Set domains.control_host in your config to your usual app hostname.

Route::domain(config('domains.control_host'))
    ->middleware('auth')
    ->group(function (): void {
        Route::get('/domains', [DomainController::class, 'index']);
        Route::post('/domains', [DomainController::class, 'store']);
        Route::delete('/domains/{domain}', [DomainController::class, 'destroy']);
    });

Route::middleware('tenant.domain')
    ->get('/{path?}', function (Request $request) {
        return view('tenant', [
            'tenant' => $request->attributes->get('tenant'),
        ]);
    })->where('path', '.*');

The fixed Route::domain keeps management endpoints off customer hosts, while the public catch-all can still serve assets and customer paths. Hostname lookup selects public content; it never authorizes control actions.

These headers prevent shared response caching. If you add an application cache, include the normalized hostname in every key; Vary does not change keys inside your own cache. Build absolute URLs from the saved domain, and leave Laravel session cookies host-only unless you deliberately need a wider scope.

Checkpoint: active hostnames render the right Blade view; unknown, pending, and removing names return 404.

5. Remove a domain safely

Disable routing before asking your hosting layer to detach the hostname and certificate. Keep the unique row while cleanup runs so the name cannot be claimed during a retry.

$domain = $tenant->domains()
    ->where('hostname', DomainName::normalize($input))
    ->firstOrFail();

$started = $domain->status === 'removing'
    || CustomDomain::query()
        ->whereKey($domain->id)
        ->where('tenant_id', $tenant->id)
        ->where('generation', $domain->generation)
        ->whereIn('status', ['pending', 'active'])
        ->update(['status' => 'removing']) === 1;

abort_unless($started, 409, 'Domain changed; reload and try again.');

// Explicit integration point; make this operation safe to retry.
$hosting->removeHostname($domain->hostname);

$hosting is your adapter for the chosen platform, not a Laravel service. Treat timeouts as unknown outcomes, leave the status at removing, and retry the same operation.

After infrastructure confirms it no longer accepts the hostname, delete only where row ID, tenant ID, generation, hostname, and removing status still match. Those conditions keep delayed responses away from a replacement row.

Checkpoint: removal immediately returns 404, retries keep the domain reserved, and the row is released only after cleanup is confirmed.