Hosts File Setup for Laravel/WordPress Local Development

Laravel and WordPress developers rely on local development environments to build and test applications efficiently. Whether you're using Laravel Valet, Herd, MAMP, or custom setups, proper hosts file configuration is essential for creating realistic local development environments with custom domains. This comprehensive guide covers everything you need to know about configuring hosts files for Laravel and WordPress local development on macOS.

Understanding Local Development Environments

Laravel Valet

Laravel Valet is a lightweight development environment for macOS that uses Nginx and Dnsmasq to automatically serve Laravel and other PHP applications. Valet automatically configures .test domains, making it incredibly easy to work with multiple projects.

Laravel Herd

Laravel Herd is the modern successor to Valet, providing a GUI application for managing local PHP development. Like Valet, Herd handles .test domains automatically through dnsmasq.

WordPress Local Development

WordPress developers often use:

• Local by Flywheel
• MAMP/XAMPP
• Laravel Valet/Herd
• Docker
• Custom server setups

Each requires different hosts file configurations.

Laravel Valet Hosts File Configuration

Automatic .test Domain Setup

Valet automatically handles .test domains through dnsmasq, so you typically don't need manual hosts file edits. However, understanding how it works helps troubleshoot issues.

How Valet Works:

# Valet installs dnsmasq and configures it
valet install

# This creates:
# /usr/local/etc/dnsmasq.conf
# address=/.test/127.0.0.1

# And resolver:
# /etc/resolver/test
# nameserver 127.0.0.1

Any *.test domain automatically resolves to 127.0.0.1.

Basic Valet Setup

# Install Valet
composer global require laravel/valet
valet install

# Park a directory
cd ~/Sites
valet park

# Or link a specific project
cd ~/Sites/my-laravel-app
valet link myapp

Now access at http://myapp.test - no hosts file editing needed!

Custom Domains with Valet

If you need custom domains (not .test), add to hosts file:

# /etc/hosts
127.0.0.1    myapp.local
127.0.0.1    api.myapp.local

Then configure Valet:

valet link myapp --domain=myapp.local

Multiple Projects Organization

Organize your hosts file for multiple Valet projects:

# /etc/hosts
# ===================
# LARAVEL VALET PROJECTS
# ===================
# Note: .test domains handled automatically by Valet
# Only add non-.test domains here

# Custom domain projects
127.0.0.1    client-project.local
127.0.0.1    api.client-project.local

Valet with HTTPS

Valet makes HTTPS trivial:

cd ~/Sites/myapp
valet secure myapp

Access at https://myapp.test - Valet handles certificates automatically via mkcert.

Laravel Herd Configuration

Automatic .test Handling

Herd, like Valet, automatically handles .test domains. The GUI makes it even easier:

1. Install Herd 2. Add your project directory 3. Access via projectname.test

No hosts file configuration needed for standard .test domains.

Herd Custom Domains

For custom domains with Herd:

# /etc/hosts
127.0.0.1    myapp.local

Then configure in Herd GUI or via CLI:

herd link myapp --domain=myapp.local

Herd Site Management

Herd provides excellent site management:

# List all sites
herd list

# Link a site
herd link myapp

# Secure with HTTPS
herd secure myapp

# Unlink
herd unlink myapp

WordPress Local Development Setup

WordPress with Valet/Herd

WordPress works great with Valet and Herd:

# Create WordPress site
cd ~/Sites
mkdir my-wordpress-site
cd my-wordpress-site

# Download WordPress
wp core download

# Link with Valet
valet link wp-site

# Or use Herd GUI

Access at http://wp-site.test - automatic!

WordPress with MAMP

MAMP requires manual hosts file configuration:

# /etc/hosts
127.0.0.1    wordpress.local
127.0.0.1    mywp.local

Then configure MAMP: 1. Set document root to WordPress directory 2. Configure Apache virtual host 3. Set ServerName to wordpress.local

WordPress Multisite Configuration

WordPress Multisite requires careful hosts file setup:

Subdomain Multisite:

# /etc/hosts
127.0.0.1    multisite.test
127.0.0.1    site1.multisite.test
127.0.0.1    site2.multisite.test
127.0.0.1    admin.multisite.test

Subdirectory Multisite (simpler):

# /etc/hosts
127.0.0.1    multisite.test
# Subdirectories handled automatically: multisite.test/site1, multisite.test/site2

WordPress Multisite with Valet

Valet handles WordPress Multisite beautifully:

# Link main site
valet link multisite

# Valet automatically serves subdomains
# site1.multisite.test works automatically!

Configure WordPress: 1. Enable Multisite in wp-config.php 2. Choose subdomain or subdirectory 3. Add sites in Network Admin 4. Access via site1.multisite.test, site2.multisite.test, etc.

WordPress with Local by Flywheel

Local by Flywheel handles hosts file automatically, but you can customize:

# Local creates entries like:
127.0.0.1    mysite.local

To use .test instead, configure in Local settings or manually edit hosts file.

Advanced Configuration Scenarios

Multiple Laravel Projects

Organize multiple Laravel projects:

# /etc/hosts
# ===================
# LARAVEL PROJECTS
# ===================

# Project 1 - E-commerce
# api.shop.test (handled by Valet automatically)
# admin.shop.test (handled by Valet automatically)

# Project 2 - Blog Platform  
# blog.test (handled by Valet automatically)

# Project 3 - Custom domain
127.0.0.1    legacy-app.local
127.0.0.1    api.legacy-app.local

API + Frontend Separation

Separate API and frontend:

# /etc/hosts
# Laravel API
# api.myapp.test (Valet handles automatically)

# Frontend (React/Vue)
127.0.0.1    myapp.test
# Or use Valet: valet link frontend --domain=myapp.test

Frontend at myapp.test, API at api.myapp.test.

Microservices Architecture

For microservices with Laravel:

# /etc/hosts
# Main Application
# app.test (Valet)

# User Service
# users.api.test (Valet)

# Payment Service
# payments.api.test (Valet)

# Notification Service  
# notifications.api.test (Valet)

Each service in its own Valet-linked directory.

Staging/Production Domain Testing

Test with production-like domains:

# /etc/hosts
# Local development with production domain
127.0.0.1    www.myapp.com
127.0.0.1    api.myapp.com

Useful for testing domain-specific configurations, cookies, and SSL.

Choosing the Right TLD

.test (Recommended)

Pros:

• Reserved by IETF
• No conflicts with real domains
• Automatic with Valet/Herd
• Fast resolution

Cons:

• None for local development

Best for: Laravel Valet, Herd, general local development

.local

Pros:

• Common convention
• Easy to remember

Cons:

• Conflicts with macOS Bonjour
• Can be slow
• Requires both IPv4 and IPv6 entries

Best for: Legacy setups, when .test unavailable

Configuration:

# /etc/hosts - Must include both!
127.0.0.1    myapp.local
::1         myapp.local

.localhost

Pros:

• Always resolves to localhost
• No DNS queries
• Very fast

Cons:

• Less common
• Some tools may not recognize

Best for: Simple setups, when you want guaranteed local resolution

.dev

Pros:

• Familiar
• Short

Cons:

• Real TLD (owned by Google)
• Requires HTTPS
• Not recommended for local dev

Avoid: Use .test instead

Organizing Your Hosts File

Project-Based Organization

# /etc/hosts
# ===================
# LARAVEL: E-commerce Platform
# ===================
# shop.test (Valet handles)
# api.shop.test (Valet handles)

# ===================
# WORDPRESS: Client Sites
# ===================
127.0.0.1    client1.local
127.0.0.1    client2.local

# ===================
# PERSONAL PROJECTS
# ===================
# blog.test (Valet handles)

Environment-Based Organization

# ===================
# DEVELOPMENT
# ===================
127.0.0.1    dev.myapp.local

# ===================
# STAGING (Local)
# ===================
127.0.0.1    staging.myapp.local

Client-Based Organization

# ===================
# CLIENT: Acme Corp
# ===================
127.0.0.1    acme.local
127.0.0.1    www.acme.local
127.0.0.1    admin.acme.local

# ===================
# CLIENT: Beta Inc
# ===================
127.0.0.1    beta.local
127.0.0.1    api.beta.local

HTTPS Configuration

Valet HTTPS

Valet makes HTTPS automatic:

cd ~/Sites/myapp
valet secure myapp

Access at https://myapp.test. Valet uses mkcert for trusted certificates.

Herd HTTPS

Herd also handles HTTPS automatically via GUI or CLI:

herd secure myapp

Manual HTTPS Setup

For custom setups, use mkcert:

# Install mkcert
brew install mkcert
mkcert -install

# Create certificate
cd ~/Sites/myapp
mkcert myapp.local "*.myapp.local"

Then configure your web server (Apache/Nginx) to use the certificates.

WordPress HTTPS

For WordPress with HTTPS:

# With Valet
valet secure wp-site

# Update WordPress URLs
wp option update home 'https://wp-site.test'
wp option update siteurl 'https://wp-site.test'

Common Laravel Development Patterns

Laravel + Vue/React Frontend

# Backend API
cd ~/Sites/myapp-api
valet link api

# Frontend
cd ~/Sites/myapp-frontend  
valet link app

# Access:
# Backend: http://api.test
# Frontend: http://app.test

Frontend calls API at http://api.test/api/....

Laravel Multi-Tenant

For multi-tenant applications:

# /etc/hosts
# Tenant 1
127.0.0.1    tenant1.myapp.test

# Tenant 2
127.0.0.1    tenant2.myapp.test

Configure Laravel to detect tenant from domain.

Laravel API + Mobile App Testing

# /etc/hosts
# API accessible from mobile device on same network
# Use Mac's local IP instead of 127.0.0.1
192.168.1.100    api.myapp.test

Mobile device can access API at http://api.myapp.test when on same WiFi.

WordPress-Specific Scenarios

WordPress + WooCommerce

# Standard setup
valet link shop
# Access at shop.test

Test payment gateways, shipping, etc. locally.

WordPress Multisite with Domain Mapping

# /etc/hosts
127.0.0.1    site1.com
127.0.0.1    site2.com
127.0.0.1    multisite.test

Configure WordPress Multisite Domain Mapping plugin to map custom domains.

WordPress Headless (Headless CMS)

# WordPress Backend
valet link wp-api

# Frontend (Next.js, etc.)
valet link frontend

# Access:
# WordPress: http://wp-api.test/wp-json
# Frontend: http://frontend.test

Troubleshooting Common Issues

Issue: .test Domain Not Resolving

Symptoms: Domain doesn't work, connection refused.

Solutions: 1. Check Valet/Herd is running: valet status or check Herd GUI 2. Verify dnsmasq: brew services list | grep dnsmasq 3. Check resolver: cat /etc/resolver/test 4. Restart Valet: valet restart 5. Flush DNS: sudo dscacheutil -flushcache

Issue: .local Domain Slow

Symptoms: .local domains take seconds to load.

Causes: Bonjour/mDNS conflicts.

Solutions: 1. Use .test instead 2. Add IPv6 entry: ::1 myapp.local 3. Disable Bonjour (not recommended)

Issue: Valet Sites Not Working

Symptoms: Valet-linked sites return 404 or connection refused.

Solutions: 1. Check site is linked: valet links 2. Verify directory exists and has index.php 3. Check Nginx config: valet paths 4. Restart Valet: valet restart 5. Check PHP version: valet php --version

Issue: WordPress Multisite Subdomains Not Working

Symptoms: Subdomains return 404.

Solutions: 1. Verify hosts file has all subdomains 2. Check WordPress Multisite configuration 3. Ensure Valet/Herd handles wildcard subdomains 4. Verify .htaccess or Nginx configuration 5. Clear WordPress cache

Issue: HTTPS Certificate Errors

Symptoms: Browser shows certificate warnings.

Solutions: 1. Re-secure with Valet: valet secure myapp 2. Check mkcert is installed: mkcert -install 3. Verify certificate exists: ls ~/.config/valet/Certificates 4. Clear browser cache 5. Check system date/time is correct

Best Practices

1. Use .test Domains

Always prefer .test for local development:

• Automatic with Valet/Herd
• No conflicts
• Fast resolution
• Industry standard

2. Organize by Project

Keep hosts file organized:

# Clear sections
# Comments for context
# Group related domains

3. Document Custom Configurations

Document non-standard setups:

# Custom domain for legacy app
# Requires manual Nginx config
127.0.0.1    legacy.local

4. Use Version Control

For team projects, include hosts file template:

# hosts.example
127.0.0.1    api.myapp.test
127.0.0.1    admin.myapp.test

5. Regular Cleanup

Remove unused entries:

• Archive old projects
• Remove test configurations
• Keep file manageable

6. Leverage Valet/Herd Features

Use built-in features:

• Automatic .test handling
• HTTPS with one command
• Easy site management
• PHP version switching

Integration with Development Tools

Laravel Artisan

# Access via custom domain
php artisan serve --host=myapp.test --port=8000

WordPress WP-CLI

# Configure WordPress URLs
wp option update home 'http://wp-site.test'
wp option update siteurl 'http://wp-site.test'

# Search-replace old URLs
wp search-replace 'http://localhost' 'http://wp-site.test'

Database Access

# Laravel
# Database: myapp
# Host: 127.0.0.1 (or localhost)

# WordPress  
# Same - use 127.0.0.1 or localhost

Git Workflow

# .gitignore
# Ignore local environment files
.env
/public/hot
/storage/*.key

Include hosts file template in repository for team.

Conclusion

Proper hosts file configuration is essential for productive Laravel and WordPress local development. Whether you're using Laravel Valet, Herd, MAMP, or custom setups, understanding how to configure hosts files enables you to:

• Create realistic local development environments
• Test with production-like domains
• Manage multiple projects efficiently
• Configure WordPress Multisite correctly
• Set up complex architectures (APIs, microservices, multi-tenant)

Remember to use .test domains when possible (especially with Valet/Herd), organize your hosts file clearly, and leverage tools like Locahl (€9.99) to manage configurations across projects and team members. With proper setup, local development becomes seamless and efficient.

For Laravel and WordPress developers, Locahl simplifies hosts file management, making it easy to switch between projects, share configurations with teammates, and maintain organized local development environments. Try Locahl today at €9.99 and streamline your development workflow.