Configuration

Introducción

Los archivos de configuración de Laravel están en el directorio config y permiten configurar aspectos esenciales de la aplicación, como la conexión de base de datos, información del servidor de correo, zona horaria, clave de encriptación, entre otros. Puedes ver un resumen de la configuración de tu aplicación con :

php artisan about

// Permite mostrar solamente alguna seccion
php artisan about --only=environment

// Para conocer alguna configuración con mas detalle
php artisan config:show database

Configuración del Entorno

Laravel usa la librería DotEnv para gestionar variables de entorno, permitiendo diferentes valores de configuración según el entorno (desarrollo, producción, etc.). Estas variables se definen en el archivo .env. Es importante no incluir este archivo en git para proteger información sensible, aunque se puede encriptar usando el comando.

php artisan env:encrypt

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

Tipos de Variables de Entorno

Por defecto, todas las variables en .env se interpretan como cadenas de texto, pero existen valores reservados (true, false, empty, null) para devolver tipos específicos como booleanos, cadenas vacías o null.

Acceder a la Configuración

Todas las variables listadas en el archivo .env se cargarán en la variable global $_ENV de PHP cuando tu aplicación reciba una solicitud. Sin embargo, puedes usar la función env para obtener los 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.

Para acceder a valores de configuración, se usa la función env en los archivos de configuración y la función config en el resto del código. Laravel permite acceder a configuraciones usando la sintaxis “dot” (ej., app.timezone).

'debug' => env('APP_DEBUG', false),
// El segundo parametro es el valor por defecto

Determinar el entorno actual

El entorno actual es determinado a través de la variable APP_ENV del .env . Puedes acceder a su valor a través de la facade App :

use Illuminate\Support\Facades\App;
 
$environment = App::environment();

Puedes incluso pasar un string o un array para determinar el entorno:

if (App::environment('local')) {
    // The environment is local
}
 
if (App::environment(['local', 'staging'])) {
    // The environment is either local OR staging...
}

ℹ️ Esta variable puede ser sobreescrita por una variable APP_ENV a nivel del servidor

Encriptar el .env

Dado que el .env no se debe subir a repositorios remotos, laravel permite encriptar el .env para permitir que se suba con el resto del código.

Encriptación

Para encriptar, se puede usar:

php artisan env:encrypt

php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF
// Proveer tu propia key de encriptación

php artisan env:encrypt --cyper=AES-256-CBC
// indicar el cifrado a utilizar

php artisan env:encrypt --env=staging
// indicar el nombre del archivo .env a encriptar

Correr este comando encriptará el .env y guardará el contenido en un archivo .env.encrypted

La clave para desencriptar este archivo se mostrará en la salida del comando y deberá ser incluida en un manejador de contraseñas (password manager).

ℹ️ La longitud de la key debe coincidir con la longitud requerida del cifrado de encriptación usado. Por defecto laravel utiliza AES-256-CBC que requiere una key de 32 caracteres.

Puedes usar cualquier cifrado usando la opción -- cypher cuando invoques el comando.

Desencriptación

Para desencriptar puedes usar este comando, esto desencriptará el archivo .env.encrypted

php artisan env:decrypt
// la key sera obtenida de la variable de entorno LARAVEL_ENV_ENCRIPTION_KEY 

php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF
// proveer la key

php artisan env:decrypt --key=qUWuNRdfuImXcKxZ --cipher=AES-128-CBC
// indicar el cifrado de desencriptación

php artisan env:decrypt --env=staging
// indicar el nombre del archivo .env a desencriptar (.env.staging)

php artisan env:decrypt --force
// Sobreescribir el .env actual

Publicar configuración

La mayoria de la cofiguración de laravel esta ya publicada en el directorio config ,pero algunos archivos de configuración como cors.php y view.php no son públicados por defecto, dado que la mayoría de aplicaciones no necesitan modificarlos. Puedes usar los siguientes comandos para publicar archibos que no estan publicados por defecto:

php artisan config:publish
 
php artisan config:publish --all

Debug mode

La opción de 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 establecer la variable de entorno APP_DEBUG en true. En tu entorno de producción, este valor siempre debe ser false. Si la variable está establecida en true en producción, corres el riesgo de exponer valores de configuración sensibles a los usuarios finales de tu aplicación.

Acceder a los valores de config

Puedes acceder a los archivos que están en config de manera facil usando la facade Config o la función global config . Para acceder a un valor en concreto del config se utiliza el . Incluyendo el nombre del archivo de configuración y el nombre de los elementos anidados hasta llegar al valor

use Illuminate\Support\Facades\Config;
 
$value = Config::get('app.timezone');
 
$value = config('app.timezone');
 
// Retrieve a default value if the configuration value does not exist...
$value = config('app.timezone', 'Asia/Seoul');

Si se necesita añadir un valor en tiempo de ejecución se puede hacer invocando la fachada Config con el método set o pasando un array a la función config

Config::set('app.timezone', 'America/Chicago');
 
config(['app.timezone' => 'America/Chicago']);

La facade Config incluye incluso tipado para los métodos de recuperación ayudando con el análisis estático. Si el valor de la configuración no coincide con el esperado, una excepción será lanzada.

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

Caching de Configuración

Para optimizar el rendimiento, es posible cachear la configuración usando php artisan config:cache, que consolida las configuraciones en un único archivo para una carga rápida en producción. Durante el desarrollo local, se recomienda no cachear la configuración, ya que puede cambiar frecuentemente.

Una vez la configuración ha sido cacheada, el archivo .env no sera cargado mas por el framework durante las peticiones o los comandos Artisan. Por lo tanto, las función env solamente devolverá variables de entorno externas a nivel de sistema.

Por esta razón deberás asegurarte de que solo llamas a la función env dentro de los archivos config

Para borrar la cache de la configuración ejecuta:

php artisan config:clear

❗❗Si ejecutas el comando config:cache durante el proceso de despliegue, debes asegurarte de que solo estás llamando a la función env dentro de tus archivos de configuración. Una vez que la configuración ha sido almacenada en caché, el archivo .env no se cargará; por lo tanto, la función env solo devolverá las variables de entorno externas a nivel de sistema.

Publicación de Configuración

No todos los archivos de configuración están publicados en config por defecto, pero se pueden publicar usando php artisan config:publish o php artisan config:publish --all.

Modo de Debug

El modo de debug se controla con la variable APP_DEBUG en .env. En desarrollo debe estar en true, pero en producción debe ser false para evitar la exposición de información sensible.

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 estás realizando mantenimiento. Una verificación del modo de mantenimiento está incluida en la pila de middleware por defecto 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 HTTP Refresh con todas las respuestas en 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 HTTP Retry-After, aunque los navegadores generalmente ignoran este encabezado:

php artisan down --retry=60

Ignorar el Modo de Mantenimiento

Para permitir que el modo de mantenimiento sea ignorado utilizando un secret token, 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 coincide 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 por ti, puedes usar la opción with-secret. El secreto se te 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 se haya emitido la cookie a tu navegador, podrás navegar por la aplicación normalmente, como si no estuviera en modo de mantenimiento.

❗❗Tu secret key del modo de mantenimiento debe consistir normalmente de caracteres alfanuméricos y, opcionalmente, guiones. Debes evitar usar caracteres que tengan un significado especial en las URL, como ? o &.

Modo mantenimiento en múltiples servidores

Por defecto, Laravel utiliza un sistema basado en archivos para determinar si la aplicación está en modo de mantenimiento, lo que requiere ejecutar el comando php artisan down en cada servidor.

Laravel también permite un método basado en caché que solo requiere ejecutar el comando en un servidor. Para utilizar este método, modifica la configuración “driver” en el archivo config/app.php a cache y selecciona un almacén de caché accesible por todos los servidores, asegurando que el estado del modo de mantenimiento se mantenga de manera consistente.

'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 encontrarse ocasionalmente con errores si acceden a la aplicación mientras se actualizan tus dependencias de Composer u otros componentes de infraestructura. Esto ocurre porque una parte significativa del framework de Laravel debe iniciarse para determinar qué tu aplicación está en modo de mantenimiento y renderizar la vista de modo de mantenimiento utilizando el motor de plantillas.

Por esta razón, Laravel te permite pre-renderizar una vista de modo de mantenimiento que se devolverá al principio del ciclo de solicitud. Esta vista se renderiza antes de que se carguen 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"

Redirigir Solicitudes en Modo de Mantenimiento

Mientras estés en modo de mantenimiento, Laravel mostrará la vista de modo de mantenimiento para todas las URL de la aplicación que el usuario intente acceder. Si lo deseas, puedes instruir a Laravel para redirigir 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 customizar la plantilla del modo mantenimiento en resources/views/errors/503.blade.php.

Mantenimiento y Queues

Durante el mantenimiento, los queues no procesarán jobs(trabajos). Los trabajos se seguirán manejando una vez la aplicación salga del modo mantenimiento.

Alternativas al modo mantenimiento

Dado que el modo mantenimiento require que tu aplicación este caida durante varios segundos, considera alternativas como Laravel Vapor o Envoyer para conseguir despliegues con 0 segundos de caída