Configuración

• Introducción
• Configuración del Entorno
  • Tipos de Variables de Entorno
  • Recuperar Configuración del Entorno
  • Determinar el Entorno Actual
  • Encriptar Archivos de Entorno
• Acceder a Valores de Configuración
• Caché de Configuración
• Modo Debug
• Modo Mantenimiento

#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éntase libre de revisar los archivos y familiarizarse con las opciones disponibles.

Estos archivos de configuración le permiten ajustar aspectos como la información de conexión a la base de datos, la configuración del servidor de correo, así como otros valores centrales como la zona horaria de la aplicación y la clave de encriptación.

#Descripción General de la Aplicación

¿Tiene prisa? Puede obtener una visión rápida de la configuración, drivers y entorno de su aplicación mediante el comando Artisan about:

php artisan about

Si solo le interesa una sección específica de la salida del resumen de la aplicación, puede filtrarla 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, puede usar 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 ejecuta la aplicación. Por ejemplo, puede que desee usar un driver de caché distinto localmente que en su 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 su 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 comunes de configuración que pueden variar según si la aplicación se ejecuta 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 usando la función env de Laravel.

Si está desarrollando en equipo, puede que desee seguir incluyendo un archivo .env.example con su aplicación. Al poner valores de marcador de posición en el archivo de configuración de ejemplo, otros desarrolladores en su equipo pueden ver claramente qué variables de entorno son necesarias para ejecutar la aplicación.

#Seguridad del Archivo de Entorno

Su archivo .env no debe ser comprometido en el control de versiones de su aplicación, ya que cada desarrollador o servidor que use su aplicación podría requerir una configuración de entorno diferente. Además, esto representaría un riesgo de seguridad si un intruso accede al repositorio de control de versiones, ya que se expondrían credenciales sensibles.

Sin embargo, es posible encriptar su archivo de entorno usando la encriptación de entorno incorporada en Laravel. Los archivos de entorno encriptados pueden ser almacenados de forma segura en el control de versiones.

#Archivos de Entorno Adicionales

Antes de cargar las variables de entorno de su aplicación, Laravel determina si se ha proporcionado externamente una variable de entorno APP_ENV 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 sus archivos .env normalmente se analizan como strings, por lo que se han creado algunos valores reservados para permitirle devolver un rango más amplio de tipos desde la función env():

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

APP_NAME="My Application"

#Recuperar Configuración del Entorno

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

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

El segundo valor pasado a la función env es el "valor por defecto". 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 su archivo .env. Puede acceder a este valor mediante el método environment en el facade App:

use Illuminate\Support\Facades\App;

$environment = App::environment();

También puede 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 proporcionados:

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

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

#Encriptar Archivos de Entorno

Los archivos de entorno sin encriptar nunca deben almacenarse en el control de versiones. Sin embargo, Laravel le permite encriptar sus archivos de entorno para que puedan añadirse de forma segura al control de versiones junto con el resto de su aplicación.

#Encriptación

Para encriptar un archivo de entorno, puede usar el comando env:encrypt:

php artisan env:encrypt

Al ejecutar el comando env:encrypt, se encriptará su archivo .env y el contenido encriptado se colocará en un archivo .env.encrypted. La clave de desencriptación se muestra en la salida del comando y debe almacenarse en un gestor de contraseñas seguro. Si desea proporcionar su propia clave de encriptación, puede usar la opción --key al invocar el comando:

php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

Si su aplicación tiene múltiples archivos de entorno, como .env y .env.staging, puede especificar cuál archivo de entorno debe ser encriptado proporcionando el nombre del entorno mediante la opción --env:

php artisan env:encrypt --env=staging

#Desencriptación

Para desencriptar un archivo de entorno, puede usar el comando env:decrypt. Este comando requiere una clave de desencriptación, que Laravel obtendrá de la variable de entorno LARAVEL_ENV_ENCRYPTION_KEY:

php artisan env:decrypt

O bien, la clave puede proporcionarse directamente al comando mediante la opción --key:

php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

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

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

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

Si su aplicación tiene múltiples archivos de entorno, como .env y .env.staging, puede especificar cuál archivo de entorno debe ser desencriptado proporcionando el nombre del entorno mediante la opción --env:

php artisan env:decrypt --env=staging

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

php artisan env:decrypt --force

#Acceder a Valores de Configuración

Puede acceder fácilmente a sus valores de configuración usando el facade Config o la función global config desde cualquier parte de su aplicación. Los valores de configuración pueden accederse usando la sintaxis de "puntos", que incluye el nombre del archivo y la opción que desea acceder. También puede especificar un valor por defecto 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 por defecto si la opción de configuración no existe...
$value = config('app.timezone', 'Asia/Seoul');

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

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

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

#Caché de Configuración

Para acelerar su aplicación, debería cachear todos sus archivos de configuración en un solo archivo usando el comando Artisan config:cache. Esto combinará todas las opciones de configuración de su aplicación en un solo archivo que puede ser cargado rápidamente por el framework.

Normalmente debería ejecutar el comando php artisan config:cache como parte de su proceso de despliegue en producción. No debería ejecutarse durante el desarrollo local, ya que las opciones de configuración suelen necesitar cambios frecuentes durante el desarrollo de la aplicación.

Una vez que la configuración ha sido cacheada, el archivo .env de su aplicación no será cargado por 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, debe asegurarse de llamar a la función env solo desde dentro de los archivos de configuración (config) de su aplicación. Puede ver muchos ejemplos de esto revisando los archivos de configuración predeterminados de Laravel. Los valores de configuración pueden accederse desde cualquier parte de su aplicación usando la función config descrita arriba.

El comando config:clear puede usarse para limpiar la configuración cacheada:

php artisan config:clear

#Modo Debug

La opción debug en su 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 su archivo .env.

#Modo Mantenimiento

Cuando su aplicación está en modo mantenimiento, se mostrará una vista personalizada para todas las solicitudes a su aplicación. Esto facilita "deshabilitar" su aplicación mientras se actualiza o realiza mantenimiento. Una verificación de modo mantenimiento está incluida en el stack de middleware predeterminado de su aplicación. Si la aplicación está en modo mantenimiento, se lanzará una instancia de Symfony\Component\HttpKernel\Exception\HttpException con un código de estado 503.

Para habilitar el modo mantenimiento, ejecute el comando Artisan down:

php artisan down

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

php artisan down --refresh=15

También puede 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

#Omitir el Modo Mantenimiento

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

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

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

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

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

php artisan down --with-secret

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

#Pre-renderizar la Vista de Modo Mantenimiento

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

Por esta razón, Laravel le permite pre-renderizar una vista de modo mantenimiento que será devuelta al inicio del ciclo de la solicitud. Esta vista se renderiza antes de que se carguen las dependencias de su aplicación. Puede pre-renderizar una plantilla de su elección usando la opción render del comando down:

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

#Redirigir Solicitudes en Modo Mantenimiento

Mientras esté en modo mantenimiento, Laravel mostrará la vista de modo mantenimiento para todas las URLs de la aplicación a las que el usuario intente acceder. Si lo desea, puede indicar a Laravel que redirija todas las solicitudes a una URL específica. Esto puede lograrse usando la opción redirect. Por ejemplo, puede querer redirigir todas las solicitudes a la URI /:

php artisan down --redirect=/

#Deshabilitar el Modo Mantenimiento

Para deshabilitar el modo mantenimiento, use el comando up:

php artisan up

#Modo Mantenimiento y Colas

Mientras su aplicación esté en modo mantenimiento, no se procesarán trabajos en cola. Los trabajos continuarán procesándose normalmente una vez que la aplicación salga del modo mantenimiento.

#Alternativas al Modo Mantenimiento

Dado que el modo mantenimiento requiere que su aplicación tenga varios segundos de inactividad, considere alternativas como Laravel Vapor y Envoyer para lograr despliegues sin tiempo de inactividad con Laravel.