Домашняя страница LaravelDocs Laravel Docs
  1. Primeros pasos
  2. Configuración

Introducción

Todos los archivos de configuración del 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 del servidor de correo, así como varios otros valores de configuración principales, como la zona horaria de tu aplicación y la clave de cifrado.

Descripción general de la aplicación

¿Con prisa? Puedes obtener una visión rápida de la configuración, controladores y entorno de tu aplicación mediante el comando Artisan about:

php artisan about

Si solo te interesa una sección específica de la salida de la descripción general de la aplicación, puedes filtrar esa sección utilizando la opción --only:

php artisan about --only=environment

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

php artisan config:show database

Configuración del entorno

A menudo es útil tener diferentes valores de configuración según el entorno donde se está ejecutando la aplicación. Por ejemplo, es posible que desees utilizar 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 se recuperan luego desde varios archivos de configuración de Laravel dentro del directorio config utilizando la función env de Laravel.

Si estás desarrollando con un equipo, es posible que desees seguir incluyendo un 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 en tu equipo pueden ver claramente qué variables de entorno son necesarias para ejecutar tu aplicación.

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

Seguridad del archivo de entorno

Tu archivo .env no debe ser confirmado en el control de versiones de tu aplicación, ya que cada desarrollador o servidor que utilice tu aplicación puede 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 se expondrían credenciales sensibles.

Sin embargo, es posible cifrar tu archivo de entorno utilizando la encriptación de entorno integrada de Laravel. Los archivos de entorno cifrados se pueden colocar de forma 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 externamente una variable de entorno APP_ENV o si se ha especificado el argumento de la 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 generalmente se analizan como cadenas, por lo que se han creado algunos valores reservados para permitir que devuelvas una gama más amplia de tipos desde la función env() de Laravel:

.env Value env() Value
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"

Recuperar configuración del entorno

Todas las variables enumeradas en el archivo .env se cargarán en el superglobal $_ENV de PHP cuando tu aplicación reciba una solicitud. Sin embargo, puedes utilizar 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 utilizando 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.

Determinar el entorno actual

El entorno actual de la aplicación se determina mediante la variable APP_ENV de tu archivo .env. Puedes acceder a este valor mediante el 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 alguno de los valores dados:

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

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

Cifrar archivos de entorno

Nunca se deben almacenar archivos de entorno sin cifrar en el control de versiones. Sin embargo, Laravel te permite cifrar tus archivos de entorno para que puedan agregarse de forma segura al control de versiones junto con el resto de tu aplicación.

Cifrado

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

php artisan env:encrypt

Al ejecutar el comando env:encrypt, se cifrará tu archivo .env y colocará el contenido cifrado en un archivo .env.encrypted. La clave de descifrado se muestra en la salida del comando y debe almacenarse 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

Nota La longitud de la clave proporcionada debe coincidir con la longitud de la clave requerida por el cifrado de encriptación que se está utilizando. De forma predeterminada, Laravel utilizará el cifrado AES-256-CBC, que requiere una clave de 32 caracteres. Puedes utilizar cualquier cifrado admitido por el encriptador de Laravel pasando la opción --cipher al invocar el comando.

Si tu aplicación tiene varios archivos de entorno, como .env y .env.staging, puedes especificar el archivo de entorno que se debe cifrar proporcionando el nombre del entorno mediante la opción --env:

php artisan env:encrypt --env=staging

Descifrado

Para descifrar un archivo de entorno, puedes utilizar 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 se puede proporcionar directamente al comando mediante 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 se puede proporcionar al comando env:decrypt para utilizar un cifrado de encriptación personalizado:

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

Si tu aplicación tiene varios archivos de entorno, como .env y .env.staging, puedes especificar el archivo de entorno que se debe descifrar proporcionando el nombre del entorno mediante 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

Acceder a los valores de configuración

Puedes acceder fácilmente a tus valores de configuración utilizando la función global config desde cualquier parte de tu aplicación. Los valores de configuración se pueden acceder utilizando la sintaxis "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:

$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, pasa un array a la función config:

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

Caché de configuración

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

Por lo general, debes ejecutar el comando php artisan config:cache como parte de tu proceso de implementación en producción. El comando no debe ejecutarse durante el desarrollo local, ya que es probable que las opciones de configuración deban cambiarse con frecuencia durante el desarrollo de tu aplicación.

Una vez que la configuración se haya almacenado en caché, el archivo .env de tu aplicación no se cargará en el framework durante las solicitudes o comandos Artisan; por lo tanto, la función env solo devolverá variables de entorno externas a nivel de sistema.

Por esta razón, debes asegurarte de llamar a la función env solo desde los archivos de configuración (config) de tu aplicación. Puedes ver muchos ejemplos de esto examinando los archivos de configuración predeterminados de Laravel. Los valores de configuración se pueden acceder desde cualquier parte de tu aplicación utilizando la función config descrita anteriormente.

El comando config:clear se puede utilizar para purgar la configuración almacenada en caché:

php artisan config:clear

Advertencia Si ejecutas el comando config:cache durante tu proceso de implementación, asegúrate de que solo estás llamando a la función env desde tus archivos de configuración. Una vez que la configuración se haya almacenado en caché, el archivo .env no se cargará; por lo tanto, la función env solo devolverá variables de entorno externas a nivel de sistema.

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. De forma predeterminada, esta opción está configurada para respetar el valor de la variable de entorno APP_DEBUG, que se almacena en tu archivo .env.

Advertencia Para el desarrollo local, debes establecer la variable de entorno APP_DEBUG en true. En tu entorno de producción, este valor siempre debe ser false. Si la variable se establece 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 "desactivar" tu aplicación mientras se actualiza o cuando se realiza mantenimiento. Se incluye una verificación de modo de mantenimiento 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 503.

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

php artisan down

Si deseas que se envíe el encabezado Refresh 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 para que actualice automáticamente la página después del número especificado de segundos:

php artisan down --refresh=15

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

php artisan down --retry=60

Evitar el modo de mantenimiento

Para permitir que el modo de mantenimiento se omita mediante 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 ir 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

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

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

Pre-renderizado de la vista del modo de mantenimiento

Si utilizas el comando php artisan down durante la implementación, tus usuarios aún pueden encontrar ocasionalmente errores 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 utilizando el motor de plantillas.

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

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

Redirigir solicitudes del modo de mantenimiento

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

php artisan down --redirect=/

Desactivar el modo de mantenimiento

Para desactivar el modo de mantenimiento, utiliza el comando up:

php artisan up

Nota 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 una implementación sin tiempo de inactividad con Laravel.