Домашняя страница LaravelDocs Laravel Docs
  1. Paquetes
  2. Laravel Sail

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 proporciona un excelente punto de partida para construir una aplicación Laravel utilizando PHP, MySQL y Redis sin requerir experiencia previa en Docker.

En su núcleo, Sail es el archivo docker-compose.yml y el script sail que se almacena en la raíz de tu proyecto. El script sail proporciona una interfaz de línea de comandos con métodos convenientes para interactuar con los contenedores Docker definidos por 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, por lo que puedes comenzar a usarlo de inmediato. Para aprender a crear una nueva aplicación Laravel, consulta la documentación de instalación de Laravel para tu sistema operativo. Durante la instalación, se te pedirá que elijas qué servicios compatibles con Sail interactuarán con tu aplicación.

Instalar Sail en Aplicaciones Existentes

Si estás interesado en usar Sail con una aplicación Laravel existente, simplemente puedes instalar Sail usando el gestor de paquetes Composer. Estos pasos asumen que tu entorno de desarrollo local existente te permite instalar las dependencias de Composer:

composer require laravel/sail --dev

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

php artisan sail:install

Finalmente, puedes iniciar Sail. Para seguir aprendiendo cómo usar Sail, continúa leyendo el resto de esta documentación:

./vendor/bin/sail up

Advertencia Si estás utilizando Docker Desktop para Linux, debes usar el contexto de Docker default ejecutando el siguiente comando: docker context use default.

Agregar Servicios Adicionales

Si deseas agregar un servicio adicional a tu instalación existente de Sail, puedes ejecutar el comando Artisan sail:add:

php artisan sail:add

Usar Devcontainers

Si deseas desarrollar dentro de un Devcontainer, puedes proporcionar la opción --devcontainer al comando sail:install. La opción --devcontainer instruirá al comando sail:install para que publique un archivo .devcontainer/devcontainer.json predeterminado en la raíz de tu aplicación:

php artisan sail:install --devcontainer

Configurar un Alias de Shell

De forma predeterminada, los comandos de Sail se invocan mediante 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, es posible que desees configurar un alias de shell que te permita ejecutar los comandos de Sail más fácilmente:

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

Para asegurarte de que esto esté siempre disponible, puedes agregar esto a tu archivo de configuración de la terminal en tu directorio principal, como ~/.zshrc o ~/.bashrc, y luego reiniciar tu terminal.

Una vez que se haya configurado el alias de la terminal, puedes ejecutar comandos Sail simplemente escribiendo sail. El resto de los ejemplos de esta documentación asumirán que has 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 ayudarte a construir aplicaciones Laravel. Cada uno de estos contenedores es una entrada dentro de la configuración services de tu archivo docker-compose.yml. El contenedor laravel.test es el contenedor de aplicación principal que servirá tu aplicación.

Antes de iniciar Sail, debes asegurarte de que no haya otros servidores web o bases de datos ejecutándose en tu computadora local. Para iniciar todos los contenedores Docker definidos en el archivo docker-compose.yml de tu aplicación, debes ejecutar el comando up:

sail up

Para iniciar todos los contenedores Docker en segundo plano, puedes iniciar Sail en modo "desconectado" (detached):

sail up -d

Una vez que los contenedores de la aplicación se han iniciado, puedes acceder al proyecto en tu navegador web en: http://localhost.

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

sail stop

Ejecutar Comandos

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

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

# Running Artisan commands locally...
php artisan queue:work
 
# Running Artisan commands within Laravel Sail...
sail artisan queue:work

Ejecutar Comandos de PHP

Los comandos PHP se pueden ejecutar usando el comando php. Por supuesto, estos comandos se ejecutarán utilizando la versión de PHP que esté configurada para tu aplicación. Para obtener más información sobre las versiones de PHP disponibles para Laravel Sail, consulta la documentación de versiones de PHP:

sail php --version
 
sail php script.php

Ejecutar Comandos de Composer

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

sail composer require laravel/sanctum

Instalar Dependencias de Composer Para Aplicaciones Existentes

Si estás desarrollando una aplicación con un equipo, es posible que no seas quien cree inicialmente la aplicación Laravel. Por lo tanto, ninguno de las dependencias de Composer de la aplicación, incluido Sail, se instalarán después de clonar el repositorio de la aplicación en tu computadora local.

Puedes instalar las dependencias de la aplicación navegando al directorio de la aplicación y ejecutando el siguiente comando. Este comando utiliza 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/php82-composer:latest \
    composer install --ignore-platform-reqs

Cuando uses la imagen laravelsail/phpXX-composer, debes usar la misma versión de PHP que planeas usar para tu aplicación (80, 81 o 82).

Ejecutar Comandos de Artisan

Los comandos Artisan de Laravel se pueden ejecutar usando el comando artisan:

sail artisan queue:work

Ejecutar Comandos de Node / NPM

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

sail node --version
 
sail npm run dev

Si lo deseas, puedes usar Yarn en lugar de NPM:

sail yarn

Interactuar con Bases de Datos

MySQL

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

Además, la primera vez que se inicia el contenedor MySQL, creará dos bases de datos para ti. La primera base de datos se llama con el valor de tu variable de entorno DB_DATABASE y es para tu desarrollo local. La segunda es una base de datos de prueba dedicada llamada testing y asegurará que tus pruebas no interfieran con los datos de tu desarrollo.

Una vez que hayas iniciado tus contenedores, puedes conectarte a la instancia de MySQL dentro de tu aplicación configurando tu variable de entorno DB_HOST en el archivo .env de tu aplicación como mysql.

Para conectarte a la base de datos MySQL de tu aplicación desde tu máquina local, puedes 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 en el puerto 3306 y las credenciales de acceso corresponden a los valores de tus variables de entorno DB_USERNAME y DB_PASSWORD. O bien, puedes conectarte como usuario root, que también utiliza el valor de tu variable de entorno DB_PASSWORD como contraseña.

Redis

El archivo docker-compose.yml de tu aplicación también contiene una entrada para un contenedor Redis. Este contenedor utiliza un volumen Docker para que los datos almacenados en tu base de datos Redis se conserven incluso al detener y reiniciar tus contenedores. Una vez que hayas iniciado tus contenedores, puedes conectarte a la instancia de Redis dentro de tu aplicación configurando tu variable de entorno REDIS_HOST en el archivo .env de tu aplicación como redis.

Para conectarte a la base de datos Redis de tu aplicación desde tu máquina local, puedes 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 en el puerto 6379.

Meilisearch

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

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

Almacenamiento de Archivos

Si planeas usar Amazon S3 para almacenar archivos mientras ejecutas tu aplicación en su entorno de producción, es posible que desees instalar el servicio MinIO al instalar Sail. MinIO proporciona una API compatible con S3 que puedes usar para desarrollar localmente con el controlador de almacenamiento de archivos s3 de Laravel sin crear buckets de almacenamiento de "prueba" en tu entorno de producción de S3. Si eliges instalar MinIO al instalar Sail, se agregará una sección de configuración de MinIO al archivo docker-compose.yml de tu aplicación.

De forma predeterminada, el archivo de configuración filesystems de tu aplicación ya contiene una configuración de disco para el disco s3. Además de usar este disco para interactuar con Amazon S3, puedes usarlo para interactuar con cualquier servicio de almacenamiento de archivos 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 las variables de entorno de tu sistema de archivos debe definirse de la siguiente manera:

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 URL adecuadas al usar MinIO, debes definir la variable de entorno AWS_URL para que coincida con la URL local de tu aplicación e incluya el nombre del bucket en la ruta de la URL:

AWS_URL=http://localhost:9000/local

Puedes 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, mientras que la contraseña predeterminada es password.

Advertencia La generación de URL temporales a través del método temporaryUrl no es compatible cuando se utiliza MinIO.

Ejecutar Pruebas

Laravel proporciona un soporte asombroso para las pruebas desde el principio, y puedes usar el comando test de Sail para ejecutar tus pruebas de características y unitarias. Cualquier opción de CLI que sea aceptada por PHPUnit también se puede pasar al comando test:

sail test
 
sail test --group orders

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

sail artisan test

De forma predeterminada, Sail creará una base de datos dedicada llamada testing para que tus pruebas no interfieran con el estado actual de tu base de datos. En una instalación predeterminada de Laravel, Sail también configurará tu archivo phpunit.xml para usar esta base de datos al ejecutar tus pruebas:

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

Laravel Dusk

Laravel Dusk proporciona una API de automatización y prueba de navegadores expresiva y fácil de usar. Gracias a Sail, puedes ejecutar estas pruebas sin instalar Selenium u otras herramientas en tu computadora local. Para empezar, descomenta el servicio Selenium en el archivo docker-compose.yml de tu aplicación:

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

A continuación, asegúrate de que el servicio laravel.test en el archivo docker-compose.yml de tu aplicación tenga una entrada depends_on para selenium:

depends_on:
    - mysql
    - redis
    - selenium

Finalmente, puedes ejecutar tu suite de pruebas Dusk iniciando Sail y ejecutando el comando dusk:

sail dusk

Selenium en Apple Silicon

Si tu máquina local contiene un chip Apple Silicon, tu 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 tu aplicación durante el desarrollo local y proporciona una interfaz web conveniente para que puedas previsualizar tus mensajes de correo electrónico en tu navegador. Cuando usas Sail, el host predeterminado de Mailpit es mailpit y está disponible a través del puerto 1025:

MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_ENCRYPTION=null

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

CLI del Contenedor

A veces, es posible que desees iniciar una sesión Bash dentro del contenedor de tu aplicación. Puedes usar el comando shell para conectarte al contenedor de tu aplicación, lo que te permite inspeccionar sus archivos y servicios instalados, así como ejecutar comandos de shell arbitrarios dentro del contenedor:

sail shell
 
sail root-shell

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

sail tinker

Versiones de PHP

Actualmente, Sail admite la ejecución de tu aplicación a través de PHP 8.3, 8.2, 8.1 o PHP 8.0. La versión de PHP predeterminada utilizada por Sail es actualmente PHP 8.2. Para cambiar la versión de PHP que se utiliza para ejecutar tu aplicación, debes actualizar la definición de build del contenedor laravel.test en el archivo docker-compose.yml de tu 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, es posible que desees actualizar el nombre de tu imagen para reflejar la versión de PHP que está utilizando tu aplicación. Esta opción también está definida en el archivo docker-compose.yml de tu aplicación:

image: sail-8.1/app

Después de actualizar el archivo docker-compose.yml de tu aplicación, debes reconstruir las imágenes de tus contenedores:

sail build --no-cache
 
sail up

Versiones de Node

Sail instala Node 20 de forma predeterminada. Para cambiar la versión de Node que se instala al compilar tus imágenes, puedes actualizar la definición build.args del servicio laravel.test en el archivo docker-compose.yml de tu aplicación:

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

Después de actualizar el archivo docker-compose.yml de tu aplicación, debes reconstruir las imágenes de tus contenedores:

sail build --no-cache
 
sail up

Compartir Tu Sitio

A veces, es posible que necesites compartir tu sitio públicamente para previsualizar tu sitio para un colega o para probar integraciones de webhook con tu aplicación. Para compartir tu sitio, puedes usar el comando share. Después de ejecutar este comando, se te asignará una URL aleatoria de laravel-sail.site que puedes usar para acceder a tu aplicación:

sail share

Cuando compartas tu sitio a través del comando share, debes configurar los proxies de confianza de tu 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 se debe usar durante la generación de URL:

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

Si deseas elegir el subdominio para tu sitio compartido, puedes proporcionar la opción subdomain al ejecutar el comando share:

sail share --subdomain=my-sail-site

Nota El comando share está alimentado por Expose, un servicio de túneles de código abierto de BeyondCode.

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ás agregar algunas variables al archivo .env de tu aplicación para configurar Xdebug. Para habilitar Xdebug, debes establecer el/los modo(s) apropiado(s) antes de iniciar Sail:

SAIL_XDEBUG_MODE=develop,debug,coverage

Configuración de IP del Host de 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 tu máquina local ejecuta Linux, debes asegurarte de que estás ejecutando Docker Engine 17.06.0+ y Compose 1.16.0+. De lo contrario, deberás definir manualmente esta variable de entorno como se muestra a continuación.

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

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

Una vez que hayas obtenido la dirección IP correcta del host, debes definir la variable SAIL_XDEBUG_CONFIG dentro del archivo .env de tu aplicación:

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

Uso de Xdebug en la CLI

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

# Run an Artisan command without Xdebug...
sail artisan migrate
 
# Run an Artisan command with Xdebug...
sail debug migrate

Uso de Xdebug en el Navegador

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

Si estás utilizando PhpStorm, revisa la documentación de JetBrains sobre depuración sin configuración.

Advertencia Laravel Sail depende de artisan serve para servir tu aplicación. El comando artisan serve solo acepta las variables XDEBUG_CONFIG y XDEBUG_MODE a partir de la versión 8.53.0 de Laravel. Las versiones anteriores de Laravel (8.52.0 y anteriores) no admiten estas variables y no aceptarán conexiones de depuración.

Personalización

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

sail artisan sail:publish

Después de ejecutar este comando, los Dockerfiles y otros archivos de configuración utilizados por Laravel Sail se colocarán en un directorio docker en el directorio raíz de tu aplicación. Después de personalizar tu instalación de Sail, es posible que desees cambiar el nombre de la imagen del contenedor de la aplicación en el archivo docker-compose.yml de tu aplicación. Después de hacerlo, reconstruye los contenedores de tu aplicación usando el comando build. Asignar un nombre único a la imagen de la aplicación es especialmente importante si estás utilizando Sail para desarrollar varias aplicaciones Laravel en una sola máquina:

sail build --no-cache