Guida Completa a Laravel Sail: Semplificare lo Sviluppo PHP con Docker

Principiante
PHP Laravel

Scopri cos'è Laravel Sail, come installarlo e come utilizzarlo per creare ambienti di sviluppo isolati e coerenti utilizzando Docker senza dover essere un esperto di DevOps.

Pubblicato
Tag
PHP laravel DevOps Docker backend Sail

Introduzione a Laravel Sail

Se sei un principiante nello sviluppo web con PHP e Laravel, potresti esserti imbattuto in un problema comune: la configurazione dell'ambiente di sviluppo. Installare PHP, Composer, un server web come Nginx o Apache, e un database come MySQL direttamente sul proprio sistema operativo (il cosiddetto "bare metal") può essere frustrante. Spesso ci si ritrova con versioni diverse tra i vari membri del team o con conflitti tra software installati per progetti differenti.

Laravel Sail nasce per risolvere esattamente questo problema. Sail è un'interfaccia a riga di comando (CLI) leggera che fornisce un'astrazione semplice per l'interazione con Docker. In termini semplici, Sail permette di avviare un ambiente di sviluppo completo, preconfigurato e isolato, senza che tu debba scrivere manualmente complessi file di configurazione Docker o conoscere a fondo ogni comando di Docker.

Perché usare Sail? Perché Docker permette di "impacchettare" l'applicazione e tutte le sue dipendenze in contenitori. Questo significa che l'ambiente in cui scrivi il codice è identico a quello dei tuoi colleghi e, potenzialmente, molto simile a quello di produzione. Non sentirai più la frase "ma sul mio computer funziona!".

Comprendere i concetti base: Docker e i Contenitori

Prima di tuffarci in Sail, è fondamentale capire cosa succede "sotto il cofano". Docker non è una macchina virtuale (VM). Mentre una VM emula l'intero hardware e carica un intero sistema operativo guest, Docker condivide il kernel del sistema operativo dell'host, isolando solo i processi dell'applicazione.

Perché Docker è fondamentale per Laravel?

Un progetto Laravel moderno non ha bisogno solo di PHP. Ha bisogno di:

  • PHP: Il linguaggio di programmazione.
  • MySQL/PostgreSQL: Per l'archiviazione dei dati.
  • Redis: Per la gestione della cache e delle code.
  • Mailpit: Per testare l'invio di email localmente.
  • Meilisearch: Per ricerche full-text avanzate.

Configurare tutti questi servizi manualmente richiederebbe ore. Sail automatizza questo processo creando un file chiamato docker-compose.yml, che istruisce Docker su quali "immagini" scaricare e come collegarle tra loro in una rete virtuale.

Installazione e Configurazione Iniziale

Per utilizzare Laravel Sail, devi avere installato Docker Desktop (su Windows, macOS o Linux). Se sei su Windows, è caldamente consigliato l'utilizzo di WSL2 (Windows Subsystem for Linux), poiché Docker e Laravel girano in modo nativamente più efficiente su un kernel Linux.

Creare un nuovo progetto con Sail

Il modo più semplice per iniziare è utilizzare il comando di installazione ufficiale fornito da Laravel. Non hai nemmeno bisogno di avere PHP o Composer installati localmente sulla tua macchina, poiché Laravel utilizzerà un contenitore temporaneo per eseguire l'installazione.

Ecco il comando da eseguire nel tuo terminale (Bash o PowerShell):

curl -s "https://laravel.build/mio-progetto" | bash

Spiegazione del comando:

  1. curl: Scarica lo script di installazione dal server di Laravel.
  2. https://laravel.build/mio-progetto: Specifica il nome della cartella in cui verrà creato il progetto.
  3. | bash: Passa lo script scaricato direttamente all'interprete Bash per l'esecuzione.

Una volta completato il processo, entrerai nella cartella del progetto e avvierai l'ambiente con il seguente comando:

cd mio-progetto
./vendor/bin/sail up -d

Il flag -d (detached mode) avvia i contenitori in background, permettendoti di continuare a usare il terminale.

Gestire l'ambiente con i comandi Sail

Ora che l'ambiente è attivo, non userai più i comandi globali (come php artisan o composer install) direttamente sul tuo PC. Perché? Perché PHP non è installato sul tuo PC, ma dentro il contenitore Docker. Sail funge da ponte.

I comandi più comuni

Invece di scrivere php artisan migrate, scriverai sail artisan migrate. Sail instrude Docker a eseguire quel comando all'interno del contenitore PHP.

Ecco una tabella di conversione rapida:

  • Artisan: php artisan ... $ ightarrow$ ./vendor/bin/sail artisan ...
  • Composer: composer install $ ightarrow$ ./vendor/bin/sail composer install
  • Node/NPM: npm run dev $ ightarrow$ ./vendor/bin/sail npm run dev
  • Test: php vendor/bin/phpunit $ ightarrow$ ./vendor/bin/sail test

Creare un alias per comodità

Scrivere ogni volta ./vendor/bin/sail è noioso. La maggior parte degli sviluppatori crea un "alias" nel proprio file di configurazione della shell (.zshrc o .bashrc):

alias sail='[ -f sail ] && bash sail || bash vendor/bin/sail'

Dopo aver aggiunto questa riga e riavviato il terminale, potrai semplicemente digitare sail up o sail artisan migrate.

Personalizzare i servizi in docker-compose.yml

Uno dei punti di forza di Sail è la flessibilità. Se il tuo progetto non ha bisogno di Redis ma preferisce PostgreSQL invece di MySQL, puoi modificare la configurazione.

Il file docker-compose.yml definisce l'architettura del tuo ambiente. Ecco un esempio semplificato di come appare una sezione di questo file:

services:
    laravel.test:
        build:
            context: ./vendor/laravel/sail/runtimes/8.2
            dockerfile: Dockerfile
        ports:
            - "80:80"
        environment:
            WWWUSER: '${WWWUSER}'
            COMPOSE_PROJECT_NAME: '${COMPOSE_PROJECT_NAME}'
        volumes:
            - '.:/var/www/html'
        networks:
            - sail
    mysql:
        image: 'mysql/mysql-server:8.0'
        ports:
            - '3306:3306'
        environment:
            MYSQL_ROOT_PASSWORD: '${DB_PASSWORD}'
        networks:
            - sail

Analisi del codice:

  • laravel.test: È il contenitore principale dove gira il tuo codice PHP. Il volume .:/var/www/html sincronizza la cartella del tuo PC con quella del contenitore: ogni modifica al file che fai nell'editor (VS Code) è istantaneamente visibile nel browser.
  • mysql: È un contenitore separato che gira il database. Comunica con il contenitore Laravel tramite la rete definita in networks.
  • ports: Mappano la porta del contenitore alla porta del tuo PC. Ad esempio, 80:80 significa che visitando http://localhost nel browser, verrai indirizzato al server web interno al contenitore.

Esempi Pratici e Casi d'Uso Reali

Caso 1: Aggiungere un nuovo servizio (es. MongoDB)

Immagina di dover integrare MongoDB nel tuo progetto Laravel. Invece di installarlo localmente, puoi aggiungere un blocco di codice al tuo docker-compose.yml sotto la sezione services:

    mongodb:
        image: 'mongo:latest'
        ports:
            - '27017:27017'
        networks:
            - sail

Dopo aver salvato il file, esegui sail down e sail up -d per ricostruire l'ambiente. Ora hai un database MongoDB pronto all'uso, isolato e configurato.

Caso 2: Collaborazione in Team

Quando un nuovo sviluppatore si unisce al progetto, non deve più seguire un manuale di 10 pagine su come installare PHP, estensioni, MySQL e Redis. Gli basterà:

  1. Clonare il repository Git.
  2. Eseguire composer install (tramite un contenitore temporaneo).
  3. Eseguire sail up -d.

L'ambiente sarà identico a quello di chiunque altro nel team, eliminando i bug legati alle differenze di versione del software.

Errori Comuni e FAQ

1. "Port 80 is already in use"

Questo è l'errore più comune. Accade quando hai già un server web (come XAMPP o Apache) installato e attivo sul tuo PC. Soluzione: Apri il file .env e cambia la porta di Laravel: APP_PORT=8080 Ora l'app sarà raggiungibile su http://localhost:8080.

2. Problemi di permessi su Linux/macOS

A volte i file creati da Sail (che gira come utente root nel contenitore) appartengono a root e non all'utente locale. Soluzione: Sail gestisce questo tramite la variabile WWWUSER. Assicurati che Docker Desktop sia correttamente configurato per mappare l'utente corrente.

3. Sail è lento su Windows

Se noti che il caricamento delle pagine è lento, è probabile che tu stia aprendo il progetto in una cartella di Windows (es. C:\\Users\\Nome\\Progetti). Soluzione: Sposta il progetto all'interno del file system di WSL2 (es. \\wsl$\\Ubuntu\\home\\utente\\progetti). La differenza di performance è drastica.

Prossimi Passi

Ora che hai familiarità con Laravel Sail, sei pronto per esplorare concetti più avanzati di DevOps e sviluppo web. Ecco alcuni suggerimenti per approfondire:

  1. Ottimizzazione delle Immagini: Impara a creare i tuoi Dockerfile personalizzati se hai bisogno di installare estensioni PHP specifiche non incluse nel runtime di Sail.
  2. CI/CD: Scopri come usare GitHub Actions per eseguire i test di Laravel in un ambiente Docker simile a quello di Sail prima di fare il deploy in produzione.
  3. Laravel Forge: Quando sarai pronto per pubblicare il tuo sito online, esplora Laravel Forge, che semplifica enormemente la gestione dei server VPS.
  4. Studio di Database: Prova a collegare un client esterno come TablePlus o DBeaver al database di Sail utilizzando la porta 3306 definita nel docker-compose.yml.

Utilizzare Sail non è solo un modo per installare Laravel, ma è il primo passo verso una mentalità professionale di sviluppo "containerizzata", che ti renderà uno sviluppatore più versatile e preparato alle esigenze delle aziende moderne.

Continua a leggere