Od nerwów do porządku – jak podejść do Laravela na Windowsie z głową
Skąd biorą się „magiczne błędy” przy Laravelu na Windowsie
Pierwszy kontakt z Laravelem na Windowsie dla wielu osób wygląda podobnie: ktoś pokaże proste polecenie z dokumentacji, wszystko niby jest zrobione, a terminal odwdzięcza się czerwonym komunikatem, którego treść brzmi jak z innej planety. W tle zwykle nie ma żadnej magii – tylko kilka chaotycznych elementów: różne wersje PHP, kilka instalacji Composera, brakujące rozszerzenia, źle ustawiona zmienna PATH albo pliki projektu trzymane w katalogu, który wolno działa z powodu antywirusa czy OneDrive.
Laravel sam w sobie jest dość przewidywalny. Większość „dziwnych” błędów bierze się z otoczenia: systemu, konfiguracji serwera HTTP, wersji PHP i MySQL. Windows nie jest domyślnym środowiskiem dla większości poradników PHP, więc sporo instrukcji nie wspomina o krokach specyficznych dla tej platformy. Stąd błędy typu „php is not recognized as an internal or external command”, komunikaty o brakujących rozszerzeniach ext-xyz albo problemy z uprawnieniami w katalogu projektu.
Dobrym porównaniem jest jazda samochodem po innym kraju: zasady ruchu niby te same, ale znaki i nawyki kierowców inne. Laravel jest tym samym frameworkiem, ale „drogi” – system, ścieżki, narzędzia – na Windowsie działają odrobinę inaczej. Kluczem do spokoju jest uporządkowanie tych elementów i trzymanie się jednego, spójnego schematu pracy.
„Działa jakoś” kontra „działa stabilnie i przewidywalnie”
Laravel da się zmusić do działania na prawie każdym Windowsie, jednak prawdziwa różnica pojawia się wtedy, gdy środowisko jest ustawione raz a dobrze, a kolejne projekty tworzy się w kilka minut. „Działa jakoś” oznacza zwykle:
projekt uruchamia się, ale co kilka dni wyskakuje nowy błąd po aktualizacji PHP lub Composera,
ciężko odtworzyć środowisko na drugim komputerze, więc współpraca w zespole to loteria,
front-end kompiluje się raz, a raz dostaje się błędy zależności Node.js,
zmiana jednej rzeczy w konfiguracji powoduje lawinę kolejnych problemów.
Natomiast „działa stabilnie i przewidywalnie” to sytuacja, w której:
znasz dokładną wersję PHP, jakiej używa projekt i potrafisz ją świadomie zaktualizować,
Composer, Node.js i baza danych są częścią jednego, opisanego zestawu (np. Docker Compose lub konfiguracja w WSL2),
każdy nowy projekt uruchamiasz kilkoma znanymi komendami, bez eksperymentów,
jeśli coś się psuje, wiesz w jakiej warstwie szukać: aplikacja, PHP, serwer czy baza.
W praktyce różnica polega na tym, że przestajesz „walczyć z komputerem”, a wracasz do pracy nad kodem. To podejście szczególnie widać w większych projektach, gdzie aktualizacja jednej biblioteki bez dobrego środowiska potrafi zająć pół dnia.
Przegląd dróg: natywny Windows, WSL2, Docker/Sail
Na Windowsie istnieją trzy główne sposoby na wygodne postawienie Laravela:
Natywna instalacja – PHP, Composer i często serwer HTTP (Apache/Nginx) instalowane bezpośrednio w Windowsie, czasem przez XAMPP/WampServer.
WSL2 – czyli warstwa, która pozwala uruchomić pełnoprawnego Linuksa „w środku” Windowsa i tam zainstalować PHP, Composera, Node itd.
Docker + Laravel Sail – infrastruktura kontenerowa, w której Laravel działa w zdefiniowanym zestawie kontenerów (PHP, MySQL, Redis, itp.), odizolowanych od systemu.
Każda opcja ma swoje mocne strony. Natywna jest najprostsza na start, WSL2 daje środowisko bardzo zbliżone do serwera produkcyjnego, a Docker pozwala niemal jeden do jednego odtworzyć konfigurację z chmury czy VPS. Wybór zależy od tego, jak duże projekty chcesz prowadzić, z kim współpracujesz i czy planujesz pracę zespołową.
Docelowy obraz: jeden spójny stos narzędzi
Celem nie jest samo „odpalenie” Laravela, tylko spójne środowisko deweloperskie. Bez względu na to, czy wybierzesz natywny Windows, WSL2 czy Docker, docelowo chodzi o to, aby:
mieć jedną, działającą wersję PHP (lub świadomie kilka),
korzystać z jednego Composera, który wie, gdzie jest PHP,
mieć działającą bazę danych (MySQL/MariaDB/PostgreSQL) i znać jej dane logowania,
posiadać Node.js do obsługi assetów front-endowych,
umieć wywołać php artisan serve lub sail up i w przewidywalny sposób zobaczyć aplikację pod konkretnym adresem.
Z takiego uporządkowanego stosu łatwo potem przejść do automatyzacji, CI/CD czy deploymentu. Bez niego każdy kolejny projekt będzie wymagał „rytuału odprawiania błędów” i wróżenia z logów.
Wymagania wstępne – co musi być ogarnięte zanim pojawi się Laravel
Sprawdzenie wersji Windows i wsparcia dla WSL2
Zanim zaczniesz, dobrze jest wiedzieć, na czym dokładnie się stoi. Od tego, jaką wersję Windows masz, zależy dostępność WSL2, a pośrednio także komfort pracy z Dockerem. Najważniejsze punkty:
Windows 10 – pełna obsługa WSL2 zaczyna się od wersji 2004 (build 19041) i wyżej. W starszych buildach bywa problematyczna.
Windows 11 – WSL2 jest tu „pierwszą klasą obywateli”, w większości przypadków działa od razu po włączeniu odpowiednich funkcji.
Home vs Pro – w kontekście WSL2 nie ma dużej różnicy, ale w przypadku niektórych opcji wirtualizacji (np. starsze Hyper-V) Pro bywa wygodniejszy. Docker Desktop na nowszych Windowsach korzysta już głównie z WSL2, więc Home jest jak najbardziej OK.
Wersję systemu sprawdzisz skrótem Win + R, wpisując winver. Jeśli chcesz korzystać z WSL2 i Docker Desktop, opłaca się zaktualizować system do najnowszego wydania. Oszczędzi to później kłopotów z niezgodnymi wersjami jąder, błędami wirtualizacji i innymi „atrakcjami”.
Podstawy pracy z terminalem: PowerShell i konsola
Laravel to framework, który kocha terminal. Komendy composer, php artisan, npm run dev czy ./vendor/bin/sail to codzienność. Nie trzeba być mistrzem skryptów PowerShella, ale przydatne jest swobodne:
poruszanie się po katalogach (cd, ls lub dir),
tworzenie folderów (mkdir),
uruchamianie programów z terminala (np. php -v, composer -V),
edytowanie plików konfiguracyjnych lub przynajmniej ich podgląd (type, cat w WSL).
Praktyczna rada: zamiast klasycznego „Wiersza polecenia” warto używać Windows Terminal – pozwala na kilka kart (PowerShell, WSL, CMD) i ułatwia życie, gdy przełączasz się między Windows a Linuksem. Dobrze jest też nawyknąć do uruchamiania terminala z poziomu folderu projektu (np. z kontekstowego menu w Eksploratorze lub bezpośrednio z VS Code).
Czym właściwie jest „środowisko deweloperskie” dla Laravela
Aby Laravel mógł działać, potrzebuje kilku elementów jednocześnie. Na produkcji zwykle zajmuje się tym administrator lub DevOps, w środowisku lokalnym – Ty. Kluczowe składniki to:
PHP – w wersji zgodnej z daną wersją Laravela (np. Laravel 10 wymaga co najmniej PHP 8.1),
serwer HTTP – Apache, Nginx lub wbudowany serwer PHP (do lokalnego developmentu),
serwer bazy danych – MySQL, MariaDB, PostgreSQL lub inny wspierany przez ORM Eloquent,
Composer – menedżer zależności PHP, odpowiednik npm dla świata PHP,
Node.js – do kompilacji assetów (Vite, Webpack), uruchamiania npm run dev, npm run build czy korzystania z narzędzi JS.
Te elementy muszą się „widzieć” i nie wchodzić sobie w drogę. Jeśli masz kilka wersji PHP, ważne jest, z której korzysta Composer i której używa serwer HTTP. Jeśli używasz Dockera – większość tego „bałaganu” jest zamknięta w kontenerach, ale nadal przydaje się rozumieć, co tam się dzieje.
Dlaczego na Windowsie opłaca się izolować środowisko
Na Linuksie czy macOS instalowanie PHP bezpośrednio w systemie jest dość naturalne – wszystko jest do tego przystosowane. Windows historycznie nie był głównym celem dla PHP, przez co:
niektóre rozszerzenia PHP są trudniejsze do doinstalowania,
narzędzia pokroju XAMPP tworzą trochę „magiczne pudełko”, w którym nie zawsze wiadomo, co gdzie leży,
różne programy (np. inne środowiska programistyczne) mogą nadpisywać PATH i wywoływać konflikty wersji.
Stąd popularność dwóch dróg: WSL2 (izoluje cały Linuxowy świat od Windowsa) oraz Docker (zamyka środowisko w kontenerach). Zyskujesz powtarzalność: na innym komputerze wystarczy włączyć te same skrypty lub pliki docker-compose.yml/.sh, aby uzyskać identyczne środowisko. W dużych projektach to różnica między „u mnie działa” a „wszędzie działa tak samo”.
Źródło: Pexels | Autor: cottonbro studio
Co wybrać? Przegląd opcji instalacji Laravela na Windowsie
Natywna instalacja na Windowsie – plusy i minusy
Natywna instalacja oznacza, że PHP, Composer, MySQL i ewentualny Apache/Nginx działają bezpośrednio w Windowsie, bez dodatkowej warstwy. Najczęściej spotykany scenariusz to:
instalacja XAMPP lub WampServera,
doinstalowanie Composera,
tworzenie projektów Laravel w katalogu serwera HTTP (np. htdocs).
Zalety:
prosty start dla osób przyzwyczajonych do „klikanych” instalatorów,
łatwy podgląd bazy danych (phpMyAdmin w pakietach typu XAMPP),
mniej warstw pośrednich – wszystko działa w jednym systemie.
Wady:
mniej zbliżone do środowiska produkcyjnego (które zwykle stoi na Linuksie),
potencjalne konflikty między wersjami PHP/Apache, jeśli instalujesz coś ręcznie obok XAMPP,
trudniejsza reprodukcja środowiska na innych maszynach,
cięższe debugowanie problemów z uprawnieniami i ścieżkami w środowisku mieszanym.
Dla prostych projektów, lokalnych narzędzi czy nauki samego Laravela natywna instalacja jest jak najbardziej do przyjęcia. Przy większych aplikacjach czy współpracy zespołowej coraz wyraźniej wygrywa WSL2 lub Docker.
WSL2 – Linux w środku Windowsa
WSL2 (Windows Subsystem for Linux 2) to rozwiązanie Microsoftu, które uruchamia pełny kernel Linuksa i dystrybucję (np. Ubuntu) bez konieczności osobnej maszyny wirtualnej w stylu VirtualBox. Z punktu widzenia Laravela oznacza to tyle, że:
instalujesz PHP, MySQL i Composera prawie identycznie jak na serwerze produkcyjnym,
masz pełen dostęp do systemu plików i narzędzi Linuxowych (grep, sed, cron, itp.),
możesz używać edytora z Windowsa (np. VS Code) i kodować w katalogu trzymanym po stronie WSL.
Zaletą jest bardzo wysoka zgodność z typowym serwerem Laravelowym, a także dobra integracja z Dockerem (Docker Desktop potrafi używać WSL2 jako backendu). Wadą bywa pierwsza konfiguracja i konieczność przełączania się między „światami” Windows i Linux, ale po kilku dniach staje się to naturalne.
Docker i Laravel Sail – kiedy to najlepsza ścieżka
Docker to warstwa, która pozwala uruchomić całą aplikację w kontenerach – lekkich, odizolowanych środowiskach. Laravel ma własny, oficjalny zestaw kontenerów pod nazwą Laravel Sail. W praktyce:
komunikacja z aplikacją odbywa się przez ./vendor/bin/sail,
PHP, MySQL, Redis, MailHog i inne usługi działają w osobnych kontenerach,
wersje zależności są zapisane w docker-compose.yml, więc całe środowisko można odtworzyć jednym poleceniem.
To świetne rozwiązanie, gdy:
Gdzie Docker i Sail błyszczą najmocniej
Najlepsze efekty Sail daje przy projektach, gdzie lokalne środowisko musi być bardzo podobne do produkcji albo gdzie w grę wchodzi więcej niż jeden serwis. Typowe sytuacje:
aplikacja Laravel + front w osobnym SPA (React/Vue) + Redis + kolejki,
kilka mikroserwisów, które na produkcji i tak działają w kontenerach,
zespół kilku–kilkunastu osób, który musi mieć identyczne środowisko niezależnie od systemu.
W takich scenariuszach tradycyjne „instaluję sobie wszystko lokalnie” szybko kończy się mailem na Slacku: „u mnie działa, u ciebie nie, bo masz inną wersję MySQL”. Sail i Docker zapisują całe środowisko w konfiguracji – różnice między maszynami znikają.
Jeśli dopiero zaczynasz i masz mały projekt, Docker może wydawać się armatą na muchę. Można wtedy zacząć natywnie lub z WSL2, a do Sail dojrzeć przy pierwszej większej aplikacji. Dobrze jest jednak zawczasu wiedzieć, jaki masz zestaw opcji i kiedy która z nich oszczędzi ci nerwów.
Wariant 1 – Natywna instalacja PHP, Composer i Laravela na Windowsie
Scenariusz: kiedy natywna instalacja ma sens
Taki wariant jest najprostszy, gdy:
robisz mały projekt do nauki albo prototyp,
nie korzystasz z Dockera na co dzień i nie chcesz na start ogarniać dodatkowej warstwy,
masz słabszy komputer lub mało RAM-u – Docker by go po prostu zamęczył.
Można to porównać do pierwszego auta. Nie musi to być od razu kombajn z automatem i 15 trybami jazdy – ważne, żeby odpalał i jechał prosto. Poniżej układ „minimum bólu” na Windowsie.
Instalacja PHP na Windowsie bez XAMPP-a
Da się oczywiście postawić PHP z XAMPP-em lub WampServerem, ale często wygodniej mieć PHP jako osobny program, niezależny od całego stosu Apache+MySQL. Dzięki temu:
sam decydujesz, jakiej wersji PHP używa Composer i Laravel,
łatwiej potem przejść na inne rozwiązanie (np. WSL2),
nie jesteś przywiązany do jednego katalogu typu htdocs.
Praktyczny schemat:
Pobierz binaria PHP dla Windowsa (np. z oficjalnej strony windows.php.net) w wersji zgodnej z planowaną wersją Laravela.
Rozpakuj je w prostą ścieżkę, np. C:php.
Dodaj C:php do zmiennej środowiskowej PATH, tak aby w terminalu zadziałało php -v.
W php.ini włącz najważniejsze rozszerzenia (np. mbstring, openssl, pdo_mysql), usuwając średnik na początku linii.
Jeśli do tego używasz VS Code i Windows Terminal, całość zaczyna przypominać „normalne” środowisko programistyczne, a nie magiczną skrzynkę z przyciskiem „Start Apache”.
Composer – serce zależności Laravela
Composer na Windowsie ma wygodny instalator „next-next-finish”, ale warto zwrócić uwagę na jedną rzecz: z jakim PHP się wiąże. Instalator zwykle:
pyta o ścieżkę do php.exe,
na podstawie tego wyboru tworzy globalne polecenie composer.
Jeżeli wcześniej zadbałeś o czystą instalację PHP w C:php, sytuacja jest prosta – wskazujesz tego php.exe i masz spójny zestaw. Po instalacji:
composer -V
powinno wyświetlić wersję Composera, co jest dobrym testem, czy PATH działa jak należy.
MySQL lub MariaDB – baza danych po Windowsowemu
Tutaj są dwa główne kierunki:
osobna instalacja MySQL/MariaDB z oficjalnego instalatora,
pakiet w stylu XAMPP/Wamp, który stawia MySQL razem z Apache i narzędziami.
Jeżeli stawiasz na lekkość, często wystarczy sam serwer bazodanowy z GUI (np. MySQL Workbench) lub zewnętrzny klient typu DBeaver. Laravelowi jest wszystko jedno, czy serwer stoi obok PHP, czy osobno – ważne, aby zgadzały się parametry połączenia w .env:
Na Windowsie zdarza się, że port 3306 jest zajęty przez inną usługę – jeśli MySQL nie startuje, pierwsze co warto sprawdzić, to kolizje portów w usługach systemowych.
Tworzenie nowego projektu Laravel natywnie
Zakładając, że PHP i Composer działają, przejście do nowego projektu to kilka komend. Typowa ścieżka:
Wybierz katalog roboczy, np. C:projekty, i przejdź tam w terminalu:
cd C:projekty
Utwórz projekt:
composer create-project laravel/laravel blog
Wejdź do katalogu projektu:
cd blog
Uruchom wbudowany serwer:
php artisan serve
Po chwili w przeglądarce pod adresem http://127.0.0.1:8000 powinien pojawić się ekran startowy Laravela. Dla większości scenariuszy developmentowych taki wbudowany serwer w zupełności wystarczy; osobny Apache czy Nginx można sobie darować na początek.
Node.js i Vite – czyli co z JavaScriptem
Laravel 9+ korzysta standardowo z Vite, co oznacza, że do komfortowej pracy z assetami przyda się Node.js. Instalator z nodejs.org ustawia wszystko za ciebie:
Node i npm w PATH,
gotowość do uruchamiania npm install i npm run dev.
W katalogu projektu:
npm install
npm run dev
odpalają developmentowy serwer Vite. Jeżeli php artisan serve działa równocześnie, dostajesz pełne środowisko z odświeżaniem frontendu. Na słabszych laptopach oba procesy potrafią „przyciąć” system – wtedy pomaga wyłączenie zbędnych programów w tle.
Typowe potknięcia przy natywnej instalacji
Przy pierwszym podejściu na Windowsie przewijają się kilka klasycznych problemów:
„php” nie jest rozpoznawane jako polecenie – brak ścieżki do PHP w PATH lub konieczność restartu terminala po zmianie zmiennych środowiskowych.
Composer korzysta z innego PHP niż terminal – instalator wskazał inny php.exe niż ten, który masz w PATH; pomaga sprawdzenie pełnych ścieżek poleceniami typu where php, where composer.
Błąd rozszerzeń PHP – brak włączonych rozszerzeń typu openssl czy pdo_mysql w php.ini.
Problemy z uprawnieniami katalogów – zdarzają się przy pracy w katalogach systemowych (np. C:Program Files); bezpieczniej trzymać projekty w prostszej lokalizacji, np. C:projekty.
Po dwóch–trzech takich przygodach człowiek przestaje się ich bać – po prostu wie, na co patrzeć najpierw, zamiast nerwowo instalować wszystko od nowa.
Źródło: Pexels | Autor: Markus Spiske
Wariant 2 – Laravel na Windowsie z WSL2: Linux bez zmiany systemu
Kiedy WSL2 robi największą różnicę
WSL2 zaczyna błyszczeć, gdy:
na produkcji aplikacje stoją na Linuksie i chcesz mieć bardzo podobne środowisko lokalnie,
myślisz o Dockerze, ale wolisz mieć możliwość uruchamiania Laravela również bez kontenerów,
potrzebujesz typowo linuxowych narzędzi: skryptów bashowych, cronów, różnych CLI.
Często wygląda to tak: na początku ktoś stawia wszystko natywnie, potem dołącza do projektu, gdzie „wszyscy jadą na WSL2 + Docker”, więc i tak musi się przełączyć. Lepiej przygotować sobie WSL2 spokojnie wcześniej niż robić awaryjną migrację w środku sprintu.
Instalacja i pierwsze odpalenie dystrybucji
Sam proces włączenia WSL2 to w większości kliknięcia w funkcje Windowsa i pobranie dystrybucji (np. Ubuntu) ze Sklepu Microsoft. Po pierwszym uruchomieniu:
tworzysz użytkownika i hasło linuxowe,
lądujesz w czystym terminalu z powłoką bash,
masz osobny system plików (zwykle pod wsl$ od strony Windowsa).
Na tym etapie dobrze jest zdecydować, gdzie będziesz trzymać kod. Najmniej problemów z wydajnością i uprawnieniami jest wtedy, gdy projekty leżą po stronie WSL, np. w /home/twoj_user/projekty, a VS Code łączy się z nimi przez rozszerzenie „Remote – WSL”.
Instalacja PHP, Composera i MySQL w WSL2
Od tego miejsca WSL2 zachowuje się jak normalny Linux. Dla Ubuntu ścieżka jest dobrze udokumentowana:
Instalacja Composera (np. według oficjalnej instrukcji z getcomposer.org).
Instalacja serwera baz danych:
sudo apt install mysql-server
Potem już znajome kroki: composer create-project, php artisan serve, konfiguracja bazy w .env. Różnica jest taka, że wszystkie komendy idą z terminala WSL, a nie z PowerShella.
Praca z kodem: Windows vs system plików WSL
Jedna z pułapek WSL2 to mieszanie lokalizacji kodu. Można co prawda:
trzymać kod na partycji Windows (np. /mnt/c/projekty) i pracować na nim z WSL,
albo trzymać kod wewnątrz WSL (np. /home/user/projekty) i otwierać go w VS Code przez „Remote – WSL”.
Pierwsze rozwiązanie bywa kuszące („bo widzę pliki od razu w Eksploratorze”), ale ma dwie wady: gorszą wydajność I/O przy większej liczbie plików i czasem problemy z uprawnieniami. Dla Laravela lepiej zadziała drugi wariant – kod w WSL, edycja przez zdalne rozszerzenie VS Code, a dostęp od strony Windowsa tylko w razie potrzeby (np. podgląd plików).
Laravel w WSL2 z serwerem developmentowym
Po utworzeniu projektu w katalogu wewnątrz WSL:
cd ~/projekty/blog
php artisan serve --host=0.0.0.0 --port=8000
uruchamia serwer nasłuchujący na wszystkich interfejsach. WSL2 automatycznie mostkuje sieć, więc zwykle możesz wejść w Windowsowej przeglądarce na adres http://localhost:8000. Jeśli port jest zajęty, zmieniasz go na inny; zasada ta sama jak przy natywnym PHP.
Na tym etapie różnica od natywnego podejścia jest niewielka w codziennej pracy, ale zyskujesz „pod spodem” linuxowe środowisko bliższe serwerowi produkcyjnemu.
Node, npm i Vite w WSL2
Front można oczywiście zostawić po stronie Windowsa, ale prościej jest mieć komplet również wewnątrz WSL:
instalujesz Node (np. przez nvm dla Linuksa),
w projekcie uruchamiasz npm install i npm run dev z poziomu terminala WSL,
przeglądarkę nadal odpalasz normalnie z Windowsa, łącząc się na localhost.
Dzięki temu nie musisz zastanawiać się, czy Node z Windowsa dogaduje się z plikami „leżącymi” wewnątrz WSL. Wszystko siedzi w jednym, spójnym środowisku linuxowym.
Typowe problemy w WSL2 przy Laravelu
Na starcie najczęściej pojawiają się:
pomieszane ścieżki – odpalanie Composera z PowerShella na projekcie trzymanym w WSL lub odwrotnie; pomaga jasny podział, skąd wydajesz komendy,
problemy z portami – kiedy jednocześnie działa natywny MySQL z Windowsa i MySQL z WSL, a oba próbują użyć tego samego portu; zwykle wystarczy zmiana portu jednego z nich lub zatrzymanie usługi, której nie używasz,
Łączenie świata Windows i WSL2 – baza w jednym, PHP w drugim
Czasem w projekcie baza danych jest już postawiona natywnie na Windowsie (np. XAMPP albo osobny MySQL), a ty chcesz rozwijać kod w WSL2. Nie trzeba od razu migrować wszystkiego – da się to spiąć.
Klucz to poprawne parametry połączenia. Jeśli:
Laravel działa w WSL2,
MySQL stoi na Windowsie i nasłuchuje na 127.0.0.1:3306,
to od strony WSL2 adres 127.0.0.1 będzie oznaczał Linuksa, a nie Windowsa. Potrzebny jest więc IP hosta Windows. W nowych wersjach WSL2 zwykle dostępna jest nazwa hosta:
Gdy ta nazwa nie działa, najprościej sprawdzić IP Windowsa w sieci wirtualnej WSL (czasem pokazywane przy starcie WSL albo przez konfigurację sieci). Potem to IP ląduje w DB_HOST. Sprawdzenie połączenia z poziomu WSL komendą:
mysql -h <IP_Windows> -u twoj_user -p
pozwala od razu stwierdzić, czy to jeszcze config, czy już Laravel.
Przyspieszanie pracy w WSL2 przy większych projektach
Przy małych aplikacjach różnicy prawie nie czuć. Gdy jednak projekt rośnie, a w nim tysiące plików, pojawia się kwestia wydajności. Kilka prostych trików robi wyraźną różnicę.
Trzymaj kod po stronie WSL – czyli np. /home/user/projekty, a nie /mnt/c. To już było wspomniane, ale przy dużych repozytoriach widać to boleśnie przy każdym composer install.
Ogranicz antywirusa – jeżeli Windowsowy antywirus wchodzi w katalogi WSL, każde zapisanie pliku może być „skanowane”. Można wykluczyć katalog wsl$ z pełnego skanowania (zgodnie z polityką bezpieczeństwa w firmie, jeśli pracujesz w zespole).
Nie mieszaj Node’a z dwóch światów – Vite z Windowsa na projekcie w WSL generuje masę dodatkowych opóźnień IO, więc lepiej mieć Node’a zainstalowanego w WSL.
Dobrym testem jest uruchomienie npm run dev oraz php artisan serve i obserwacja, jak szybko odświeżają się widoki i komponenty. Jeśli pojawia się kilkusekundowa zadyszka, któryś z elementów łańcucha (dysk, antywirus, lokalizacja plików) hamuje całość.
Wariant 3 – Laravel Sail i Docker na Windowsie krok po kroku
Dla kogo Docker i Sail mają największy sens
Sail to tak naprawdę zestaw gotowych kontenerów Dockera z prostym skryptem. Najbardziej docenią go osoby, które:
potrzebują powtarzalnego środowiska w zespole („u mnie działa” zamienia się w „u wszystkich działa tak samo”),
mają kilka projektów w różnych wersjach PHP, MySQL, Redis itp.,
nie chcą się bawić w ręczne instalowanie PHP, MySQL i Node na systemie.
Wyobraź sobie, że na jednym laptopie rozwijasz starą apkę na PHP 7.4 i nową na PHP 8.3. Natywnie zaczyna się walka z wersjami. W Sailu po prostu uruchamiasz inny zestaw kontenerów – każdy z własnym PHP.
Wymagania do Dockera na Windowsie
Zanim Laravel trafi do kontenerów, trzeba przygotować grunt. Docker Desktop potrzebuje:
włączonej wirtualizacji sprzętowej w BIOS/UEFI (Intel VT-x/AMD-V),
włączonego WSL2 w funkcjach systemu Windows,
zainstalowanej co najmniej jednej dystrybucji WSL (np. Ubuntu), bo Docker lubi ją wykorzystywać jako backend.
Po instalacji Docker Desktop przeprowadza krótki kreator i pyta, czy ma używać WSL2. W kontekście Laravela odpowiedź niemal zawsze brzmi: tak. Dzięki temu kontenery działają stabilniej i zużywają mniej zasobów niż przy klasycznej maszynie Hyper-V.
Instalacja i konfiguracja Docker Desktop
Samo ustawienie Dockera jest dość bezbolesne, ale kilka opcji ma wpływ na komfort:
Pobierz instalator ze strony docker.com i zainstaluj.
Po pierwszym starcie:
wejdź w ustawienia „Resources > WSL Integration” i zaznacz dystrybucję, z której korzystasz (np. Ubuntu),
upewnij się, że „Use the WSL 2 based engine” jest zaznaczone.
W terminalu WSL sprawdź, czy Docker widzi się od środka:
docker version
docker info
Jeżeli polecenia z WSL zwracają sensowne informacje, a nie komunikat „Cannot connect to the Docker daemon”, integracja jest poprawna. W przeciwnym razie trzeba wrócić do ustawień Dockera i sprawdzić sekcję WSL.
Tworzenie nowego projektu Laravel z Sail
Najprostsza ścieżka do nowego projektu w Sail wygląda tak:
W terminalu WSL (np. Ubuntu) przejdź do katalogu roboczego:
cd ~/projekty
Utwórz nowy projekt Laravela z flagą Sail:
curl -s "https://laravel.build/blog" | bash
Nazwa po build/ to nazwa folderu – możesz podać np. crm, api itp.
Po zakończeniu skryptu przejdź do katalogu:
cd blog
Uruchom kontenery:
./vendor/bin/sail up
Pierwsze odpalenie trwa wyraźnie dłużej – Docker ściąga obrazy PHP, MySQL, Node i innych usług. Kolejne starty są już sporo szybsze, bo wszystko jest w cache.
Konfiguracja kontenerów w pliku docker-compose
Po utworzeniu projektu z Sail w katalogu pojawia się docker-compose.yml. To serce konfiguracji środowiska. W środku znajdziesz m.in. sekcje:
laravel.test – kontener z PHP, serwerem HTTP (np. nginx) i kodem aplikacji,
mysql lub mariadb – baza danych,
redis – cache / kolejki, jeśli zostały włączone,
czasem meilisearch, mailhog i inne – w zależności od wybranych opcji.
Domyślnie Sail wykorzystuje port 80 na hoście i mapuje go na laravel.test. To oznacza, że:
http://localhost
powinno wyświetlać stronę startową Laravela po starcie sail up. Jeśli port 80 jest zajęty (np. przez IIS albo inny serwer), w pliku docker-compose.yml można zmienić mapowanie portu w sekcji serwisu laravel.test, np.:
ports:
- '8080:80'
i wtedy aplikacja będzie dostępna pod http://localhost:8080.
Podstawowe komendy Sail w codziennej pracy
Zamiast pamiętać długie komendy Dockera, Sail opakowuje je prostym skryptem. Kilka przydatnych przykładów:
Nie trzeba tu wpisywać localhost, bo połączenie idzie między kontenerami po nazwach usług. Laravel siedzi w kontenerze laravel.test, a MySQL w mysql, więc w DB_HOST zostaje po prostu mysql.
Jeśli chcesz podłączyć się do tej bazy z narzędzia na Windowsie (np. TablePlus, DBeaver, HeidiSQL), korzystasz już z adresu hosta – zazwyczaj:
Host: 127.0.0.1
Port: 3306 (lub inny, jeśli zmieniony w docker-compose)
User: sail
Password: password
Database: laravel
Tu znów działa mapowanie portów – to, co Laravel widzi jako mysql:3306, ty z zewnątrz widzisz jako localhost:3306.
Praca z logami i debugowaniem w Sail
W kontenerach logi nie są już „gdzieś w systemie Windows”, tylko włączone w obsługę Dockera. Dobrze mieć kilka prostych komend pod ręką:
logi aplikacji (kontener laravel.test):
docker logs <nazwa_kontenera_laravel.test>
albo prościej:
./vendor/bin/sail logs laravel.test
logi bazy:
./vendor/bin/sail logs mysql
Jeśli trzeba „wejść do środka” kontenera i coś sprawdzić ręcznie (np. listę procesów, zawartość katalogu), przydaje się:
./vendor/bin/sail shell
Polecenie otwiera powłokę w środku kontenera laravel.test. Dalej działa już znajome środowisko linuksowe: ls, php -v, artisan itd.
Najczęstsze problemy z Dockerem i Sail na Windowsie
Przy pierwszym kontakcie z Dockerem na Windowsie przewijają się podobne zgrzyty:
Docker Desktop się nie uruchamia – często chodzi o wyłączoną wirtualizację w BIOS/UEFI lub konflikt z innym oprogramowaniem wirtualizującym.
Brak połączenia z daemonem z WSL – terminal w WSL zwraca błąd typu „Cannot connect to the Docker daemon”; zwykle pomaga włączenie integracji danej dystrybucji w ustawieniach Docker Desktop i restart zarówno Dockera, jak i WSL.
Porty zajęte – np. laravel.test chce używać portu 80, ale ten jest już zajęty przez inny serwer (IIS, XAMPP). Rozwiązanie: zmienić port w docker-compose.yml albo wyłączyć konkurencyjną usługę.
Wolne działanie na katalogach Windows – projekty trzymane w /mnt/c w połączeniu z Dockerem potrafią mocno zwolnić przy dużej liczbie plików; lepsza lokalizacja to ~/projekty wewnątrz WSL.
Po kilku takich sytuacjach zaczyna to być przewidywalne: gdy coś nie działa, pierwsze spojrzenie idzie w stronę Dockera (czy działa), integracji WSL (czy włączona) i portów (czy są wolne).
Przenoszenie istniejącego projektu do Sail
Często jest tak, że projekt już istnieje, działał do tej pory na natywnym PHP albo samym WSL, a ktoś w zespole proponuje „przenieśmy się na Sail”. Proces jest do zrobienia bez większego bólu:
W istniejącym projekcie doinstaluj Sail:
composer require laravel/sail --dev
Wygeneruj pliki Dockera:
php artisan sail:install
W tym momencie można wybrać usługi (MySQL, Redis, Meilisearch itd.).
Uruchom kontenery:
./vendor/bin/sail up
Dostosuj .env do konfiguracji bazy i innych usług Sail (szczególnie DB_HOST, DB_USERNAME, DB_PASSWORD).
Jeśli baza istniała wcześniej na Windowsie, można:
Najczęściej zadawane pytania (FAQ)
Jak najlepiej zainstalować Laravel na Windowsie: natywnie, przez WSL2 czy Docker/Sail?
Jeśli dopiero zaczynasz i chcesz po prostu „zobaczyć Laravel w akcji”, najprostsza będzie natywna instalacja: PHP, Composer i baza danych zainstalowane bezpośrednio w Windowsie (np. przez XAMPP, WampServer lub ręczną instalację). To dobre rozwiązanie na małe projekty i naukę, ale z czasem bywa trudniejsze w utrzymaniu.
Przy dłuższej pracy wygodniejsze są WSL2 albo Docker + Laravel Sail. WSL2 daje Ci „prawdziwego Linuksa” w środku Windowsa, bardzo zbliżonego do serwera produkcyjnego. Docker/Sail idzie krok dalej – zamyka PHP, bazę, Redis i resztę w kontenerach, dzięki czemu zespół może mieć identyczne środowisko jednym plikiem docker-compose. Jeśli myślisz o pracy w zespole, prędzej czy później skończysz właśnie na jednym z tych dwóch rozwiązań.
Co zrobić, gdy Windows pokazuje błąd „php is not recognized as an internal or external command”?
Ten komunikat oznacza, że system nie wie, gdzie leży plik php.exe – czyli ścieżka do PHP nie jest dopisana do zmiennej PATH, albo masz kilka instalacji PHP i Windows „gubi się”, której użyć. Typowy scenariusz: PHP od XAMPP-a jest w jednym katalogu, inne PHP w drugim i żadnego nie ma w PATH.
Najprościej: znajdź folder, w którym jest php.exe (np. C:xamppphp), dodaj go ręcznie do zmiennej PATH w ustawieniach systemu i zrestartuj terminal. Jeśli korzystasz z WSL2 lub Dockera, komendę php wywołuj wewnątrz Linuksa lub kontenera – tam PHP jest zwykle poprawnie skonfigurowane i nie miesza się z wersją z Windowsa.
Dlaczego mam tyle „magicznych błędów” w Laravelu na Windowsie, a na Linuksie działa od strzału?
Laravel sam w sobie jest dość przewidywalny. Problemy na Windowsie biorą się zwykle z otoczenia: kilku wersji PHP zainstalowanych równolegle, różnych kopii Composera, brakujących rozszerzeń (ext-xyz), wolnych katalogów synchronizowanych przez OneDrive czy skanowanych agresywnie przez antywirusa.
Na typowym Linuksie środowisko jest prostsze i lepiej opisane w dokumentacji, więc te „zaczarowane” błędy się nie pojawiają. Na Windowsie pomaga jedno – ustalony schemat: jedna świadomie wybrana wersja PHP, jeden Composer, projekty trzymane w normalnym katalogu (np. C:projekty, nie na pulpicie w OneDrive) i jasno opisany sposób uruchamiania (natywnie, w WSL2 lub przez Docker/Sail).
Czym różni się „jakoś działa” od stabilnego środowiska Laravela na Windowsie?
„Jakoś działa” to sytuacja, w której projekt się uruchamia, ale każda aktualizacja PHP, Composera albo paczki npm potrafi wywrócić cały dzień pracy. Na jednym komputerze w zespole działa, na drugim sypie błędami. Nikt do końca nie wie, jaką wersję PHP ma projekt i co dokładnie biega w tle.
Stabilne środowisko to przeciwieństwo loterii. Wiesz:
jaką wersję PHP i MySQL/MariaDB używa projekt,
który Composer jest używany (i gdzie leży),
jak wygląda podstawowy „zestaw startowy” – np. WSL2 + PHP + MySQL + Node albo Docker + Sail,
jak powtórzyć ten sam setup na drugim komputerze kilkoma komendami.
W praktyce przestajesz walczyć ze sprzętem, a zaczynasz spokojnie pracować nad kodem.
Czy do pracy z Laravelem na Windowsie muszę znać PowerShell i terminal?
Nie musisz być guru PowerShella, ale bez podstaw pracy w terminalu z Laravelem jest jak bez kierownicy w aucie. Framework opiera się na komendach: composer create-project, php artisan migrate, npm run dev, ./vendor/bin/sail up i wielu innych.
Przydaje się umieć:
przechodzić między folderami (cd, ls lub dir),
odpalać programy z terminala (php -v, composer -V),
podejrzeć pliki konfiguracyjne (type w PowerShell, cat w WSL).
Dobrym nawykiem jest używanie Windows Terminal z kilkoma kartami (PowerShell, WSL) i otwieranie go bezpośrednio w folderze projektu – znacznie ułatwia to codzienną pracę.
Jakie są minimalne wymagania systemowe, żeby wygodnie pracować z Laravelem na Windowsie?
Na sam start wystarczy współczesny Windows 10 lub 11, ale dla WSL2 i Dockera kluczowa jest konkretna wersja. Wygodnie pracuje się na:
Windows 10 w wersji co najmniej 2004 (build 19041) lub nowszej,
Windows 11 – WSL2 działa tu bardzo dobrze „z pudełka”,
edycji Home lub Pro – do WSL2 i nowszego Dockera nie ma dużej różnicy.
Do tego dorzuć minimum 8 GB RAM (12–16 GB, jeśli chcesz używać Dockera i kilku usług naraz) i trochę wolnego miejsca na dysku pod projekty, bazy danych i kontenery.
Jak uniknąć konfliktów między różnymi wersjami PHP, Composera i Node.js na Windowsie?
Najpewniejsza droga to izolacja środowiska. Zamiast instalować „PHP dla wszystkiego” w całym systemie, lepiej zamknąć projekt w jednym, spójnym stosie: WSL2 (gdzie PHP, Composer i Node są zainstalowane tylko w tej dystrybucji Linuksa) albo Docker/Sail (gdzie wersje narzędzi są zdefiniowane w plikach konfiguracyjnych kontenerów).
Jeżeli pracujesz natywnie w Windowsie, trzymaj się kilku prostych zasad:
jedna główna instalacja PHP,
Composer wskazujący właśnie na tę wersję PHP,
Node.js z oficjalnego instalatora lub nvm-windows, ale bez pięciu różnych wersji naraz,
czytelny katalog na projekty (np. C:dev) i unikanie folderów synchronizowanych w chmurze.
Wtedy zamiast „magii” zostaje przewidywalne, powtarzalne środowisko, które łatwo przenieść na drugi komputer.
