Laravel Sail

Què és Laravel Sail?#

Configurar un entorn de desenvolupament PHP ha sigut tradicionalment un dels punts de fricció més grans per als desenvolupadors que comencen amb Laravel. Necessites instal·lar PHP amb les extensions adequades, un servidor web (Nginx o Apache), una base de dades (MySQL, PostgreSQL), potser Redis per a la cache, i assegurar-te que totes les versions són compatibles entre elles i amb el projecte. Si treballes en múltiples projectes, cada un pot requerir versions diferents de PHP o de la base de dades, cosa que complica encara més la situació. I si un nou desenvolupador s'incorpora a l'equip, ha de repetir tot el procés des de zero.

Laravel Sail resol aquest problema proporcionant un entorn de desenvolupament Docker lleuger i preconfigurar per a Laravel. Amb Sail, no cal instal·lar PHP, MySQL, Redis ni cap altra dependència al teu ordinador. Tot s'executa dins de contenidors Docker que es configuren automàticament. L'únic requisit és tenir Docker instal·lat.

Sail és una interfície de línia de comandes que simplifica la interacció amb Docker Compose. En lloc d'escriure comandes Docker llargues i complexes, fas servir comandes curtes i intuïtives. sail up en lloc de docker compose up. sail artisan migrate en lloc de docker compose exec laravel.test php artisan migrate. La simplicitat és el principi fonamental de Sail.

Per què Docker per a desenvolupament Laravel?#

Docker aïlla completament l'entorn de l'aplicació del sistema operatiu de la teva màquina. Això significa que tots els membres de l'equip treballen amb exactament el mateix entorn, independentment de si fan servir macOS, Windows o Linux. Els problemes de "a la meva màquina funciona" desapareixen perquè tothom té el mateix PHP, la mateixa base de dades i les mateixes extensions.

A més, Docker permet treballar en múltiples projectes amb requisits diferents simultàniament. Un projecte pot necessitar PHP 8.2 amb MySQL 5.7, mentre que un altre necessita PHP 8.3 amb PostgreSQL 16. Amb Docker, cada projecte té el seu propi entorn aïllat sense conflictes.

Instal·lació#

En un projecte nou#

La manera més ràpida de crear un projecte Laravel amb Sail és utilitzar l'instal·lador oficial. Amb una sola comanda, es crea el projecte, s'instal·len les dependències i es configuren els contenidors Docker:

curl -s "https://laravel.build/el-meu-projecte" | bash

Aquesta comanda crea un directori el-meu-projecte amb una instal·lació fresca de Laravel i un fitxer docker-compose.yml preconfigurar amb MySQL, Redis, Meilisearch, Mailpit i Selenium. Un cop acabada la instal·lació, pots iniciar l'entorn:

cd el-meu-projecte
./vendor/bin/sail up

Si vols triar quins serveis incloure durant la instal·lació, afegeix el paràmetre with a la URL:

# Només MySQL i Redis
curl -s "https://laravel.build/el-meu-projecte?with=mysql,redis" | bash
 
# PostgreSQL, Redis i Mailpit
curl -s "https://laravel.build/el-meu-projecte?with=pgsql,redis,mailpit" | bash
 
# Tots els serveis disponibles
curl -s "https://laravel.build/el-meu-projecte?with=mysql,pgsql,mariadb,redis,memcached,meilisearch,typesense,minio,mailpit,selenium,soketi" | bash

En un projecte existent#

Si ja tens un projecte Laravel i vols afegir Sail, instal·la'l com a dependència de desenvolupament:

composer require laravel/sail --dev

Després, executa la comanda interactiva d'instal·lació que et permet seleccionar quins serveis vols:

php artisan sail:install

Aquesta comanda et mostrarà una llista dels serveis disponibles i et permetrà seleccionar els que necessites. Generarà un fitxer docker-compose.yml a l'arrel del projecte i actualitzarà el fitxer .env amb les variables de connexió adequades.

Un cop instal·lat, inicia l'entorn:

./vendor/bin/sail up -d

Serveis disponibles#

Sail ofereix una àmplia selecció de serveis preconfigurats que cobreixen les necessitats més comunes de les aplicacions Laravel. Cada servei és un contenidor Docker independent que es comunica amb els altres a través d'una xarxa interna.

Bases de dades#

• MySQL: La base de dades relacional més popular per a Laravel. Accessible al port 3306 des del contenidor i al port configurat per FORWARD_DB_PORT des de la teva màquina.
• PostgreSQL: Una alternativa a MySQL amb funcionalitats avançades com JSONB, arrays i tipus personalitzats. Ideal per a aplicacions que necessiten consultes complexes o tipus de dades avançats.
• MariaDB: Un fork de MySQL compatible que alguns equips prefereixen per la seva llicència i rendiment.

Cache i cues#

• Redis: Emmagatzematge clau-valor en memòria. S'utilitza habitualment per a cache, sessions, cues i broadcasting. La majoria de projectes Laravel en producció fan servir Redis per almenys una d'aquestes funcions.
• Memcached: Una alternativa a Redis per a cache. Més senzill que Redis però amb menys funcionalitats.

Cerca#

• Meilisearch: Motor de cerca ràpid i fàcil de configurar. S'integra amb Laravel Scout per proporcionar cerca de text complet als teus models Eloquent.
• Typesense: Una alternativa a Meilisearch amb característiques similars. Alguns equips el prefereixen pel seu rendiment en cerques amb molts registres.

Emmagatzematge#

• MinIO: Servei compatible amb l'API d'Amazon S3. Permet desenvolupar i provar codi que utilitza el disc s3 de Laravel sense necessitat d'un compte AWS real. Les pujades de fitxers es guarden localment dins del contenidor MinIO.

Correu#

• Mailpit: Captura tots els correus sortints de l'aplicació i proporciona una interfície web per visualitzar-los. Mai envia correus reals, cosa que evita accidents durant el desenvolupament. Accessible a http://localhost:8025.

Testing#

• Selenium: Servidor per a tests de navegador (browser tests). Permet executar tests amb Laravel Dusk que interactuen amb un navegador real.

Websockets#

• Soketi: Servidor de WebSockets compatible amb Pusher. Permet desenvolupar i provar funcionalitats en temps real (broadcasting) sense necessitat d'un servei extern com Pusher o Ably.

Comandes bàsiques#

Totes les comandes de Sail s'executen des del directori arrel del projecte. La manera completa és ./vendor/bin/sail, però és recomanable configurar un alias (com veurem més endavant) per simplificar-ho.

Gestió de contenidors#

# Iniciar tots els contenidors en segon pla
./vendor/bin/sail up -d
 
# Iniciar en primer pla (veure els logs en temps real)
./vendor/bin/sail up
 
# Aturar tots els contenidors
./vendor/bin/sail down
 
# Reiniciar tots els contenidors
./vendor/bin/sail restart
 
# Veure l'estat dels contenidors
./vendor/bin/sail ps

El flag -d (detached) és important: sense ell, els logs de tots els contenidors es mostren a la terminal i el procés es bloqueja. Amb -d, els contenidors s'executen en segon pla i la terminal queda lliure.

Comandes Laravel#

Sail proporciona wrappers per a totes les comandes habituals de Laravel. Aquests wrappers executen la comanda dins del contenidor principal, on PHP i totes les extensions estan instal·lades:

# Artisan
./vendor/bin/sail artisan migrate
./vendor/bin/sail artisan make:model Product -mfc
./vendor/bin/sail artisan db:seed
./vendor/bin/sail artisan tinker
./vendor/bin/sail artisan queue:work
 
# Composer
./vendor/bin/sail composer require spatie/laravel-permission
./vendor/bin/sail composer update
./vendor/bin/sail composer dump-autoload
 
# npm / Node
./vendor/bin/sail npm install
./vendor/bin/sail npm run dev
./vendor/bin/sail npm run build
./vendor/bin/sail node --version
 
# Tests
./vendor/bin/sail test
./vendor/bin/sail pest
./vendor/bin/sail test --filter=UserTest

Accés a serveis#

Sail també proporciona accés directe als serveis instal·lats:

# Obrir la consola de MySQL
./vendor/bin/sail mysql
 
# Obrir la consola de Redis
./vendor/bin/sail redis
 
# Obrir la consola de PostgreSQL (si tens PostgreSQL instal·lat)
./vendor/bin/sail psql

Accés al contenidor#

De vegades necessites accedir directament al contenidor per executar comandes que no tenen un wrapper de Sail, inspeccionar fitxers o depurar problemes:

# Entrar al contenidor com a usuari normal (sail)
./vendor/bin/sail shell
 
# Entrar al contenidor com a root
./vendor/bin/sail root-shell

Un cop dins del contenidor, pots executar qualsevol comanda com si estiguessis en un servidor Linux. Això és útil per inspeccionar la configuració de PHP (php -i), comprovar extensions instal·lades (php -m) o executar scripts personalitzats.

L'alias de Sail#

Escriure ./vendor/bin/sail cada vegada és tediós. La solució és crear un alias al teu fitxer de configuració del shell:

# Afegeix al teu ~/.bashrc, ~/.zshrc o ~/.config/fish/config.fish
alias sail='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)'

Després de recarregar el shell (source ~/.bashrc o source ~/.zshrc), pots fer servir sail directament:

# Ara en lloc de ./vendor/bin/sail, simplement:
sail up -d
sail artisan migrate
sail composer require package/name
sail npm run dev
sail test
sail down

L'alias comprova si existeix un fitxer sail al directori actual (per a projectes que el publiquen) i, si no, fa servir vendor/bin/sail. Aquesta flexibilitat fa que funcioni en qualsevol projecte Sail.

Variables d'entorn#

Sail utilitza variables d'entorn per controlar el comportament dels contenidors. Aquestes variables es defineixen al fitxer .env del projecte.

Ports#

Per defecte, Sail exposa els serveis a ports estàndard. Si tens conflictes amb altres serveis del teu sistema (o amb altres projectes Sail), pots canviar els ports:

# Port de l'aplicació (per defecte 80)
APP_PORT=8080
 
# Port de MySQL (per defecte 3306)
FORWARD_DB_PORT=3307
 
# Port de Redis (per defecte 6379)
FORWARD_REDIS_PORT=6380
 
# Port de Mailpit (per defecte 1025 per SMTP, 8025 per web)
FORWARD_MAILPIT_PORT=1026
FORWARD_MAILPIT_DASHBOARD_PORT=8026
 
# Port de Meilisearch (per defecte 7700)
FORWARD_MEILISEARCH_PORT=7701

Variables de Sail#

Sail també té les seves pròpies variables de configuració:

# La versió de PHP a utilitzar (8.0, 8.1, 8.2, 8.3)
SAIL_PHP_VERSION=8.3
 
# La imatge del contenidor principal
SAIL_PHP_IMAGE=sail-8.3/app
 
# Obrir el navegador automàticament al fer sail up
SAIL_OPEN_BROWSER=true

Canviar la versió de PHP és tan senzill com modificar SAIL_PHP_VERSION i reconstruir els contenidors:

sail build --no-cache
sail up -d

Personalització de Docker#

Sail utilitza Docker Compose per definir i gestionar els contenidors. El fitxer docker-compose.yml a l'arrel del projecte descriu tots els serveis. Pots modificar aquest fitxer directament per afegir serveis, canviar configuracions o ajustar recursos.

Publicar els Dockerfiles#

Si necessites personalitzar les imatges Docker (per exemple, per instal·lar extensions PHP addicionals o paquets del sistema), pots publicar els Dockerfiles:

sail artisan sail:publish

Això crea un directori docker/ a l'arrel del projecte amb els Dockerfiles de tots els serveis. Ara pots modificar-los segons les teves necessitats:

# docker/8.3/Dockerfile
 
# Exemple: instal·lar l'extensió PHP GD amb suport WebP
RUN apt-get update && apt-get install -y \
    libwebp-dev \
    libjpeg-dev \
    libpng-dev \
    && docker-php-ext-configure gd --with-jpeg --with-webp \
    && docker-php-ext-install gd
 
# Exemple: instal·lar l'extensió PHP intl
RUN apt-get update && apt-get install -y \
    libicu-dev \
    && docker-php-ext-install intl
 
# Exemple: instal·lar ffmpeg per a processament de vídeo
RUN apt-get update && apt-get install -y ffmpeg

Després de modificar el Dockerfile, reconstrueix la imatge:

sail build --no-cache
sail up -d

Afegir serveis personalitzats#

Pots afegir qualsevol servei Docker al fitxer docker-compose.yml. Per exemple, si necessites Elasticsearch per a cerques avançades:

# docker-compose.yml
services:
    # ... serveis existents de Sail
 
    elasticsearch:
        image: elasticsearch:8.12.0
        environment:
            - discovery.type=single-node
            - xpack.security.enabled=false
            - "ES_JAVA_OPTS=-Xms512m -Xmx512m"
        ports:
            - "${FORWARD_ELASTICSEARCH_PORT:-9200}:9200"
        volumes:
            - sail-elasticsearch:/usr/share/elasticsearch/data
        networks:
            - sail
 
    kibana:
        image: kibana:8.12.0
        environment:
            - ELASTICSEARCH_HOSTS=http://elasticsearch:9200
        ports:
            - "${FORWARD_KIBANA_PORT:-5601}:5601"
        depends_on:
            - elasticsearch
        networks:
            - sail
 
volumes:
    # ... volums existents
    sail-elasticsearch:
        driver: local

Un cop afegit el servei, actualitza el fitxer .env amb les variables de connexió adequades i reinicia els contenidors:

sail up -d

Compartir el teu lloc#

De vegades necessites compartir el teu entorn de desenvolupament local amb algú de fora: un client que vol veure el progrés, un col·lega que treballa en un altre lloc o un servei extern que necessita fer callbacks (com webhooks de Stripe). Sail facilita això amb la comanda share:

sail share

Aquesta comanda utilitza Expose (un servei de túnels HTTP similar a ngrok) per crear una URL pública temporal que redirigeix al teu entorn local. Qualsevol persona amb la URL pot accedir a la teva aplicació.

Quan executis sail share, es mostrarà la URL pública a la terminal. Aquesta URL és temporal i desapareix quan atures la comanda.

Per configurar el domini correctament, afegeix la variable SAIL_SHARE_DOMAIN si fas servir un domini personalitzat d'Expose, i assegura't que APP_URL a .env apunta a la URL correcta perquè els enllaços generats per l'aplicació siguin vàlids:

sail share --subdomain=el-meu-projecte

Si prefereixes ngrok, pots instal·lar-lo directament dins del contenidor o fer servir-lo des de la teva màquina local apuntant al port de l'aplicació:

ngrok http 80

Executar tests#

Sail facilita l'execució de tests proporcionant wrappers per a PHPUnit i Pest. Com que els tests s'executen dins del contenidor Docker, tenen accés a la base de dades, Redis i tots els altres serveis sense cap configuració addicional:

# Executar tots els tests amb PHPUnit
sail test
 
# Executar tots els tests amb Pest
sail pest
 
# Executar tests d'un fitxer específic
sail test --filter=UserTest
 
# Executar tests amb cobertura de codi
sail test --coverage
 
# Executar tests en paral·lel
sail test --parallel
 
# Passar arguments addicionals a PHPUnit
sail test -- --stop-on-failure --verbose

Per a tests amb navegador (Laravel Dusk), necessites tenir el servei Selenium instal·lat. Si l'has seleccionat durant la instal·lació de Sail, pots executar els tests Dusk directament:

sail dusk
sail dusk --filter=LoginTest

Base de dades de testing#

Per defecte, Sail configura una base de dades de testing separada (accessible com a testing dins del docker-compose.yml). Això permet executar tests sense afectar les dades de desenvolupament. Pots configurar la base de dades de testing al fitxer phpunit.xml:

<!-- phpunit.xml -->
<env name="DB_DATABASE" value="testing"/>

Depuració amb Xdebug#

Xdebug és l'eina de depuració per excel·lència en PHP. Permet posar punts d'interrupció (breakpoints) al codi, inspeccionar variables, seguir l'execució pas a pas i analitzar el rendiment. Sail inclou Xdebug preinstal·lat, però desactivat per defecte perquè afecta el rendiment.

Activar Xdebug#

Per activar Xdebug, afegeix la variable SAIL_XDEBUG_MODE al fitxer .env:

# Modes disponibles: off, develop, coverage, debug, gcstats, profile, trace
SAIL_XDEBUG_MODE=debug
 
# Per a múltiples modes:
SAIL_XDEBUG_MODE=debug,coverage

Cada mode té una funció diferent:

• off: Xdebug desactivat (per defecte)
• debug: Depuració pas a pas amb breakpoints
• coverage: Cobertura de codi (necessari per a --coverage als tests)
• develop: Millores en els missatges d'error de PHP
• profile: Anàlisi de rendiment (genera fitxers de profiling)
• trace: Traça d'execució (registra cada crida a funció)

Després de canviar el mode, reinicia els contenidors:

sail down && sail up -d

Configurar l'editor#

Un cop Xdebug està actiu, necessites configurar l'editor per escoltar les connexions de depuració.

VS Code:

Instal·la l'extensió "PHP Debug" i crea un fitxer .vscode/launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Sail Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/var/www/html": "${workspaceFolder}"
            },
            "hostname": "0.0.0.0"
        }
    ]
}

PHPStorm:

1. Ves a Settings > PHP > Debug i verifica que el port d'Xdebug sigui 9003
2. Ves a Settings > PHP > Servers i crea un servidor:
   • Host: localhost, Port: 80
   • Activa "Use path mappings"
   • Mapeja l'arrel del projecte a /var/www/html
3. Clica "Start Listening for PHP Debug Connections" a la barra d'eines

Ara pots posar breakpoints al codi i quan facis una petició a l'aplicació, l'execució es pausarà al breakpoint i podràs inspeccionar les variables, la pila de crides i avançar pas a pas.

Múltiples projectes#

Si treballes en múltiples projectes Laravel simultàniament, cadascun amb el seu propi Sail, pots tenir conflictes de ports. Per defecte, tots els projectes intenten utilitzar els mateixos ports (80 per a l'aplicació, 3306 per a MySQL, 6379 per a Redis, etc.).

La solució és assignar ports diferents a cada projecte mitjançant les variables d'entorn al fitxer .env de cada projecte:

# Projecte A (.env)
APP_PORT=8001
FORWARD_DB_PORT=3307
FORWARD_REDIS_PORT=6380
 
# Projecte B (.env)
APP_PORT=8002
FORWARD_DB_PORT=3308
FORWARD_REDIS_PORT=6381
 
# Projecte C (.env)
APP_PORT=8003
FORWARD_DB_PORT=3309
FORWARD_REDIS_PORT=6382

Amb aquesta configuració, els tres projectes poden funcionar simultàniament. El projecte A és accessible a http://localhost:8001, el B a http://localhost:8002 i el C a http://localhost:8003.

Una alternativa és aturar els contenidors d'un projecte abans d'iniciar un altre (sail down seguit de sail up -d al directori de l'altre projecte). Això és més senzill però no permet treballar en múltiples projectes simultàniament.

Sail vs Homestead vs Valet#

Laravel ofereix tres opcions principals per a l'entorn de desenvolupament local, cadascuna amb avantatges i inconvenients diferents. L'elecció depèn de les teves necessitats, el teu sistema operatiu i les teves preferències.

Laravel Valet (només macOS)#

Valet és un entorn de desenvolupament minimalista per a macOS. Instal·la PHP i un servidor Nginx directament al teu Mac, sense Docker ni màquines virtuals. L'aplicació Laravel s'executa directament al teu sistema operatiu, cosa que la fa extremadament ràpida.

Valet és ideal si treballes en macOS, tens PHP instal·lat localment i vols l'experiència més ràpida possible. El desavantatge és que no proporciona una base de dades ni Redis: has d'instal·lar-los tu mateix amb Homebrew. A més, l'entorn no és portable: cada desenvolupador ha de configurar el seu propi Valet amb les mateixes versions i extensions.

Laravel Homestead (qualsevol SO)#

Homestead és una màquina virtual Vagrant preconfigurada amb tot el que necessites: PHP, Nginx, MySQL, PostgreSQL, Redis, Memcached i molt més. Proporciona un entorn complet i aïllat, molt similar a un servidor de producció.

El desavantatge de Homestead és el rendiment: les màquines virtuals són més pesades que els contenidors Docker i la sincronització de fitxers entre el sistema amfitrió i la màquina virtual pot ser lenta, especialment a macOS. A més, Homestead requereix VirtualBox o VMware, que poden ser problemàtics en alguns sistemes.

Laravel Sail (qualsevol SO)#

Sail utilitza contenidors Docker, que són més lleugers que les màquines virtuals de Homestead però proporcionen un aïllament similar. Sail és la opció recomanada per la documentació oficial de Laravel i és el que ve preconfigurar amb els projectes nous.

| Característica | Sail (Docker) | Homestead (Vagrant) | Valet (natiu) | |---|---|---|---| | Sistema operatiu | Qualsevol | Qualsevol | Només macOS | | Rendiment | Bo | Moderat | Excel·lent | | Aïllament | Contenidors | Màquina virtual | Cap | | Serveis inclosos | Seleccionables | Tots | Cap (instal·lació manual) | | Ús de memòria | Moderat | Alt | Baix | | Configuració | Automàtica | Vagrantfile | Homebrew | | Portabilitat | Alta (docker-compose.yml) | Alta (Vagrantfile) | Baixa (local) | | Recomanat per Laravel | Sí (opció per defecte) | Sí (alternativa) | Sí (macOS) | | Múltiples projectes | Ports separats | Sites al Vagrantfile | Automàtic | | Depuració (Xdebug) | Integrat | Integrat | Configuració manual |

La recomanació general és: si comences amb Laravel, utilitza Sail. Si treballes en macOS i vols la velocitat màxima, considera Valet. Si necessites un entorn que repliqui exactament el servidor de producció, Homestead pot ser la millor opció.

Bones pràctiques#

Per treure el màxim profit de Sail, hi ha algunes pràctiques recomanades que val la pena seguir.

Inclou sempre el fitxer docker-compose.yml al repositori Git. Aquest fitxer defineix l'entorn complet i permet que qualsevol membre de l'equip pugui iniciar el projecte amb un simple sail up -d. No l'afegeixis al .gitignore.

No incloguis els volums de Docker al repositori. Els volums contenen dades dinàmiques (bases de dades, cache) que no s'han de versionar. Si necessites dades inicials, utilitza seeders (sail artisan db:seed).

Documenta la versió de PHP i els serveis necessaris al README del projecte. Si algú clona el repositori, ha de saber quina versió de PHP s'espera i quins serveis necessita. El docker-compose.yml ho mostra implícitament, però una menció explícita ajuda.

Utilitza la mateixa versió de PHP que en producció. Si el servidor de producció fa servir PHP 8.2, configura Sail amb SAIL_PHP_VERSION=8.2. Això evita sorpreses quan desplegueu codi que funciona en desenvolupament però no en producció per diferències de versió.

Executa sail build --no-cache després de canviar el Dockerfile o les extensions PHP. Docker fa servir cache agressivament, i de vegades els canvis no es reflecteixen fins que reconstrueixes la imatge sense cache.