Laravel Sail

• Introducción
• Instalación y Configuración
  • Instalando Sail en Aplicaciones Existentes
  • Configurando un Alias de Shell
• Iniciar y Detener Sail
• Ejecutando Comandos
  • Ejecutando Comandos PHP
  • Ejecutando Comandos Composer
  • Ejecutando Comandos Artisan
  • Ejecutando Comandos Node / NPM
• Interacción con Bases de Datos
  • MySQL
  • Redis
  • Meilisearch
  • Typesense
• Almacenamiento de Archivos
• Ejecutando Tests
  • Laravel Dusk
• Vista Previa de Correos Electrónicos
• CLI del Contenedor
• Versiones de PHP
• Versiones de Node
• Compartiendo Su Sitio
• Depuración con Xdebug
  • Uso de Xdebug en CLI
  • Uso de Xdebug en Navegador
• Personalización

#Introducción

Laravel Sail es una interfaz de línea de comandos ligera para interactuar con el entorno de desarrollo Docker predeterminado de Laravel. Sail ofrece un excelente punto de partida para construir una aplicación Laravel usando PHP, MySQL y Redis sin requerir experiencia previa con Docker.

En esencia, Sail es el archivo docker-compose.yml y el script sail que se almacenan en la raíz de su proyecto. El script sail proporciona una CLI con métodos convenientes para interactuar con los contenedores Docker definidos en el archivo docker-compose.yml.

Laravel Sail es compatible con macOS, Linux y Windows (a través de WSL2).

#Instalación y Configuración

Laravel Sail se instala automáticamente con todas las nuevas aplicaciones Laravel para que pueda comenzar a usarlo de inmediato. Para aprender cómo crear una nueva aplicación Laravel, consulte la documentación de instalación de Laravel para su sistema operativo. Durante la instalación, se le pedirá que elija con qué servicios compatibles con Sail interactuará su aplicación.

#Instalando Sail en Aplicaciones Existentes

Si desea usar Sail con una aplicación Laravel existente, simplemente puede instalar Sail usando el gestor de paquetes Composer. Por supuesto, estos pasos asumen que su entorno local de desarrollo permite instalar dependencias de Composer:

composer require laravel/sail --dev

Después de instalar Sail, puede ejecutar el comando Artisan sail:install. Este comando publicará el archivo docker-compose.yml de Sail en la raíz de su aplicación y modificará su archivo .env con las variables de entorno necesarias para conectarse a los servicios Docker:

php artisan sail:install

Finalmente, puede iniciar Sail. Para continuar aprendiendo cómo usar Sail, siga leyendo el resto de esta documentación:

./vendor/bin/sail up

#Añadiendo Servicios Adicionales

Si desea agregar un servicio adicional a su instalación existente de Sail, puede ejecutar el comando Artisan sail:add:

php artisan sail:add

#Usando Devcontainers

Si desea desarrollar dentro de un Devcontainer, puede proporcionar la opción --devcontainer al comando sail:install. La opción --devcontainer indicará al comando sail:install que publique un archivo .devcontainer/devcontainer.json predeterminado en la raíz de su aplicación:

php artisan sail:install --devcontainer

#Configurando un Alias de Shell

Por defecto, los comandos de Sail se invocan usando el script vendor/bin/sail que se incluye con todas las nuevas aplicaciones Laravel:

./vendor/bin/sail up

Sin embargo, en lugar de escribir repetidamente vendor/bin/sail para ejecutar comandos de Sail, puede configurar un alias de shell que le permita ejecutar los comandos de Sail más fácilmente:

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

Para asegurarse de que esto esté siempre disponible, puede agregarlo a su archivo de configuración de shell en su directorio home, como ~/.zshrc o ~/.bashrc, y luego reiniciar su shell.

Una vez configurado el alias de shell, puede ejecutar los comandos de Sail simplemente escribiendo sail. El resto de los ejemplos en esta documentación asumirán que ha configurado este alias:

sail up

#Iniciar y Detener Sail

El archivo docker-compose.yml de Laravel Sail define una variedad de contenedores Docker que trabajan juntos para ayudarle a construir aplicaciones Laravel. Cada uno de estos contenedores es una entrada dentro de la configuración services de su archivo docker-compose.yml. El contenedor laravel.test es el contenedor principal de la aplicación que servirá su aplicación.

Antes de iniciar Sail, debe asegurarse de que ningún otro servidor web o base de datos esté ejecutándose en su computadora local. Para iniciar todos los contenedores Docker definidos en el archivo docker-compose.yml de su aplicación, debe ejecutar el comando up:

sail up

Para iniciar todos los contenedores Docker en segundo plano, puede iniciar Sail en modo "detached":

sail up -d

Una vez que los contenedores de la aplicación estén iniciados, puede acceder al proyecto en su navegador web en: http://localhost.

Para detener todos los contenedores, simplemente puede presionar Control + C para detener la ejecución del contenedor. O, si los contenedores están ejecutándose en segundo plano, puede usar el comando stop:

sail stop

#Ejecutando Comandos

Cuando usa Laravel Sail, su aplicación se ejecuta dentro de un contenedor Docker y está aislada de su computadora local. Sin embargo, Sail proporciona una forma conveniente de ejecutar varios comandos contra su aplicación, como comandos PHP arbitrarios, comandos Artisan, comandos Composer y comandos Node / NPM.

Al leer la documentación de Laravel, a menudo verá referencias a comandos de Composer, Artisan y Node / NPM que no mencionan Sail. Esos ejemplos asumen que estas herramientas están instaladas en su computadora local. Si usa Sail para su entorno local de desarrollo Laravel, debe ejecutar esos comandos usando Sail:

# Ejecutando comandos Artisan localmente...
php artisan queue:work

# Ejecutando comandos Artisan dentro de Laravel Sail...
sail artisan queue:work

#Ejecutando Comandos PHP

Los comandos PHP pueden ejecutarse usando el comando php. Por supuesto, estos comandos se ejecutarán usando la versión de PHP configurada para su aplicación. Para aprender más sobre las versiones de PHP disponibles en Laravel Sail, consulte la documentación de versiones de PHP:

sail php --version

sail php script.php

#Ejecutando Comandos Composer

Los comandos Composer pueden ejecutarse usando el comando composer. El contenedor de la aplicación de Laravel Sail incluye una instalación de Composer 2.x:

sail composer require laravel/sanctum

#Instalando Dependencias Composer para Aplicaciones Existentes

Si está desarrollando una aplicación con un equipo, puede que usted no sea quien creó inicialmente la aplicación Laravel. Por lo tanto, ninguna de las dependencias Composer de la aplicación, incluyendo Sail, estará instalada después de clonar el repositorio de la aplicación en su computadora local.

Puede instalar las dependencias de la aplicación navegando al directorio de la aplicación y ejecutando el siguiente comando. Este comando usa un pequeño contenedor Docker que contiene PHP y Composer para instalar las dependencias de la aplicación:

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

Al usar la imagen laravelsail/phpXX-composer, debe usar la misma versión de PHP que planea usar para su aplicación (80, 81, 82 o 83).

#Ejecutando Comandos Artisan

Los comandos Artisan de Laravel pueden ejecutarse usando el comando artisan:

sail artisan queue:work

#Ejecutando Comandos Node / NPM

Los comandos Node pueden ejecutarse usando el comando node, mientras que los comandos NPM pueden ejecutarse usando el comando npm:

sail node --version

sail npm run dev

Si lo desea, puede usar Yarn en lugar de NPM:

sail yarn

#Interacción con Bases de Datos

#MySQL

Como habrá notado, el archivo docker-compose.yml de su aplicación contiene una entrada para un contenedor MySQL. Este contenedor usa un volumen Docker para que los datos almacenados en su base de datos se mantengan incluso al detener y reiniciar sus contenedores.

Además, la primera vez que el contenedor MySQL se inicia, creará dos bases de datos para usted. La primera base de datos se nombra usando el valor de su variable de entorno DB_DATABASE y es para su desarrollo local. La segunda es una base de datos dedicada para pruebas llamada testing y asegurará que sus tests no interfieran con sus datos de desarrollo.

Una vez que haya iniciado sus contenedores, puede conectarse a la instancia MySQL dentro de su aplicación configurando la variable de entorno DB_HOST en el archivo .env de su aplicación a mysql.

Para conectarse a la base de datos MySQL de su aplicación desde su máquina local, puede usar una aplicación gráfica de gestión de bases de datos como TablePlus. Por defecto, la base de datos MySQL es accesible en localhost puerto 3306 y las credenciales de acceso corresponden a los valores de sus variables de entorno DB_USERNAME y DB_PASSWORD. O bien, puede conectarse como usuario root, que también utiliza el valor de su variable de entorno DB_PASSWORD como contraseña.

#Redis

El archivo docker-compose.yml de su aplicación también contiene una entrada para un contenedor Redis. Este contenedor usa un volumen Docker para que los datos almacenados en Redis se mantengan incluso al detener y reiniciar sus contenedores. Una vez que haya iniciado sus contenedores, puede conectarse a la instancia Redis dentro de su aplicación configurando la variable de entorno REDIS_HOST en el archivo .env de su aplicación a redis.

Para conectarse a la base de datos Redis de su aplicación desde su máquina local, puede usar una aplicación gráfica de gestión de bases de datos como TablePlus. Por defecto, la base de datos Redis es accesible en localhost puerto 6379.

#Meilisearch

Si eligió instalar el servicio Meilisearch al instalar Sail, el archivo docker-compose.yml de su aplicación contendrá una entrada para este potente motor de búsqueda que es compatible con Laravel Scout. Una vez que haya iniciado sus contenedores, puede conectarse a la instancia Meilisearch dentro de su aplicación configurando la variable de entorno MEILISEARCH_HOST a http://meilisearch:7700.

Desde su máquina local, puede acceder al panel de administración web de Meilisearch navegando a http://localhost:7700 en su navegador web.

#Typesense

Si eligió instalar el servicio Typesense al instalar Sail, el archivo docker-compose.yml de su aplicación contendrá una entrada para este motor de búsqueda de código abierto y muy rápido que está integrado nativamente con Laravel Scout. Una vez que haya iniciado sus contenedores, puede conectarse a la instancia Typesense dentro de su aplicación configurando las siguientes variables de entorno:

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

Desde su máquina local, puede acceder a la API de Typesense vía http://localhost:8108.

#Almacenamiento de Archivos

Si planea usar Amazon S3 para almacenar archivos mientras ejecuta su aplicación en producción, puede que desee instalar el servicio MinIO al instalar Sail. MinIO proporciona una API compatible con S3 que puede usar para desarrollar localmente usando el driver de almacenamiento de archivos s3 de Laravel sin crear buckets "de prueba" en su entorno S3 de producción. Si elige instalar MinIO al instalar Sail, se añadirá una sección de configuración de MinIO al archivo docker-compose.yml de su aplicación.

Por defecto, el archivo de configuración filesystems de su aplicación ya contiene una configuración de disco para el disco s3. Además de usar este disco para interactuar con Amazon S3, puede usarlo para interactuar con cualquier servicio de almacenamiento compatible con S3 como MinIO simplemente modificando las variables de entorno asociadas que controlan su configuración. Por ejemplo, al usar MinIO, la configuración de variables de entorno de su sistema de archivos debería definirse así:

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

Para que la integración de Flysystem de Laravel genere URLs correctas al usar MinIO, debe definir la variable de entorno AWS_URL para que coincida con la URL local de su aplicación e incluya el nombre del bucket en la ruta de la URL:

AWS_URL=http://localhost:9000/local

Puede crear buckets a través de la consola de MinIO, que está disponible en http://localhost:8900. El nombre de usuario predeterminado para la consola de MinIO es sail y la contraseña predeterminada es password.

#Ejecutando Tests

Laravel ofrece un soporte increíble para testing desde el primer momento, y puede usar el comando test de Sail para ejecutar los tests de características y unitarios de su aplicación. Cualquier opción de CLI aceptada por PHPUnit también puede pasarse al comando test:

sail test

sail test --group orders

El comando test de Sail es equivalente a ejecutar el comando Artisan test:

sail artisan test

Por defecto, Sail creará una base de datos dedicada testing para que sus tests no interfieran con el estado actual de su base de datos. En una instalación Laravel por defecto, Sail también configurará su archivo phpunit.xml para usar esta base de datos al ejecutar sus tests:

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

#Laravel Dusk

Laravel Dusk proporciona una API expresiva y fácil de usar para automatización y testing en navegador. Gracias a Sail, puede ejecutar estos tests sin necesidad de instalar Selenium u otras herramientas en su computadora local. Para comenzar, descomente el servicio Selenium en el archivo docker-compose.yml de su aplicación:

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

Luego, asegúrese de que el servicio laravel.test en el archivo docker-compose.yml de su aplicación tenga una entrada depends_on para selenium:

depends_on:
    - mysql
    - redis
    - selenium

Finalmente, puede ejecutar su suite de tests Dusk iniciando Sail y ejecutando el comando dusk:

sail dusk

#Selenium en Apple Silicon

Si su máquina local tiene un chip Apple Silicon, su servicio selenium debe usar la imagen seleniarm/standalone-chromium:

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

#Vista Previa de Correos Electrónicos

El archivo docker-compose.yml predeterminado de Laravel Sail contiene una entrada de servicio para Mailpit. Mailpit intercepta los correos electrónicos enviados por su aplicación durante el desarrollo local y proporciona una interfaz web conveniente para que pueda previsualizar sus mensajes de correo en el navegador. Al usar Sail, el host predeterminado de Mailpit es mailpit y está disponible en el puerto 1025:

MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_ENCRYPTION=null

Cuando Sail está en ejecución, puede acceder a la interfaz web de Mailpit en: http://localhost:8025

#CLI del Contenedor

A veces puede que desee iniciar una sesión Bash dentro del contenedor de su aplicación. Puede usar el comando shell para conectarse al contenedor de su aplicación, lo que le permitirá inspeccionar sus archivos y servicios instalados, así como ejecutar comandos shell arbitrarios dentro del contenedor:

sail shell

sail root-shell

Para iniciar una nueva sesión de Laravel Tinker, puede ejecutar el comando tinker:

sail tinker

#Versiones de PHP

Sail actualmente soporta servir su aplicación con PHP 8.3, 8.2, 8.1 o PHP 8.0. La versión predeterminada de PHP usada por Sail es actualmente PHP 8.3. Para cambiar la versión de PHP que se usa para servir su aplicación, debe actualizar la definición build del contenedor laravel.test en el archivo docker-compose.yml de su aplicación:

# 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

Además, puede que desee actualizar el nombre de su image para reflejar la versión de PHP que usa su aplicación. Esta opción también se define en el archivo docker-compose.yml de su aplicación:

image: sail-8.1/app

Después de actualizar el archivo docker-compose.yml de su aplicación, debe reconstruir las imágenes de sus contenedores:

sail build --no-cache

sail up

#Versiones de Node

Sail instala Node 20 por defecto. Para cambiar la versión de Node que se instala al construir sus imágenes, puede actualizar la definición build.args del servicio laravel.test en el archivo docker-compose.yml de su aplicación:

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

Después de actualizar el archivo docker-compose.yml de su aplicación, debe reconstruir las imágenes de sus contenedores:

sail build --no-cache

sail up

#Compartiendo Su Sitio

A veces puede necesitar compartir su sitio públicamente para previsualizarlo con un colega o para probar integraciones webhook con su aplicación. Para compartir su sitio, puede usar el comando share. Después de ejecutar este comando, se le asignará una URL aleatoria laravel-sail.site que podrá usar para acceder a su aplicación:

sail share

Al compartir su sitio mediante el comando share, debe configurar los proxies confiables de su aplicación dentro del middleware TrustProxies. De lo contrario, los ayudantes de generación de URL como url y route no podrán determinar el host HTTP correcto que debe usarse durante la generación de URLs:

/**
 * Los proxies confiables para esta aplicación.
 *
 * @var array|string|null
 */
protected $proxies = '*';

Si desea elegir el subdominio para su sitio compartido, puede proporcionar la opción subdomain al ejecutar el comando share:

sail share --subdomain=my-sail-site

#Depuración con Xdebug

La configuración Docker de Laravel Sail incluye soporte para Xdebug, un depurador popular y potente para PHP. Para habilitar Xdebug, deberá agregar algunas variables a su archivo .env para configurar Xdebug. Para habilitar Xdebug debe establecer el/los modo(s) apropiado(s) antes de iniciar Sail:

SAIL_XDEBUG_MODE=develop,debug,coverage

#Configuración de IP del Host en Linux

Internamente, la variable de entorno XDEBUG_CONFIG se define como client_host=host.docker.internal para que Xdebug se configure correctamente en Mac y Windows (WSL2). Si su máquina local ejecuta Linux, debe asegurarse de que está usando Docker Engine 17.06.0+ y Compose 1.16.0+. De lo contrario, deberá definir manualmente esta variable de entorno como se muestra a continuación.

Primero, debe determinar la dirección IP correcta del host para agregar a la variable de entorno ejecutando el siguiente comando. Normalmente, <container-name> debe ser el nombre del contenedor que sirve su aplicación y a menudo termina con _laravel.test_1:

docker inspect -f {{range.NetworkSettings.Networks}}{{.Gateway}}{{end}} <container-name>

Una vez que haya obtenido la dirección IP correcta del host, debe definir la variable SAIL_XDEBUG_CONFIG en el archivo .env de su aplicación:

SAIL_XDEBUG_CONFIG="client_host=<host-ip-address>"

#Uso de Xdebug en CLI

Puede usar el comando sail debug para iniciar una sesión de depuración al ejecutar un comando Artisan:

# Ejecutar un comando Artisan sin Xdebug...
sail artisan migrate

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

#Uso de Xdebug en Navegador

Para depurar su aplicación mientras interactúa con ella a través de un navegador web, siga las instrucciones proporcionadas por Xdebug para iniciar una sesión Xdebug desde el navegador.

Si usa PhpStorm, revise la documentación de JetBrains sobre depuración sin configuración.

#Personalización

Dado que Sail es simplemente Docker, usted es libre de personalizar casi todo sobre él. Para publicar los propios Dockerfiles de Sail, puede ejecutar el comando sail:publish:

sail artisan sail:publish

Después de ejecutar este comando, los Dockerfiles y otros archivos de configuración usados por Laravel Sail se colocarán dentro de un directorio docker en la raíz de su aplicación. Después de personalizar su instalación de Sail, puede que desee cambiar el nombre de la imagen para el contenedor de la aplicación en el archivo docker-compose.yml de su aplicación. Después de hacerlo, reconstruya los contenedores de su aplicación usando el comando build. Asignar un nombre único a la imagen de la aplicación es especialmente importante si usa Sail para desarrollar múltiples aplicaciones Laravel en una sola máquina:

sail build --no-cache