Valet Linux Plus Laravel Package

Getting Started

valet-linux-plus is the Linux port of Laravel Valet: a global CLI that runs nginx + dnsmasq + PHP-FPM in the background so *.test domains resolve to local project folders without editing /etc/hosts or vhosts by hand. It is not a Composer dependency you require into an app — you install it globally:

composer global require valet-linux-plus/valet-linux-plus
# ensure ~/.composer/vendor/bin (or ~/.config/composer/vendor/bin) is on PATH
valet install

valet install is the moment of truth: it installs/starts nginx, dnsmasq and PHP-FPM, hooks into NetworkManager/systemd-resolved for DNS, and writes config under ~/.config/valet. If it exits cleanly, valet park ~/Code and open http://mysite.test — that's the first use case, and it's the one that matters most day-to-day.

Where to look first when something is off:

• ~/.config/valet/ — Nginx/ (generated per-site server blocks), Certificates/, Sites/, Log/
• valet paths — confirm which directories are served
• valet which / valet links — confirm what a hostname actually maps to

As of 2.0.3 the package serves both Laravel 11 and 12 out of the box, so on a current Laravel app you should not need per-site PHP juggling just to get APP_URL-correct links and asset URLs.

Implementation Patterns

Park vs. link. valet park ~/Code serves every subdirectory as <dir>.test — ideal for a monorepo of apps or a scratch folder. valet link myapp inside a single project creates a named symlink instead, which is what you want for client work where the folder name (laravel-2023-final-v2) shouldn't become the hostname. Park broad, link selectively.

Per-site PHP isolation. valet isolate [email protected] (run from the site directory) pins one project to a specific PHP-FPM pool while valet use [email protected] changes the global default. Keep a [email protected]/8.2/8.3 set installed via your distro or ondrej/php PPA so isolation never fails mid-task.

TLS locally. valet secure myapp generates a locally-trusted cert and rewrites the site's nginx block for https://myapp.test. Use it whenever the app sets Secure cookies, uses SameSite=None, or exercises a service worker — these break subtly over plain HTTP and you'll waste an afternoon. valet unsecure reverts.

Sharing and proxying. valet share exposes a site publicly (via ngrok-style tunnel) for webhook testing; valet proxy myapp http://localhost:3000 fronts a Vite/Next/Docker backend behind a .test hostname — the cleanest way to avoid CORS pain in a split frontend/backend setup.

Day-to-day loop. valet status after a reboot or a distro upgrade to confirm nginx/php-fpm/dnsmasq are up; valet restart after editing PHP ini; valet open to jump to the current site. Treat valet status as your first diagnostic, not your last.

Gotchas and Tips

• 2.0.3's http2 fix matters if you're on nginx ≥ 1.25. listen ... http2 was deprecated there in favour of http2 on;. Existing secured sites keep their old generated blocks — if nginx -t warns, re-run valet install (or valet unsecure && valet secure) to regenerate the config rather than hand-patching ~/.config/valet/Nginx.
• Don't hand-edit generated nginx configs. They're overwritten on valet install, secure, isolate, and restart. If you need custom directives, add a snippet file and include it from the site block, or use the package's custom-config extension point.
• DNS is the #1 Linux failure mode. .test resolution depends on dnsmasq being wired into NetworkManager or systemd-resolved; VPN clients, resolv.conf rewrites, and distro upgrades routinely break it. Symptom: ping mysite.test fails but nginx serves fine on 127.0.0.1. Fix the resolver, don't touch /etc/hosts as a workaround — it desyncs from valet links.
• Port 80/443 conflicts. Apache, Docker publishing :80, or a stray nginx from the distro package will make valet install appear to succeed while serving the wrong thing. sudo ss -tlnp | grep -E ':(80|443)' before installing.
• PHP-FPM socket version drift. Isolation pins to a socket like php8.2-fpm.sock; upgrading the distro PHP can silently change the socket name and produce 502s. Check ~/.config/valet/Nginx/<site> against ls /run/php/.
• Xdebug slows everything. valet xdebug off for normal browsing; the request latency on .test with Xdebug in develop,debug mode is very noticeable across a full test suite of manual clicks.
• Config lives in your home directory, not the project. Nothing about a site is committed to git except, at most, a note in the README — so onboarding a second machine means re-running park/link/secure/isolate. Worth a three-line bin/setup-local.sh in each repo.
• Upgrade path. Pull 2.0.3 with composer global update valet-linux-plus/valet-linux-plus, then valet install to re-sync generated assets; the Laravel 11/12 support in this release is a driver-compatibility fix, not a migration, so no project-side changes are needed.