Prologo

Primi Passi

Architettura

Le Basi

Approfondimenti

Sicurezza

Database

Eloquent ORM

Testing

Package

Sail

Introduzione

Laravel Sail è un’interfaccia a riga di comando leggera per interagire con l’ambiente di sviluppo Docker predefinito di Laravel. Sail offre un ottimo punto di partenza per costruire un’applicazione Laravel usando PHP, MySQL e Redis senza necessità di esperienza precedente con Docker.

Alla base, Sail è il file docker-compose.yml e lo script sail che si trovano nella radice del tuo progetto. Lo script sail fornisce una CLI con metodi comodi per interagire con i container Docker definiti dal file docker-compose.yml.

Laravel Sail è supportato su macOS, Linux e Windows (tramite WSL2).

Installazione e Configurazione

Laravel Sail viene installato automaticamente con tutte le nuove applicazioni Laravel, così puoi iniziare a usarlo subito. Per sapere come creare una nuova applicazione Laravel, consulta la documentazione di installazione di Laravel per il tuo sistema operativo. Durante l’installazione, ti verrà chiesto di scegliere con quali servizi supportati da Sail la tua applicazione interagirà.

Installare Sail nelle Applicazioni Esistenti

Se vuoi usare Sail con un’applicazione Laravel esistente, puoi semplicemente installare Sail usando il gestore di pacchetti Composer. Naturalmente, questi passaggi presuppongono che il tuo ambiente di sviluppo locale esistente permetta di installare le dipendenze di Composer:

composer require laravel/sail --dev

Dopo aver installato Sail, puoi eseguire il comando Artisan sail:install. Questo comando pubblicherà il file docker-compose.yml di Sail nella radice della tua applicazione e modificherà il tuo file .env con le variabili d’ambiente necessarie per connettersi ai servizi Docker:

php artisan sail:install

Infine, puoi avviare Sail. Per continuare a imparare come usare Sail, continua a leggere il resto di questa documentazione:

./vendor/bin/sail up

Se stai usando Docker Desktop per Linux, dovresti usare il contesto Docker default eseguendo il seguente comando: docker context use default.

Aggiungere Servizi Aggiuntivi

Se desideri aggiungere un servizio aggiuntivo alla tua installazione Sail esistente, puoi eseguire il comando Artisan sail:add:

php artisan sail:add

Utilizzo di Devcontainers

Se desideri sviluppare all’interno di un Devcontainer, puoi fornire l’opzione --devcontainer al comando sail:install. L’opzione --devcontainer istruirà il comando sail:install a pubblicare un file predefinito .devcontainer/devcontainer.json nella root della tua applicazione:

php artisan sail:install --devcontainer

Ricostruire le Immagini di Sail

A volte potresti voler ricostruire completamente le tue immagini di Sail per assicurarti che tutti i pacchetti e i software dell’immagine siano aggiornati. Puoi farlo utilizzando il comando build:

docker compose down -v

sail build --no-cache

sail up

Configurare un Alias della Shell

Di default, i comandi di Sail vengono eseguiti usando lo script vendor/bin/sail incluso in tutte le nuove applicazioni Laravel:

./vendor/bin/sail up

Tuttavia, invece di digitare ripetutamente vendor/bin/sail per eseguire i comandi di Sail, potresti voler configurare un alias della shell che ti permetta di eseguire i comandi di Sail più facilmente:

alias sail='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)'

Per assicurarti che sia sempre disponibile, puoi aggiungere questa riga al file di configurazione della tua shell nella tua directory home, come ~/.zshrc o ~/.bashrc, e poi riavviare la shell.

Una volta configurato l’alias della shell, puoi eseguire i comandi di Sail semplicemente digitando sail. Il resto degli esempi in questa documentazione presumerà che tu abbia configurato questo alias:

sail up

Avviare e Fermare Sail

Il file docker-compose.yml di Laravel Sail definisce diversi container Docker che lavorano insieme per aiutarti a costruire applicazioni Laravel. Ognuno di questi container è un elemento nella configurazione services del tuo file docker-compose.yml. Il container laravel.test è il principale container dell’applicazione che servirà la tua applicazione.

Prima di avviare Sail, assicurati che nessun altro server web o database sia in esecuzione sul tuo computer locale. Per avviare tutti i container Docker definiti nel file docker-compose.yml della tua applicazione, esegui il comando up:

sail up

Per avviare tutti i container Docker in background, puoi avviare Sail in modalità "detached":

sail up -d

Una volta avviati i container dell’applicazione, puoi accedere al progetto nel tuo browser web all’indirizzo: http://localhost.

Per fermare tutti i container, puoi semplicemente premere Control + C per interrompere l’esecuzione dei container. Oppure, se i container stanno girando in background, puoi usare il comando stop:

sail stop

Esecuzione dei comandi

Quando usi Laravel Sail, la tua applicazione viene eseguita all’interno di un contenitore Docker ed è isolata dal tuo computer locale. Tuttavia, Sail offre un modo comodo per eseguire vari comandi sulla tua applicazione, come comandi PHP arbitrari, comandi Artisan, comandi Composer e comandi Node / NPM.

Quando leggi la documentazione di Laravel, spesso vedrai riferimenti ai comandi Composer, Artisan e Node / NPM che non fanno riferimento a Sail. Questi esempi presumono che questi strumenti siano installati sul tuo computer locale. Se usi Sail per l’ambiente di sviluppo locale di Laravel, dovresti eseguire quei comandi tramite Sail:

# Eseguire comandi Artisan localmente...
php artisan queue:work

# Eseguire comandi Artisan all'interno di Laravel Sail...
sail artisan queue:work

Eseguire comandi PHP

I comandi PHP possono essere eseguiti usando il comando php. Naturalmente, questi comandi utilizzeranno la versione di PHP configurata per la tua applicazione. Per saperne di più sulle versioni PHP disponibili per Laravel Sail, consulta la documentazione sulle versioni PHP:

sail php --version

sail php script.php

Esecuzione dei comandi Composer

I comandi Composer possono essere eseguiti utilizzando il comando composer. Il contenitore dell’applicazione di Laravel Sail include un’installazione di Composer:

sail composer require laravel/sanctum

Installare le dipendenze Composer per applicazioni esistenti

Se stai sviluppando un’applicazione in team, potresti non essere tu a creare inizialmente l’applicazione Laravel. Pertanto, nessuna delle dipendenze Composer dell’applicazione, incluso Sail, verrà installata dopo aver clonato il repository dell’applicazione sul tuo computer locale.

Puoi installare le dipendenze dell’applicazione navigando nella directory dell’applicazione ed eseguendo il seguente comando. Questo comando utilizza un piccolo container Docker che contiene PHP e Composer per installare le dipendenze dell’applicazione:

docker run --rm \
    -u "$(id -u):$(id -g)" \
    -v "$(pwd):/var/www/html" \
    -w /var/www/html \
    laravelsail/php84-composer:latest \
    composer install --ignore-platform-reqs

Quando usi l’immagine laravelsail/phpXX-composer, dovresti utilizzare la stessa versione di PHP che prevedi di usare per la tua applicazione (80, 81, 82, 83 o 84).

Eseguire i comandi Artisan

I comandi Laravel Artisan possono essere eseguiti usando il comando artisan:

sail artisan queue:work

Eseguire Comandi Node / NPM

I comandi Node possono essere eseguiti usando il comando node, mentre i comandi NPM possono essere eseguiti usando il comando npm:

sail node --version

sail npm run dev

Se preferisci, puoi usare Yarn invece di NPM:

sail yarn

Interagire con i database

MySQL

Come avrai notato, il file docker-compose.yml della tua applicazione contiene una voce per un container MySQL. Questo container utilizza un volume Docker in modo che i dati memorizzati nel tuo database siano persistenti anche quando si fermano e si riavviano i container.

Inoltre, la prima volta che il container MySQL viene avviato, creerà due database per te. Il primo database prende il nome dal valore della tua variabile d’ambiente DB_DATABASE ed è destinato allo sviluppo locale. Il secondo è un database di test dedicato chiamato testing e garantirà che i tuoi test non interferiscano con i dati di sviluppo.

Una volta avviati i tuoi container, puoi connetterti all’istanza MySQL all’interno della tua applicazione impostando la variabile d’ambiente DB_HOST nel file .env della tua applicazione su mysql.

Per connetterti al database MySQL della tua applicazione dalla tua macchina locale, puoi utilizzare un’applicazione grafica per la gestione dei database come TablePlus. Per impostazione predefinita, il database MySQL è accessibile su localhost porta 3306 e le credenziali di accesso corrispondono ai valori delle tue variabili d’ambiente DB_USERNAME e DB_PASSWORD. In alternativa, puoi connetterti come utente root, che utilizza anche il valore della tua variabile d’ambiente DB_PASSWORD come password.

MongoDB

Se hai scelto di installare il servizio MongoDB durante l’installazione di Sail, il file docker-compose.yml della tua applicazione contiene una voce per un container MongoDB Atlas Local che fornisce il database documentale MongoDB con funzionalità di Atlas come Search Indexes. Questo container utilizza un Docker volume in modo che i dati memorizzati nel tuo database vengano preservati anche quando arresti e riavvii i container.

Una volta avviati i container, puoi connetterti all’istanza MongoDB all’interno della tua applicazione impostando la variabile d’ambiente MONGODB_URI nel file .env della tua applicazione su mongodb://mongodb:27017. L’autenticazione è disabilitata di default, ma puoi impostare le variabili d’ambiente MONGODB_USERNAME e MONGODB_PASSWORD per abilitare l’autenticazione prima di avviare il container mongodb. Poi, aggiungi le credenziali alla stringa di connessione:

MONGODB_USERNAME=user
MONGODB_PASSWORD=laravel
MONGODB_URI=mongodb://${MONGODB_USERNAME}:${MONGODB_PASSWORD}@mongodb:27017

Per un’integrazione perfetta di MongoDB con la tua applicazione, puoi installare il pacchetto ufficiale mantenuto da MongoDB.

Per connetterti al database MongoDB della tua applicazione dalla tua macchina locale, puoi usare un’interfaccia grafica come Compass. Per impostazione predefinita, il database MongoDB è accessibile su localhost porta 27017.

Redis

Il file docker-compose.yml della tua applicazione include anche un’entry per un container Redis. Questo container utilizza un Docker volume in modo che i dati memorizzati in Redis siano persistenti anche quando i container vengono arrestati e riavviati. Una volta avviati i container, puoi connetterti all’istanza Redis all’interno della tua applicazione impostando la variabile d’ambiente REDIS_HOST nel file .env della tua applicazione su redis.

Per connetterti al database Redis della tua applicazione dal tuo computer locale, puoi usare un’applicazione grafica per la gestione dei database come TablePlus. Per impostazione predefinita, il database Redis è accessibile su localhost porta 6379.

Meilisearch

Se hai scelto di installare il servizio Meilisearch durante l’installazione di Sail, il file docker-compose.yml della tua applicazione conterrà una voce per questo potente motore di ricerca integrato con Laravel Scout. Una volta avviati i tuoi container, puoi connetterti all’istanza di Meilisearch nella tua applicazione impostando la variabile d’ambiente MEILISEARCH_HOST su http://meilisearch:7700.

Dalla tua macchina locale, puoi accedere al pannello di amministrazione web di Meilisearch navigando su http://localhost:7700 nel tuo browser.

Typesense

Se hai scelto di installare il servizio Typesense durante l’installazione di Sail, il file docker-compose.yml della tua applicazione conterrà una voce per questo motore di ricerca open-source ultrarapido, integrato nativamente con Laravel Scout. Una volta avviati i tuoi container, puoi connetterti all’istanza di Typesense nella tua applicazione impostando le seguenti variabili di ambiente:

TYPESENSE_HOST=typesense
TYPESENSE_PORT=8108
TYPESENSE_PROTOCOL=http
TYPESENSE_API_KEY=xyz

Dalla tua macchina locale, puoi accedere all’API di Typesense tramite http://localhost:8108.

Archiviazione dei File

Se prevedi di utilizzare Amazon S3 per archiviare i file durante l’esecuzione della tua applicazione in ambiente di produzione, potresti voler installare il servizio MinIO durante l’installazione di Sail. MinIO fornisce un’API compatibile con S3 che puoi usare per sviluppare localmente utilizzando il driver di archiviazione dei file s3 di Laravel senza creare bucket di archiviazione "di test" nel tuo ambiente di produzione S3. Se scegli di installare MinIO durante l’installazione di Sail, verrà aggiunta una sezione di configurazione MinIO al file docker-compose.yml della tua applicazione.

Per impostazione predefinita, il file di configurazione filesystems della tua applicazione contiene già una configurazione del disco per il disco s3. Oltre a utilizzare questo disco per interagire con Amazon S3, puoi usarlo per interagire con qualsiasi servizio di archiviazione file compatibile con S3 come MinIO semplicemente modificando le variabili d’ambiente associate che controllano la sua configurazione. Ad esempio, quando usi MinIO, la configurazione delle variabili d’ambiente del filesystem dovrebbe essere definita come segue:

FILESYSTEM_DISK=s3
AWS_ACCESS_KEY_ID=sail
AWS_SECRET_ACCESS_KEY=password
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=local
AWS_ENDPOINT=http://minio:9000
AWS_USE_PATH_STYLE_ENDPOINT=true

Affinché l’integrazione Flysystem di Laravel generi URL corretti quando usi MinIO, dovresti definire la variabile d’ambiente AWS_URL in modo che corrisponda all’URL locale della tua applicazione e includa il nome del bucket nel percorso dell’URL:

AWS_URL=http://localhost:9000/local

Puoi creare bucket tramite la console di MinIO, disponibile all’indirizzo http://localhost:8900. Il nome utente predefinito per la console di MinIO è sail mentre la password predefinita è password.

Generare URL di archiviazione temporanea tramite il metodo temporaryUrl non è supportato quando si utilizza MinIO.

Eseguire i test

Laravel offre un supporto eccezionale per i test fin dall’installazione, e puoi usare il comando test di Sail per eseguire i test di funzionalità e unità delle tue applicazioni. Qualsiasi opzione CLI accettata da Pest / PHPUnit può essere passata al comando test:

sail test

sail test --group orders

Il comando test di Sail è equivalente all’esecuzione del comando Artisan test:

sail artisan test

Per impostazione predefinita, Sail creerà un database testing dedicato in modo che i tuoi test non interferiscano con lo stato attuale del tuo database. In un’installazione Laravel predefinita, Sail configurerà anche il tuo file phpunit.xml per utilizzare questo database durante l’esecuzione dei test:

<env name="DB_DATABASE" value="testing"/>

Laravel Dusk

Laravel Dusk offre un’API espressiva e facile da usare per l’automazione e il testing del browser. Grazie a Sail, puoi eseguire questi test senza installare Selenium o altri strumenti sul tuo computer locale. Per iniziare, decommenta il servizio Selenium nel file docker-compose.yml della tua applicazione:

selenium:
    image: 'selenium/standalone-chrome'
    extra_hosts:
      - 'host.docker.internal:host-gateway'
    volumes:
        - '/dev/shm:/dev/shm'
    networks:
        - sail

Successivamente, assicurati che il servizio laravel.test nel file docker-compose.yml della tua applicazione abbia una voce depends_on per selenium:

depends_on:
    - mysql
    - redis
    - selenium

Infine, puoi eseguire la suite di test Dusk avviando Sail e utilizzando il comando dusk:

sail dusk

Selenium su Apple Silicon

Se il tuo computer locale ha un chip Apple Silicon, il servizio selenium deve utilizzare l’immagine selenium/standalone-chromium:

selenium:
    image: 'selenium/standalone-chromium'
    extra_hosts:
        - 'host.docker.internal:host-gateway'
    volumes:
        - '/dev/shm:/dev/shm'
    networks:
        - sail

Anteprima delle Email

Il file predefinito docker-compose.yml di Laravel Sail contiene un servizio per Mailpit. Mailpit intercetta le email inviate dalla tua applicazione durante lo sviluppo locale e offre un’interfaccia web comoda per visualizzare le email nel tuo browser. Quando usi Sail, l’host predefinito di Mailpit è mailpit ed è disponibile tramite la porta 1025:

MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_ENCRYPTION=null

Quando Sail è in esecuzione, puoi accedere all’interfaccia web di Mailpit su: http://localhost:8025

Container CLI

A volte potresti voler avviare una sessione Bash all’interno del container della tua applicazione. Puoi usare il comando shell per connetterti al container della tua applicazione, permettendoti di ispezionare i suoi file e i servizi installati, oltre a eseguire comandi shell arbitrari all’interno del container:

sail shell

sail root-shell

Per avviare una nuova sessione Laravel Tinker, puoi eseguire il comando tinker:

sail tinker

Versioni PHP

Attualmente, Sail supporta l’esecuzione della tua applicazione tramite PHP 8.4, 8.3, 8.2, 8.1 o PHP 8.0. La versione predefinita di PHP utilizzata da Sail è PHP 8.4. Per cambiare la versione di PHP utilizzata per eseguire la tua applicazione, dovresti aggiornare la definizione build del container laravel.test nel file docker-compose.yml della tua applicazione:

# PHP 8.4
context: ./vendor/laravel/sail/runtimes/8.4

# PHP 8.3
context: ./vendor/laravel/sail/runtimes/8.3

# PHP 8.2
context: ./vendor/laravel/sail/runtimes/8.2

# PHP 8.1
context: ./vendor/laravel/sail/runtimes/8.1

# PHP 8.0
context: ./vendor/laravel/sail/runtimes/8.0

Inoltre, potresti voler aggiornare il nome della tua image per riflettere la versione di PHP utilizzata dalla tua applicazione. Questa opzione è definita anche nel file docker-compose.yml della tua applicazione:

image: sail-8.2/app

Dopo aver aggiornato il file docker-compose.yml della tua applicazione, dovresti ricostruire le immagini dei container:

sail build --no-cache

sail up

Versioni di Node

Sail installa Node 20 per impostazione predefinita. Per cambiare la versione di Node installata durante la costruzione delle tue immagini, puoi aggiornare la definizione build.args del servizio laravel.test nel file docker-compose.yml della tua applicazione:

build:
    args:
        WWWGROUP: '${WWWGROUP}'
        NODE_VERSION: '18'

Dopo aver aggiornato il file docker-compose.yml della tua applicazione, dovresti ricostruire le immagini dei container:

sail build --no-cache

sail up

Condividere il tuo sito

A volte potresti aver bisogno di condividere il tuo sito pubblicamente per mostrarlo a un collega o per testare le integrazioni webhook con la tua applicazione. Per condividere il tuo sito, puoi usare il comando share. Dopo aver eseguito questo comando, ti verrà assegnato un URL casuale laravel-sail.site che puoi usare per accedere alla tua applicazione:

sail share

Quando condividi il tuo sito tramite il comando share, dovresti configurare i proxy fidati della tua applicazione usando il metodo trustProxies nel file bootstrap/app.php della tua applicazione. Altrimenti, gli helper per la generazione degli URL come url e route non saranno in grado di determinare l’host HTTP corretto da usare durante la generazione degli URL:

    ->withMiddleware(function (Middleware $middleware) {
        $middleware->trustProxies(at: '*');
    })

Se desideri scegliere il sottodominio per il tuo sito condiviso, puoi fornire l’opzione subdomain quando esegui il comando share:

sail share --subdomain=my-sail-site

Il comando share è supportato da Expose, un servizio di tunneling open source di BeyondCode.

Debugging con Xdebug

La configurazione Docker di Laravel Sail include il supporto per Xdebug, un debugger popolare e potente per PHP. Per abilitare Xdebug, assicurati di aver pubblicato la tua configurazione Sail. Successivamente, aggiungi le seguenti variabili al file .env della tua applicazione per configurare Xdebug:

SAIL_XDEBUG_MODE=develop,debug,coverage

Successivamente, assicurati che il file php.ini pubblicato includa la seguente configurazione affinché Xdebug sia attivato nelle modalità specificate:

[xdebug]
xdebug.mode=${XDEBUG_MODE}

Dopo aver modificato il file php.ini, ricordati di ricostruire le immagini Docker affinché le modifiche al file php.ini abbiano effetto:

sail build --no-cache

Configurazione IP Host Linux

Internamente, la variabile d’ambiente XDEBUG_CONFIG è definita come client_host=host.docker.internal in modo che Xdebug sia configurato correttamente per Mac e Windows (WSL2). Se la tua macchina locale esegue Linux e stai usando Docker 20.10+, host.docker.internal è disponibile e non è necessaria alcuna configurazione manuale.

Per le versioni di Docker precedenti alla 20.10, host.docker.internal non è supportato su Linux e dovrai definire manualmente l’IP host. Per fare ciò, configura un IP statico per il tuo container definendo una rete personalizzata nel tuo file docker-compose.yml:

networks:
  custom_network:
    ipam:
      config:
        - subnet: 172.20.0.0/16

services:
  laravel.test:
    networks:
      custom_network:
        ipv4_address: 172.20.0.2

Una volta impostato l’IP statico, definisci la variabile SAIL_XDEBUG_CONFIG all’interno del file .env della tua applicazione:

SAIL_XDEBUG_CONFIG="client_host=172.20.0.2"

Utilizzo di Xdebug CLI

Il comando sail debug può essere utilizzato per avviare una sessione di debug quando si esegue un comando Artisan:

# Esegui un comando Artisan senza Xdebug...
sail artisan migrate

# Esegui un comando Artisan con Xdebug...
sail debug migrate

Utilizzo di Xdebug nel Browser

Per fare il debug della tua applicazione mentre interagisci tramite un browser web, segui le istruzioni fornite da Xdebug per avviare una sessione Xdebug dal browser.

Se usi PhpStorm, consulta la documentazione di JetBrains relativa al debugging senza configurazioni.

Laravel Sail si basa su artisan serve per servire la tua applicazione. Il comando artisan serve accetta solo le variabili XDEBUG_CONFIG e XDEBUG_MODE a partire dalla versione Laravel 8.53.0. Le versioni precedenti di Laravel (8.52.0 e inferiori) non supportano queste variabili e non accetteranno connessioni di debug.

Personalizzazione

Poiché Sail è semplicemente Docker, sei libero di personalizzare quasi tutto. Per pubblicare i Dockerfile di Sail, puoi eseguire il comando sail:publish:

sail artisan sail:publish

Dopo aver eseguito questo comando, i Dockerfile e altri file di configurazione utilizzati da Laravel Sail saranno posizionati nella cartella docker nella directory principale della tua applicazione. Dopo aver personalizzato l’installazione di Sail, potresti voler cambiare il nome dell’immagine per il contenitore dell’applicazione nel file docker-compose.yml della tua applicazione. Dopo averlo fatto, ricostruisci i contenitori della tua applicazione usando il comando build. Assegnare un nome unico all’immagine dell’applicazione è particolarmente importante se usi Sail per sviluppare più applicazioni Laravel su una singola macchina:

sail build --no-cache
Lascia un commento

Lascia un commento

Il tuo indirizzo email non sarà pubblicato. I campi obbligatori sono contrassegnati *

Laravel-Italia.it è il sito della Community Italiana di Laravel.
2024 — Laravel-Italia