Introducción

Todos los archivos de configuración para el framework Laravel se almacenan en el directorio config Cada opción está documentada, así que siéntete libre de revisar los archivos y familiarizarte con las opciones disponibles.

Estos archivos de configuración te permiten configurar cosas como la información de conexión a tu base de datos, la información de tu servidor de correo, así como varios otros valores de configuración central, como la zona horaria de tu aplicación y la clave de cifrado.

El Comando about

Laravel puede mostrar una visión general de la configuración de tu aplicación, controladores y entorno a través del comando about de Artisan.

php artisan about

Si solo estás interesado en una sección particular de la salida de la visión general de la aplicación, puedes
filtrar esa sección usando la opción --only:

php artisan about --only=environment

O, para explorar en detalle los valores de un archivo de configuración específico, puedes usar el comando
config:show de Artisan:

php artisan config:show database

Configuración del Entorno

A menudo es útil tener diferentes valores de configuración según el entorno en el que se esté ejecutando la
aplicación. Por ejemplo, es posible que desees usar un controlador de caché diferente localmente que en tu
servidor de producción.

Para facilitar esto, Laravel utiliza la biblioteca PHP DotEnv. En una instalación nueva de Laravel,
el directorio raíz de tu aplicación contendrá un archivo .env.example que define muchas variables
de entorno comunes. Durante el proceso de instalación de Laravel, este archivo se copiará automáticamente a
.env.

El archivo .env predeterminado de Laravel contiene algunos valores de configuración comunes que
pueden diferir según si tu aplicación se está ejecutando localmente o en un servidor web de producción. Estos
valores son leídos por los archivos de configuración dentro del directorio config usando la función
env de Laravel.

Si estás desarrollando con un equipo, es posible que desees seguir incluyendo y actualizando el archivo
.env.example con tu aplicación. Al poner valores de marcador de posición en el archivo de
configuración de ejemplo, otros desarrolladores de tu equipo pueden ver claramente qué variables de entorno son
necesarias para ejecutar tu aplicación.

Cualquier variable en tu archivo .env puede ser sobrescrita por variables de entorno externas, como
variables de entorno a nivel de servidor o de sistema.

Seguridad del Archivo de Entorno

Tu archivo .env no debe ser comprometido en el control de versiones de tu aplicación, ya que cada
desarrollador/servidor que use tu aplicación podría requerir una configuración de entorno diferente. Además,
esto sería un riesgo de seguridad en caso de que un intruso obtenga acceso a tu repositorio de control de
versiones, ya que cualquier credencial sensible se expondría.

Sin embargo, es posible cifrar tu archivo de entorno usando el cifrado de entorno incorporado de Laravel. Los
archivos de entorno cifrados pueden ser colocados de manera segura en el control de versiones.

Archivos de Entorno Adicionales

Antes de cargar las variables de entorno de tu aplicación, Laravel determina si se ha proporcionado una variable
de entorno APP_ENV externamente o si se ha especificado el argumento CLI --env. Si es
así, Laravel intentará cargar un archivo .env.[APP_ENV] si existe. Si no existe, se cargará el
archivo .env predeterminado.

Tipos de Variables de Entorno

Todas las variables en tus archivos .env son típicamente analizadas como cadenas, por lo que se han
creado algunos valores reservados para permitirte devolver una gama más amplia de tipos desde la función
env():

Valor en .env	Valor en env()
true	(bool) true
(true)	(bool) true
false	(bool) false
(false)	(bool) false
empty	(string) »
(empty)	(string) »
null	(null) null
(null)	(null) null

Si necesitas definir una variable de entorno con un valor que contenga espacios, puedes hacerlo encerrando el
valor entre comillas dobles:

APP_NAME="My Application"

Todas las variables listadas en el archivo .env se cargarán en la superglobal PHP $_ENV
cuando tu aplicación reciba una solicitud. Sin embargo, puedes usar la función env para recuperar
valores de estas variables en tus archivos de configuración. De hecho, si revisas los archivos de configuración de
Laravel, notarás que muchas de las opciones ya están usando esta función:

'debug' => env('APP_DEBUG', false),

El segundo valor pasado a la función env es el «valor predeterminado». Este valor se devolverá si no
existe una variable de entorno para la clave dada.

Determinando el Entorno Actual

El entorno actual de la aplicación se determina a través de la variable APP_ENV de tu archivo
.env. Puedes acceder a este valor a través del método environment en la fachada
App:

use Illuminate\Support\Facades\App;

$environment = App::environment();

También puedes pasar argumentos al método environment para determinar si el entorno coincide con un
valor dado. El método devolverá true si el entorno coincide con cualquiera de los valores dados:

if (App::environment('local')) {
    // El entorno es local
}

if (App::environment(['local', 'staging'])) {
    // El entorno es local O staging...
}

La detección del entorno actual de la aplicación puede ser anulada definiendo una variable de entorno
APP_ENV a nivel de servidor.

Cifrando Archivos de Entorno

Los archivos de entorno sin cifrar nunca deben almacenarse en el control de versiones. Sin embargo, Laravel te
permite cifrar tus archivos de entorno para que puedan ser añadidos de manera segura al control de versiones junto
con el resto de tu aplicación.

Cifrado

Para cifrar un archivo de entorno, puedes usar el comando env:encrypt:

php artisan env:encrypt

Ejecutar el comando env:encrypt cifrará tu archivo .env y colocará el contenido cifrado en
un archivo .env.encrypted. La clave de descifrado se presenta en la salida del comando y debe ser
almacenada en un administrador de contraseñas seguro. Si deseas proporcionar tu propia clave de cifrado, puedes usar
la opción --key al invocar el comando:

php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

La longitud de la clave proporcionada debe coincidir con la longitud de la clave requerida por el cifrado que se está
utilizando. Por defecto, Laravel usará el cifrado AES-256-CBC que requiere una clave de 32 caracteres.
Puedes usar cualquier cifrado compatible con el encriptador de Laravel pasando la opción --cipher al
invocar el comando.

Si tu aplicación tiene múltiples archivos de entorno, como .env y .env.staging, puedes
especificar el archivo de entorno que debe cifrarse proporcionando el nombre del entorno a través de la opción
--env:

php artisan env:encrypt --env=staging

Descifrado

Para descifrar un archivo de entorno, puedes usar el comando env:decrypt. Este comando requiere una
clave de descifrado, que Laravel recuperará de la variable de entorno LARAVEL_ENV_ENCRYPTION_KEY:

php artisan env:decrypt

O, la clave puede ser proporcionada directamente al comando a través de la opción --key:

php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

Cuando se invoca el comando env:decrypt, Laravel descifrará el contenido del archivo
.env.encrypted y colocará el contenido descifrado en el archivo .env.

La opción --cipher puede ser proporcionada al comando env:decrypt para usar un cifrado
personalizado:

php artisan env:decrypt --key=qUWuNRdfuImXcKxZ --cipher=AES-128-CBC

Si tu aplicación tiene múltiples archivos de entorno, como .env y .env.staging, puedes
especificar el archivo de entorno que debe descifrarse proporcionando el nombre del entorno a través de la opción
--env:

php artisan env:decrypt --env=staging

Para sobrescribir un archivo de entorno existente, puedes proporcionar la opción --force al comando
env:decrypt:

php artisan env:decrypt --force

Accediendo a los Valores de Configuración

Puedes acceder fácilmente a tus valores de configuración usando la fachada Config o la función global
config desde cualquier lugar de tu aplicación. Los valores de configuración pueden ser accedidos usando
la sintaxis de «punto», que incluye el nombre del archivo y la opción que deseas acceder. También se puede
especificar un valor predeterminado que se devolverá si la opción de configuración no existe:

use Illuminate\Support\Facades\Config;

$value = Config::get('app.timezone');

$value = config('app.timezone');

// Recuperar un valor predeterminado si el valor de configuración no existe...
$value = config('app.timezone', 'Asia/Seoul');

Para establecer valores de configuración en tiempo de ejecución, puedes invocar el método set de la
fachada Config o pasar un array a la función config:

Config::set('app.timezone', 'America/Chicago');

config(['app.timezone' => 'America/Chicago']);

Para ayudar con el análisis estático, la fachada Config también proporciona métodos de recuperación de
configuración tipados. Si el valor de configuración recuperado no coincide con el tipo esperado, se lanzará una
excepción:

Config::string('config-key');
Config::integer('config-key');
Config::float('config-key');
Config::boolean('config-key');
Config::array('config-key');

Cache de Configuración

Para darle un impulso de velocidad a tu aplicación, debes cachear todos tus archivos de configuración en un solo
archivo usando el comando config:cache de Artisan. Esto combinará todas las opciones de configuración
de tu aplicación en un solo archivo que puede ser cargado rápidamente por el framework.

Normalmente, debes ejecutar el comando php artisan config:cache como parte de tu proceso de despliegue
en producción. El comando no debe ejecutarse durante el desarrollo local, ya que las opciones de configuración
necesitarán cambiarse frecuentemente durante el desarrollo de tu aplicación.

Una vez que la configuración ha sido cacheada, el archivo .env de tu aplicación no será cargado por el
framework durante las solicitudes o comandos de Artisan; por lo tanto, la función env solo devolverá
variables de entorno externas a nivel del sistema.

Por esta razón, debes asegurarte de que solo estás llamando a la función env desde dentro de los
archivos de configuración de tu aplicación. Puedes ver muchos ejemplos de esto examinando los archivos de
configuración predeterminados de Laravel. Los valores de configuración pueden ser accedidos desde cualquier lugar de
tu aplicación usando la función config descrita anteriormente.

El comando config:clear puede ser usado para purgar la configuración cacheada:

php artisan config:clear

Si ejecutas el comando config:cache durante tu proceso de despliegue, debes asegurarte de que solo estás
llamando a la función env desde dentro de tus archivos de configuración. Una vez que la configuración
ha sido cacheada, el archivo .env no será cargado; por lo tanto, la función env solo
devolverá variables de entorno externas a nivel del sistema.

Publicación de Configuración

La mayoría de los archivos de configuración de Laravel ya están publicados en el directorio config de tu
aplicación; sin embargo, ciertos archivos de configuración como cors.php y view.php no se
publican por defecto, ya que la mayoría de las aplicaciones nunca necesitarán modificarlos.

Sin embargo, puedes usar el comando config:publish de Artisan para publicar cualquier archivo de
configuración que no esté publicado por defecto:

php artisan config:publish

php artisan config:publish --all

Modo de Depuración

La opción debug en tu archivo de configuración config/app.php determina cuánta información
sobre un error se muestra realmente al usuario. Por defecto, esta opción está configurada para respetar el valor de
la variable de entorno APP_DEBUG, que se almacena en tu archivo .env.

Para el desarrollo local, debes configurar la variable de entorno APP_DEBUG en true. En tu
entorno de producción, este valor siempre debe ser false. Si la variable está configurada en
true en producción, corres el riesgo de exponer valores de configuración sensibles a los usuarios
finales de tu aplicación.

Modo de Mantenimiento

Cuando tu aplicación está en modo de mantenimiento, se mostrará una vista personalizada para todas las solicitudes a
tu aplicación. Esto facilita «deshabilitar» tu aplicación mientras se está actualizando o cuando estás realizando
mantenimiento. Una verificación del modo de mantenimiento está incluida en la pila de middleware predeterminada de
tu aplicación. Si la aplicación está en modo de mantenimiento, se lanzará una instancia de
Symfony\Component\HttpKernel\Exception\HttpException con un código de estado de 503.

Para habilitar el modo de mantenimiento, ejecuta el comando down de Artisan:

php artisan down

Si deseas que el encabezado HTTP Refresh se envíe con todas las respuestas del modo de mantenimiento,
puedes proporcionar la opción refresh al invocar el comando down. El encabezado
Refresh instruirá al navegador a actualizar automáticamente la página después del número de segundos
especificado:

php artisan down --refresh=15

También puedes proporcionar una opción retry al comando down, que se establecerá como el
valor del encabezado HTTP Retry-After, aunque los navegadores generalmente ignoran este encabezado:

php artisan down --retry=60

Omitiendo el Modo de Mantenimiento

Para permitir que el modo de mantenimiento sea omitido usando un token secreto, puedes usar la opción
secret para especificar un token de omisión del modo de mantenimiento:

php artisan down --secret="1630542a-246b-4b66-afa1-dd72a4c43515"

Después de colocar la aplicación en modo de mantenimiento, puedes navegar a la URL de la aplicación que coincida con
este token y Laravel emitirá una cookie de omisión del modo de mantenimiento a tu navegador:

https://example.com/1630542a-246b-4b66-afa1-dd72a4c43515

Si deseas que Laravel genere el token secreto por ti, puedes usar la opción with-secret. El secreto se
mostrará una vez que la aplicación esté en modo de mantenimiento:

php artisan down --with-secret

Al acceder a esta ruta oculta, serás redirigido a la ruta / de la aplicación. Una vez que la cookie ha
sido emitida a tu navegador, podrás navegar por la aplicación normalmente como si no estuviera en modo de
mantenimiento.

Tu secreto del modo de mantenimiento debe consistir típicamente en caracteres alfanuméricos y, opcionalmente,
guiones. Debes evitar usar caracteres que tengan un significado especial en las URLs como ? o
&.

Modo de Mantenimiento en Múltiples Servidores

Por defecto, Laravel determina si tu aplicación está en modo de mantenimiento usando un sistema basado en archivos.
Esto significa que para activar el modo de mantenimiento, el comando php artisan down debe ejecutarse
en cada servidor que aloje tu aplicación.

Alternativamente, Laravel ofrece un método basado en cache para manejar el modo de mantenimiento. Este método
requiere ejecutar el comando php artisan down en solo un servidor. Para usar este enfoque, modifica la
configuración del «driver» en el archivo config/app.php de tu aplicación a cache. Luego,
selecciona un almacén de cache que sea accesible por todos tus servidores. Esto asegura que el estado del modo de
mantenimiento se mantenga consistentemente en cada servidor:

'maintenance' => [
    'driver' => 'cache',
    'store' => 'database',
],

Pre-Renderizando la Vista del Modo de Mantenimiento

Si utilizas el comando php artisan down durante el despliegue, tus usuarios aún pueden encontrar errores
ocasionalmente si acceden a la aplicación mientras tus dependencias de Composer u otros componentes de
infraestructura se están actualizando. Esto ocurre porque una parte significativa del framework Laravel debe
iniciarse para determinar que tu aplicación está en modo de mantenimiento y renderizar la vista del modo de
mantenimiento usando el motor de plantillas.

Por esta razón, Laravel te permite pre-renderizar una vista del modo de mantenimiento que se devolverá al comienzo
del ciclo de solicitud. Esta vista se renderiza antes de que se hayan cargado las dependencias de tu aplicación.
Puedes pre-renderizar una plantilla de tu elección usando la opción render del comando
down:

php artisan down --render="errors::503"

Redirigiendo Solicitudes en Modo de Mantenimiento

Mientras está en modo de mantenimiento, Laravel mostrará la vista del modo de mantenimiento para todas las URLs de la
aplicación que el usuario intente acceder. Si lo deseas, puedes instruir a Laravel para que redirija todas las
solicitudes a una URL específica. Esto se puede lograr usando la opción redirect. Por ejemplo, puedes
desear redirigir todas las solicitudes a la URI /:

php artisan down --redirect=/

Deshabilitando el Modo de Mantenimiento

Para deshabilitar el modo de mantenimiento, usa el comando up:

php artisan up

Puedes personalizar la plantilla predeterminada del modo de mantenimiento definiendo tu propia plantilla en
resources/views/errors/503.blade.php.

Modo de Mantenimiento y Colas

Mientras tu aplicación está en modo de mantenimiento, no se manejarán trabajos en cola. Los trabajos continuarán
manejándose normalmente una vez que la aplicación salga del modo de mantenimiento.

Alternativas al Modo de Mantenimiento

Dado que el modo de mantenimiento requiere que tu aplicación tenga varios segundos de inactividad, considera
alternativas como Laravel Vapor y Envoyer para lograr un despliegue sin tiempo de inactividad con Laravel.