Vanaf Laravel 8 kun je gebruik maken van Sail, een ingebouwde oplossing voor het hosten van je Laravel project met gebruik van Docker. Dat is erg handig want je hebt dan een compleet schaalbare lokale server omgeving die bovendien voor alle developers, die meewerken aan het project, gelijk is. Met schaalbaar bedoel ik dat je eenvoudig extra containers kunt toevoegen waarmee je extra functionaliteit binnen je serveromgeving brengt. De standaard installatie is een omgeving met alles wat nodig is om een Laravel project te developen, maar er is één ding dat ik direct miste… Xdebug!

Ik ben persoonlijk zeer gehecht aan Xdebug als step-by-step debugger in mijn PHP ontwikkel tactiek. Het is voor mij onmisbaar om op die manier heel snel code van derden te ontrafelen en ook bij het ontwikkelen van nieuwe functies is het super handig om de code stap voor stap te kunnen doorlopen om te controleren of alles wat je hebt bedacht ook precies zo werkt als je wil. Je kunt eenvoudig controleren of collecties netjes tot stand komen, variabelen op de juiste wijze gevuld worden, queries goed gebouwd worden, etc..

Toen ik laatst voor het eerst met Laravel Sail aan de gang ging kwam ik al direct tot de conclusie dat Xdebug geen deel uitmaakt van de standaard installatie. Na behoorlijk rondstruinen op het web kwam ik tot de conclusie dat het lastig is om een lekkere “step-by-step” uitleg te vinden om Xdebug aan de praat te krijgen binnen Laravel Sail. Zelf werk ik met PhpStorm op een Mac dus ik beperk deze uitleg tot mijn eigen setup. Voor VS Code en Windows zal het echter niet heel veel verschillen, zeker de setup van Sail niet.

Om te beginnen heb je uiteraard Docker desktop nodig dus die moet je wel eerst even installeren: 

https://www.docker.com/products/docker-desktop

Zodra je Docker hebt geïnstalleerd kunnen we met een nieuw Laravel project beginnen. In deze uitleg noemen we onze app “eenvoud-app”, niet alleen omdat Eenvoud slaat op de eenvoudige installatie van Laravel en Sail maar ook omdat Eenvoud gewoon een heel leuk bureau is om te werken. Uiteraard starten we het nieuwe project vanuit de terminal.

curl -s "https://laravel.build/eenvoud-app" | bash

Nu is je project geïnstalleerd en in de root zie je het docker-compose.yml file staan. Aangezien ze bij Laravel bedacht hebben om Sail als een soort schil om Docker te bouwen vind je het bijbehorende Dockerfile in de vendor folder. In een vendor folder wil je natuurlijk geen aanpassingen doen dus om XDebug toe te voegen aan het Dockerfile heb ik liever dat deze terug te vinden is in bijvoorbeeld de “resources” folder.  Het Dockerfile kan dan ook gewoon in je version control wordt meegenomen zodat de andere developers die aan het project werken in exact dezelfde omgeving gaan werken. Ik heb daarom besloten de files uit de vendor folder te kopiëren naar de resource folder, maar de locatie maakt verder niet zoveel uit natuurlijk.

cp -r vendor/laravel/sail/runtimes/8.0 ./resources/docker/

Nu heb je de benodigde files binnen handbereik en kun je eenvoudig de wijziging maken en bijhouden in GIT.

Om er nu voor te zorgen dat Laravel Sail gebruik gaat maken van het gedupliceerde Dockerfile in de resources folder in plaats van de standaard vendor folder moet je een aanpassing in je docker-compose.yml file maken. 

Op regel 6 vind je de “context”. Daar vind je ook het pad naar je Dockerfile en deze moet je dus veranderen naar het nieuwe Dockerfile. In mijn geval is dat dan dus: ./resources/docker. Ook heb ik hier een variabele toegevoegd waarmee ik in het nieuwe Dockerfile kan bepalen of Xdebug geïnstalleerd dient te worden. In mijn setup gebeurt dit alleen als je in je .env file de variabel APP_DEBUG op true hebt staan.

# For more information: https://laravel.com/docs/sail
version: '3'
services:
laravel.test:
build:
context: ./resources/docker
dockerfile: Dockerfile
args:
WWWGROUP: '${WWWGROUP}'
XDEBUG: ${APP_DEBUG}

Vervolgens gaan we het nieuwe Dockerfile aanpassen. Het Dockerfile is feitelijk een configuratiebestand waarmee je de serveromgeving mee samenstelt en aangezien XDebug niet standaard geïnstalleerd staat gaan we in het Dockerfile aangeven dat als APP_DEBUG in het .env file op true staat, XDebug ook geïnstalleerd moet worden. Ik heb deze code op regel 44 ingevoerd, dus direct na het RUN apt-get update \ script

RUN if [ ${XDEBUG} ] ; then \
apt-get install -y php-xdebug \
&& echo "[XDebug]" > /etc/php/8.0/cli/php.ini \
&& echo "zend_extension="$(find /usr/lib/php/20200930/ -name xdebug.so)" > /etc/php/8.0/cli/php.ini" \
&& echo "xdebug.mode = debug" >> /etc/php/8.0/cli/php.ini \
&& echo "xdebug.start_with_request = yes" >> /etc/php/8.0/cli/php.ini \
&& echo "xdebug.discover_client_host = true" >> /etc/php/8.0/cli/php.ini \
&& echo "xdebug.client_host = host.docker.internal" >> /etc/php/8.0/cli/php.ini \
fi;

Hiermee heb je feitelijk alles geregeld en is je serveromgeving voorzien van XDebug. Wanneer je Laravel Sail nu voor de eerste keer start wordt je image gebouwd. Mocht je nu al eerder een keer het image gebouwd hebben dan moet je die eerst even weggooien, dat kan eenvoudig in Docker desktop. Je start Laravel Sail met het volgende commando vanuit je project:

./vendor/bin/sail up

Als je zeker wilt weten dat de image opnieuw gebouwd wordt kun je ook het volgende commando gebruiken:

./vendor/bin/sail up --build -d

Wanneer je nu in je browser de url ‘http://localhost/‘ opent dan zie je de startpagina van je nieuwe project. En nu kan de Magic beginnen. Zoals gezegd werk ik met PhpStorm en die IDE is helemaal voorbereid op het step-by-step debuggen met XDebug. Er is dus geen extra installatie nodig om het werkend te krijgen, alleen wat configuratie. Voor VS Code heb je wel een extensie nodig, de PHP Debug extension van Felix Becker.

Wanneer ik naar PhpStorm ga en ik klik op “luisteren naar Xdebug” dan gaat Xdebug luisteren naar inkomende debug connectie. Als het icoon groen is dan luistert PhpStorm naar je inkomende debug connectie en kun je vervolgens breekpunten plaatsen in de code (van die rode punten in de kantlijn).

Wanneer je dan de webpagina in je browser herlaad zal PhpStorm eerst vragen of je de inkomende debug connectie wilt accepteren. Dat hoeft alleen de eerste keer, de server settings worden dan automatisch voor je bewaard.

Uiteraard wil je niet altijd debuggen maar door het luisteren weer uit te schakelen stop je met debuggen en wanneer je een probleem op te lossen hebt zet je het gewoon even aan. Het aan en uit schakelen doe je in PhpStorm door op het uitluister icoon te klikken, handiger kan niet!

Happy Debugging!

Niels Meijer

Eenvoud Amsterdam