laravel valet macos

Laravel Valet auf macOS: Das schlanke Dev-Setup für Profis

von

Warum Laravel Valet auf dem Mac so viel Zeit spart

Sie entwickeln täglich Laravel- oder PHP-Anwendungen auf dem Mac und möchten lokale Projekte ohne VMs, ohne ausgewachsene Container-Orchestrierung und ohne Klick-Orgien starten? Dann ist Laravel Valet eines der effizientesten Werkzeuge. Valet richtet auf macOS einen ständig laufenden Nginx ein, löst lokale Domains via Dnsmasq auf und macht jedes Projekt unter einer *.test-Domain sofort verfügbar. Laut offizieller Dokumentation ist die Umgebung extrem ressourcenschonend und für schnelle Iterationen ausgelegt – ideal, wenn Sie viele Repositories parallel checken, testen und verlinken.

In diesem Leitfaden zeigen wir, wie Sie Valet produktiv in Ihren Profi-Workflow integrieren: Installation, Park vs. Link, TLS/HTTP/2, per-Site-PHP-Versionen, Sharing, Proxies zu lokalen Diensten (z. B. Elasticsearch/Docker), Custom Driver, Logs, macOS-Berechtigungen und Troubleshooting. Dazu gibt es einen konkreten Tages-Workflow zum Nachbauen.

Tipp: Wenn Sie frisch mit Laravel starten oder ein Projekt zügig initialisieren möchten, lesen Sie ergänzend unsere Beiträge zu Laravel installieren und Laravel-Projekt erzeugen.

Wie Valet funktioniert – das Prinzip in 60 Sekunden

Valet setzt auf drei Bausteine:

  • Nginx läuft als Hintergrunddienst auf Ihrem Mac und bedient lokale Sites.
  • Dnsmasq weist alle Anfragen an Domains unter der TLD .test auf 127.0.0.1 zu.
  • Konvention vor Konfiguration: Valet erkennt Frameworks/CMS über Driver, die Requests zur passenden Front-Controller-Datei leiten. Viele verbreitete Systeme sind ab Werk unterstützt; für Sonderfälle gibt es Custom Driver.

Der Gewinn: Kein händisches Editieren der Hosts-Datei, kein schwergewichtiger Stack. Sie klonen ein Projekt, verlinken es in Sekunden und können direkt entwickeln – inklusive Subdomains und optionalem TLS.

Installation auf macOS: Vom leeren Mac zur laufenden Dev-Domain

Voraussetzungen: Sie nutzen macOS und haben Homebrew installiert. Stellen Sie sicher, dass kein anderer Webserver (Apache/Nginx) Port 80 belegt.

Aktualisieren Sie zunächst Homebrew und installieren Sie PHP:

brew update
brew install php

Installieren Sie dann Composer global und achten Sie darauf, dass sich $HOME/.composer/vendor/bin im PATH befindet. Anschließend installieren Sie Valet als globales Composer-Paket und führen das Setup aus:

composer global require laravel/valet
valet install

Testen Sie die Auflösung der .test-Domains:

ping foobar.test

Wenn Valet korrekt eingerichtet ist, antwortet die Domain mit 127.0.0.1. Die Valet-Dienste starten künftig automatisch beim Booten Ihres Macs.

Sites bereitstellen: Park vs. Link

Valet kennt zwei grundlegende Mechaniken, um Projekte erreichbar zu machen.

Park: Ein Verzeichnis, viele Projekte

Mit park „merken“ Sie Valet ein Verzeichnis, in dem beliebig viele Projekte liegen. Jede Unterstruktur wird dann sofort als http(s)://<verzeichnisname>.test ausgeliefert.

mkdir -p ~/Sites
cd ~/Sites
valet park

Ein Unterordner laravel ist dann unter http://laravel.test verfügbar. Subdomains funktionieren ebenfalls: http://api.laravel.test löst automatisch auf.

Link: Einzelnes Projekt gezielt binden

Wenn Sie nur ein einzelnes Projekt freischalten möchten, nutzen Sie link im Projektverzeichnis:

cd ~/Sites/laravel
valet link

Das Projekt ist nun unter http://laravel.test erreichbar. Einen eigenen Hostnamen vergeben Sie so:

valet link application
# erreichbar als http://application.test

Auch Subdomains sind möglich:

valet link api.application
# erreichbar als http://api.application.test

Hilfreiche Ergänzungen:

valet links      # zeigt alle Links an
valet unlink     # entfernt den Link des aktuellen Projekts
Erstellung eines Links mit anschließendem Test via Ping

TLS/HTTPS und HTTP/2 lokal aktivieren

Per Default liefert Valet über HTTP aus. Mit secure aktivieren Sie TLS und HTTP/2 für eine Site – Valet erzeugt und hinterlegt ein Zertifikat in der lokalen Nginx-Konfiguration.

# Beispiel: Projekt „laravel“ absichern
valet secure laravel

# Zurück zu HTTP
valet unsecure laravel

Wenn Sie sich tiefer mit HTTP/2 beschäftigen möchten – etwa in Hinblick auf Multiplexing oder Priorisierung – lohnt der Blick in unseren Beitrag HTTP/2-Protokoll aktivieren.

Optional können Sie eine Default-Site setzen, die statt einer 404-Seite bei unbekannten .test-Hosts ausgeliefert wird. Ergänzen Sie in ~/.config/valet/config.json den absoluten Pfad:

{
  "default": "/Users/Sally/Sites/example-site"
}

Pro-Projekt-PHP-Versionen mit Isolate

Projekte leben in unterschiedlichen PHP-Epochen – 8.0, 8.1, 8.2 oder neuer. Valet kann zwar systemweit die PHP-Version wechseln, in der Praxis ist das per-Site-Setup flexibler.

  • Global umschalten:
valet use php@8.2
# oder zurück auf die aktuell verlinkte Brew-Version
valet use php
  • Pro Projekt isolieren:
cd ~/Sites/example-site
valet isolate php@8.0

Wenn Site- und Ordnername nicht übereinstimmen:

valet isolate php@8.0 --site="site-name"
  • Komfortbefehle, die automatisch in die isolierte Version „proxien“:
valet php
valet composer
valet which-php
  • Übersicht aller isolierten Sites:
valet isolated
  • Isolation zurücknehmen:
valet unisolate

Hinweis: Valet bedient immer nur eine PHP-FPM-Instanz gleichzeitig. Mehrere Versionen können installiert sein, aber pro Valet-Laufzeit ist exakt eine aktiv.

Datenbanken lokal: DBngin als All-in-One-Option

Für MySQL, PostgreSQL und Redis empfiehlt die Valet-Dokumentation das kostenlose Tool DBngin. Nach der Installation können Sie sich zu Diensten auf 127.0.0.1 verbinden – typischerweise mit Benutzer root und leerem Passwort für MySQL, sofern so eingerichtet. Das eignet sich besonders für reproduzierbare lokale Setups, ohne Container oder VMs pflegen zu müssen.

Wenn Sie parallel tiefer in Datenbankintegration und Migrationskonzepte in Laravel einsteigen möchten, liefert unser Beitrag Laravel und Datenbank: Eloquent, Migrations & Co. praxisnahe Beispiele.

Projekte live teilen: ngrok, Expose oder Cloudflared

Sie möchten eine Site schnell auf dem Smartphone oder beim Kunden zeigen? Mit valet share erhalten Sie eine öffentliche URL.

Zuerst wählen Sie das Share-Tool:

valet share-tool ngrok
# oder
valet share-tool expose
# oder
valet share-tool cloudflared
Share via Cloudflare

Nicht installierte Tools bietet Valet zum Nachinstallieren an. Für ngrok und Expose benötigen Sie ein Konto und einen Auth-Token, den Sie in Valet hinterlegen. Danach genügt im Projektverzeichnis:

cd ~/Sites/laravel
valet share

Valet kopiert die öffentliche URL automatisch in die Zwischenablage. Beenden Sie die Freigabe mit Ctrl + C im Terminal.

Achtung: Wenn Ihr Mac einen benutzerdefinierten DNS-Server nutzt (z. B. 1.1.1.1), kann ngrok-Freigabe Probleme machen. Stellen Sie in den Netzwerkeinstellungen sicher, dass 127.0.0.1 als erster DNS-Server eingetragen ist, falls nötig.

Zugriff im lokalen Netzwerk erlauben

Standardmäßig beschränkt Valet eingehende Verbindungen auf 127.0.0.1, damit Ihre Dev-Maschine nicht unnötig exponiert wird. Für Tests im LAN können Sie das gezielt aufheben:

  • Für nicht-HTTPS-Sites die Datei /usr/local/etc/nginx/valet/valet.conf bearbeiten.
  • Für per valet secure abgesicherte Sites die Datei ~/.config/valet/Nginx/<site>.test bearbeiten.
  • Entfernen Sie in den listen-Direktiven die Präfixe 127.0.0.1: (Ports 80 und 443), damit Nginx auf allen Interfaces lauscht.
  • Änderungen aktivieren:
valet restart

Danach können Geräte im gleichen Subnetz Ihr Projekt z. B. über http://192.168.1.10/application.test aufrufen.

Site-spezifische Environment-Variablen

Manche Frameworks oder Legacy-Systeme erwarten Server-Variablen über $_SERVER, ohne dass Ihr Projekt diese komfortabel sättigen kann. Valet erlaubt pro Site Umgebungsvariablen via .valet-env.php im Projektroot:

<?php
return [
    // Gilt für laravel.test
    'laravel' => [
        'APP_ENV' => 'local',
        'SOME_FLAG' => '1',
    ],

    // Gilt global für alle Sites
    '*' => [
        'CACHE_DRIVER' => 'file',
    ],
];

Diese Werte landen zur Laufzeit in $_SERVER. Praktisch für Third-Party-Apps, die nicht .env-basiert konfigurierbar sind.

Proxying: Wenn Docker, Datenbanken oder andere Dienste Port 80 blockieren

Valet und Docker konkurrieren häufig um Port 80. Statt ständig Ports umzubauen, leiten Sie eine .test-Domain einfach per Proxy auf einen lokalen Dienst weiter – mit oder ohne TLS.

Beispiel: Elasticsearch unter 127.0.0.1:9200 per elasticsearch.test erreichbar machen:

# HTTP
valet proxy elasticsearch http://127.0.0.1:9200

# TLS + HTTP/2
valet proxy elasticsearch http://127.0.0.1:9200 --secure

# Proxy löschen
valet unproxy elasticsearch

# Übersicht anzeigen
valet proxies

Das funktioniert auch für Backend-APIs, Node-Server oder Dienste aus Docker-Compose-Stacks, die Ihnen feste Ports liefern.

Eigene Valet-Driver schreiben

Valet erkennt viele Frameworks automatisch. Für Spezialfälle implementieren Sie einen eigenen Driver und legen ihn in ~/.config/valet/Drivers/ ab. Drei Methoden sind zentral:

  • serves($sitePath, $siteName, $uri): bool – entscheidet, ob dieser Driver für eine Site zuständig ist (z. B. anhand von Verzeichnisstrukturen).
  • isStaticFile(...) – liefert den Pfad zu statischen Dateien zurück oder false.
  • frontControllerPath(...): string – liefert den Pfad zum Front Controller (z. B. public/index.php).

Minimalbeispiel für einen lokalen, an Laravel angelehnten Driver im Projektroot:

<?php
use Valet\Drivers\LaravelValetDriver;

class LocalValetDriver extends LaravelValetDriver
{
    public function serves(string $sitePath, string $siteName, string $uri): bool
    {
        return true; // Nur für dieses Projekt
    }

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

Custom Driver sind der Hebel für Monorepos, ungewöhnliche Public-Pfade oder CMS, die Valet nicht out of the box kennt.

Diagnose, Logs und hilfreiche Valet-Befehle

Für den Alltag und das Debugging sollten diese Kommandos sitzen:

valet list                # alle Befehle
valet diagnose            # Diagnoseausgabe
valet paths               # geparkte Pfade
valet forget              # Verzeichnis nicht mehr als „geparkt“ behandeln
valet start|stop|restart  # Dienste steuern
valet log                 # Logdateien-Übersicht
valet directory-listing   # Verzeichnislisting aktivieren/deaktivieren
valet uninstall --force   # Hard-Reset (anschließend valet install)

Wichtige Pfade für Konfiguration und Logs:

  • ~/.config/valet/ – zentrale Valet-Konfiguration (Backup sinnvoll)
  • ~/.config/valet/dnsmasq.d/ – Dnsmasq-Settings
  • ~/.config/valet/Nginx/ – Nginx-Site-Konfigurationen (werden u. a. bei install und secure neu geschrieben)
  • ~/.config/valet/Sites/ – Symlinks für valet link
  • ~/.config/valet/valet.sock – PHP-FPM-Socket
  • ~/.config/valet/Log/fpm-php.www.log – PHP-User-Log
  • ~/.config/valet/Log/nginx-error.log – Nginx-User-Errors
  • /usr/local/var/log/php-fpm.log – System-PHP-FPM-Log
  • /usr/local/var/log/nginx – Nginx Access/Error Logs
  • /usr/local/etc/php/X.X/conf.d – PHP-Ini-Fragmente
  • /usr/local/etc/php/X.X/php-fpm.d/valet-fpm.conf – PHP-FPM-Pool

Wenn die Installation zickt, hilft oft ein „sauberes“ Neuaufsetzen:

composer global require laravel/valet
valet install

# Im Notfall
valet uninstall --force
valet install

macOS-Sicherheitszonen und Vollzugriff für Nginx

Seit macOS 10.14 schützt das System bestimmte Ordner stärker (u. a. Schreibtisch, Dokumente, Downloads) sowie Netz- und Wechsellaufwerke. Legen Sie Ihre Projektordner am besten außerhalb dieser Bereiche an – z. B. ~/Sites.

Wenn Sie dennoch aus geschützten Orten ausliefern, braucht Nginx „Vollzugriff auf Festplatten“. macOS fragt in vielen Fällen automatisch, andernfalls aktivieren Sie den Zugriff in den Systemeinstellungen unter „Datenschutz & Sicherheit“ im Bereich „Vollzugriff auf Festplatten“ und setzen die Häkchen bei den Nginx-Einträgen. Die genaue Bezeichnung variiert je nach macOS-Version.

Ein praxistauglicher Daily-Workflow mit Valet

Ein Beispiel, wie ein typischer Tag mit Valet aussieht – schnell, deterministisch und teamtauglich:

1) Grundsetup

mkdir -p ~/Sites && cd ~/Sites
valet park

2) Neues Projekt anlegen

cd ~/Sites
composer create-project laravel/laravel blog
cd blog
valet link blog

3) PHP-Version festnageln

valet isolate php@8.2

Alternativ per .valetrc im Projekroot:

echo "php=php@8.2" > .valetrc
valet use

4) HTTPS aktivieren

valet secure blog

5) DB lokal starten

  • DBngin: MySQL/Redis/Postgres starten
  • Laravel .env auf 127.0.0.1 konfigurieren

6) Temporäres Sharing

valet share-tool ngrok
valet share
# URL aus der Zwischenablage an Stakeholder schicken

7) Service-Proxies

# Lokale API (Node) auf 3000 verfügbar machen
valet proxy api http://127.0.0.1:3000 --secure

8) Entwicklungsaufgaben in Laravel

Für wiederkehrende Jobs, Cron-Ersatz und koordinierte Aufgaben in der lokalen Entwicklungsphase lohnt unser Beitrag Laravel Scheduler einrichten und nutzen. Sobald die Anwendung wächst, sind Jobs & Queues in Laravel ein Muss – lokal mit Valet problemlos testbar.

9) Aufräumen & Diagnose

valet links
valet log
valet diagnose

Mit diesem Setup bleiben Sie flexibel: Monorepos, mehrere Projekte parallel, verschiedene PHP-Stände – alles unter .test konsistent abrufbar.

Valet im Kontext: Wann es besser passt als Sail oder Homestead

Valet ersetzt Docker-basierte Setups (Sail) oder Vagrant-VMs (Homestead) nicht generell, aber punktuell ist es überlegen:

  • Wenn Sie sehr viele Repositories schnell an- und abklemmen müssen, ohne Images/VMs zu bauen.
  • Wenn Sie minimale Latenz wünschen – Nginx + FPM auf localhost ist sehr direkt.
  • Wenn Teamkollegen auf dem Mac einheitliche .test-Konventionen nutzen wollen.

Für Produktionsnähe, reproduzierbare Container und OS-Parität bleibt Sail/Containers die bessere Wahl. Valet bietet dafür die schnellste lokale Iteration.

Häufige Stolpersteine und wie Sie sie vermeiden

  • Port-80-Kollisionen: Prüfen Sie, dass kein Apache/Nginx oder anderer Dienst Port 80 belegt. Stoppen/deaktivieren Sie konkurrierende Dienste, bevor Sie valet install ausführen.
  • DNS-Auflösung: *.test muss auf 127.0.0.1 zeigen. Der Ping-Test nach der Installation deckt fehlerhafte Dnsmasq-Konfigurationen auf.
  • PHP-Fehler: Sehen Sie ins FPM-Log (~/.config/valet/Log/fpm-php.www.log) und in die Nginx-Error-Logs, wenn eine Site weiße Seiten liefert.
  • „Full Disk Access“: Statische Assets laden nicht? Nginx braucht ggf. Vollzugriff, wenn Projekte in geschützten Ordnern liegen.
  • Share-Probleme: ngrok streikt mit Custom-DNS? 127.0.0.1 als ersten DNS-Server setzen.

Mit diesen Checks lösen Sie 90 % der lokalen Valet-Probleme in Minuten.

Ohne schweres Gerät produktiv zu arbeiten, fühlt sich mit Valet schnell selbstverständlich an. Wenn Sie Ihren Laravel-Stack weiter schärfen möchten, stöbern Sie in unserer Kategorie Laravel oder auf dem ADMIN CODE Blog. Für Fragen zu Setups, Automatisierung und Workflows schreiben Sie uns gern – wir teilen gern praxiserprobte Ansätze aus Projekten.