Valet Linux Laravel Package

Getting Started

Valet Linux is a per-machine daemon stack (nginx + dnsmasq + php-fpm, driven by systemd) plus a CLI that maps directories to *.test hostnames. You install it once per workstation; after that the daily loop is valet link / valet park and a browser.

Minimal setup on Debian/Ubuntu:

sudo apt install nginx dnsmasq libnss3-tools \
  php8.3-cli php8.3-fpm php8.3-curl php8.3-mbstring php8.3-xml php8.3-zip

composer global require cpriego/valet-linux
export PATH="$PATH:$(composer global config bin-dir --absolute)"
valet install          # sudo prompts; configures dnsmasq, nginx, sudoers
valet --version        # confirm it's on PATH before anything else

First use case — serve a directory of projects with zero config:

mkdir -p ~/Code && cd ~/Code
valet park             # every subfolder is now <folder>.test
laravel new blog       # then visit http://blog.test
valet open blog        # opens the default browser

Where to look first:

• valet status — is nginx/dnsmasq/php-fpm actually up?
• ~/.config/valet/ (older 2.x installs: ~/.valet/) — config.json, the Sites/ symlink directory, generated nginx site configs, and logs. This directory is Valet's state; almost every problem is diagnosable here.
• valet --help then valet <command> --help — the command surface is small and self-documenting.

Check http://blog.test before touching .env or nginx by hand. If that responds, PHP and DNS are fine and your problem is application-level.

Implementation Patterns

Pick the right mapping primitive. Three commands cover nearly everything:

link is the workhorse — it's a symlink into ~/.config/valet/Sites, so you can valet unlink and re-link freely without touching the project.

Standard Laravel project with the side services proxied in. Valet gives you PHP but no database, queue worker, or mail catcher. Compose those yourself and give them hostnames so nothing is a 127.0.0.1:port in your head:

valet proxy mail.test  http://127.0.0.1:8025    # Mailpit
valet proxy minio.test http://127.0.0.1:9001
# .env
MAIL_HOST=mail.test

Isolate PHP per site. Mixed-version portfolios are the common case; isolate rewrites the site's nginx fastcgi_pass to the right fpm socket without touching global PHP:

cd ~/Code/legacy-app && valet isolate php8.1
cd ~/Code/legacy-app && valet unisolate
valet use php8.3            # global default for everything else

Wildcard subdomains come free. dnsmasq resolves *.test, so Laravel multitenancy (tenant.test, {tenant}.myapp.test) needs no /etc/hosts edits. Just make sure your route constraints and APP_URL agree on the TLD.

HTTPS when a third party demands it. valet secure myapp provisions a locally-trusted cert; this is what makes Socialite callbacks, session cookies with Secure, and webhook providers that reject http:// testable at all. Pair with valet share myapp to expose it publicly for inbound webhooks — much less friction than a reverse tunnel you configure yourself.

Custom driver for a non-standard docroot. Laravel's public/, WordPress, and static sites are built in. For Symfony, Drupal, Craft, or a monorepo with apps/web/public, drop a class in ~/.config/valet/Drivers:

<?php
class MonorepoValetDriver extends BasicValetDriver
{
    public function serves(string $sitePath, string $siteName, string $uri): bool
    {
        return is_dir($sitePath.'/apps/web/public');
    }

    public function frontControllerPath(string $sitePath, string $siteName, string $uri): ?string
    {
        return $sitePath.'/apps/web/public/index.php';
    }
}

Drivers are the sanctioned extension point — prefer one over hand-editing nginx configs, which get regenerated on secure/isolate.

Onboarding teammates. Valet is machine-local, so don't put it in the repo as a hard requirement. A short bin/setup.sh that checks for valet, prints the install one-liner, and runs valet link is enough; keep Docker/Sail as the parity fallback for CI and for anyone unwilling to give up port 80.

Gotchas and Tips

• Port 80 is the single most common failure. sudo ss -tlnp | grep ':80' — a distro Apache, a stray nginx, or a Docker publish will silently win and you'll get connection refused, not an error from Valet. sudo systemctl disable --now apache2 on fresh Ubuntu.
• DNS breaks more often than nginx. Valet registers a NetworkManager dispatcher to point lookups at dnsmasq. systemd-resolved's stub on 127.0.0.53 and VPN split-DNS both fight it. Symptom: curl to the .test host fails with "could not resolve" while 127.0.0.1 works. Diagnose with resolvectl status and dig @127.0.0.1 myapp.test, then valet restart and reconnect the network. A reboot after valet install fixes a surprising share of first-run issues.
• Never use .dev or .app. Both are HSTS-preloaded and browsers will force HTTPS regardless of what Valet serves. Stay on .test; if you change it (valet tld local), re-secure anything you'd already secured and restart.
• Install as your user, not with sudo valet install's side effects. Running Valet commands as root creates root-owned files in the config directory and in project storage/, which then breaks php artisan and asset compilation in confusing ways.
• fpm socket names are hardcoded in the generated vhost. If PHP comes from a PPA or a non-distro build, the socket may be php8.3-fpm.sock vs www.sock; you get a 502 with connect() failed in the nginx error log. Check ls /run/php/, then align the version via valet isolate/valet use rather than editing the vhost.
• park is exactly one directory deep. Subfolders of projects are not served, which is usually what you want — but nested monorepos need link per app.
• Link names must be valid DNS labels. No underscores, no dots; valet link api_v2 will create a vhost you can't resolve.
• Xdebug will halve your throughput. Keep it off globally (valet xdebug off where supported, or disable in the fpm ini) and toggle it on for a debugging session only. If a request hangs instead of erroring, suspect Xdebug trying to reach an IDE that isn't listening.
• Logs: valet log tails the Valet-managed logs; failures before nginx gets involved show up in journalctl -u nginx -u dnsmasq. Laravel's own 500s are in storage/logs/laravel.log — check which layer you're in before changing config.
• Maintenance risk is real. ~1.5k stars and a small maintainer pool means releases are sporadic and Ubuntu version bumps occasionally break the installer. Pin the Composer version in your notes, and re-run valet install (not just composer global update) after every upgrade, since templates and systemd units ship with the install step. Upgrades from 2.x to 3.x moved the config directory and introduced the driver API — budget an afternoon to re-link sites if you're coming from an old install.
• Certificates on Chromium/Firefox need NSS. libnss3-tools plus mkcert -install (if your Valet version delegates to it) or manually importing the CA into the browser store — otherwise valet secure works in curl but shows a warning in the browser.