Configuration

# Introducción

Todos los archivos de configuración de la estructura de Laravel están almacenados en el directorio de configuración. Cada opción está documentada, así que siéntase libre de revisar los archivos y familiarizarse con las opciones disponibles.

# Configuración del entorno

A menudo es útil tener diferentes valores de configuración basados en el entorno en el que se ejecuta la aplicación. Por ejemplo, tal vez desee utilizar un controlador de caché diferente localmente que el que utiliza en su servidor de producción.

Para que esto sea pan comido, Laravel utiliza la biblioteca DotEnv PHP de Vance Lucas. En una instalación fresca de Laravel, el directorio raíz de su aplicación contendrá un archivo .env.example. Si instalas Laravel a través de Composer, este archivo se copiará automáticamente a .env. De lo contrario, deberías copiar el archivo manualmente.

Su archivo .env no debería estar comprometido con el control de código fuente de su aplicación, ya que cada desarrollador/servidor que utilice su aplicación podría requerir una configuración de entorno diferente. Además, esto sería un riesgo de seguridad en el caso de que un intruso acceda a su repositorio de control de fuentes, ya que cualquier credencial sensible quedaría expuesta.

Si está desarrollando con un 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 de su equipo pueden ver claramente qué variables de entorno se necesitan para ejecutar su aplicación. También puede crear un archivo .env.testing. cuando ejecute las pruebas de PHPUnit o cuando ejecute los comandos de Artisan con la opción --env=testing.

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

Tipos de variable de entorno

Todas las variables de sus archivos .env se analizan como cadenas, por lo que se han creado algunos valores reservados para permitirle devolver un rango más amplio de tipos desde la función env():

.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 necesita definir una variable de entorno con un valor que contenga espacios, puede hacerlo encerrando el valor entre comillas.

APP_NAME="My Application"

Recuperando la información de entorno

Todas las variables listadas en este archivo serán cargadas en el $_ENV PHP super-global cuando su aplicación reciba una solicitud. Sin embargo, puede usar el ayudante env hpara recuperar los valores de estas variables en sus archivos de configuración. De hecho, si revisa los archivos de configuración de Laravel, notará que varias de las opciones ya están usando este ayudante:

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

El segundo valor que se pasa a la función env es el "valor por defecto". Este valor se utilizará si no existe ninguna variable de entorno para la clave dada.

Determinación del entorno actual

El entorno actual de la aplicación se determina a través de la variable APP_ENV de su archivor .env fPuede acceder a este valor a través del método de entorno de la fachada de la aplicación:

$environment = App::environment();

También puede pasar argumentos al método del medio ambiente para comprobar si el medio ambiente coincide con un valor determinado. El método devolverá true si el entorno coincide con alguno de los valores dados:

if (App::environment('local')) {
    // The environment is local
}

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

La detección del entorno de la aplicación actual puede ser anulada por una variable de entorno APP_ENV a nivel de servidor. Esto puede ser útil cuando se necesita compartir la misma aplicación para diferentes configuraciones de entorno, de modo que se puede configurar un host determinado para que coincida con un entorno determinado en las configuraciones de su servidor.

Ocultando las variables de entorno de las páginas de depuración

Cuando una excepción no es capturada y la variable de entorno APP_DEBUG es verdadera, la página de depuración mostrará todas las variables de entorno y su contenido. En algunos casos puede querer ocultar ciertas variables. Puede hacerlo actualizando la opción debug_hide en su archivo de configuración ur config/app.php.

Algunas variables están disponibles tanto en las variables de entorno como en los datos del servidor / solicitud. Por lo tanto, es posible que tenga que ocultarlas tanto para $_ENV como para $_SERVER:

return [

    // ...

    'debug_hide' => [
        '_ENV' => [
            'APP_KEY',
            'DB_PASSWORD',
        ],

        '_SERVER' => [
            'APP_KEY',
            'DB_PASSWORD',
        ],

        '_POST' => [
            'password',
        ],
    ],
];

# Acceder a los valores de configuración

Puede acceder fácilmente a sus valores de configuración mediante la función de ayuda a la configuración global desde cualquier lugar de su aplicación. Se puede acceder a los valores de configuración utilizando la sintaxis "punto", que incluye el nombre del archivo y la opción a la que desea 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');

// Retrieve a default value if the configuration value does not exist...
$value = config('app.timezone', 'Asia/Seoul');

Para establecer los valores de configuración en tiempo de ejecución, pase una matriz al ayudante de configuración:

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

# Configuración Caching

Para aumentar la velocidad de su aplicación, debería guardar en caché todos sus archivos de configuración en un único archivo mediante el comando config:cache Artisan. Esto combinará todas las opciones de configuración de su aplicación en un único archivo que será cargado rápidamente por el framework.

Normalmente debería ejecutar el comando php artisan config:cache como parte de su rutina de despliegue de producción. El comando no debe ser ejecutado durante el desarrollo local ya que las opciones de configuración necesitarán ser cambiadas frecuentemente durante el curso del desarrollo de su aplicación.

Si ejecuta el comand config:cache durante su proceso de despliegue, debe asegurarse de que sólo está llamando a la función env desde sus archivos de configuración. Una vez que la configuración se haya almacenado en caché, el archivo .env no se cargará y todas las llamadas a la función env se devolverán nulas.

# Modo de mantenimiento

Cuando su aplicación esté en modo de mantenimiento, se mostrará una vista personalizada para todas las solicitudes de su aplicación. Esto facilita la "desactivación" de su aplicación mientras se está actualizando o cuando está realizando el mantenimiento. Se incluye una comprobación del modo de mantenimiento en la pila de middleware predeterminada para su aplicación. Si la aplicación se encuentra en modo de mantenimiento, se lanzará una MaintenanceModeException con un código de estado de 503.

Para habilitar el modo de mantenimiento, ejecute el down Artisan command:

php artisan down

También puede proporcionar una opción de reintento para el comando down, que se establecerá como el valor de la cabecera Retry-After HTTP:

php artisan down --retry=60

Anulación del modo de mantenimiento

Incluso en el modo de mantenimiento, puede utilizar la opción secret para especificar un token de derivación del modo de mantenimiento:

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

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

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

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

Pre-Rendering The Maintenance Mode View

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

Por esta razón, Laravel le permite pre-procesar una vista de modo de mantenimiento que será devuelta al principio del ciclo de solicitud. Esta vista se renderiza antes de que se haya cargado cualquiera de las dependencias de su aplicación. Puedes pre-renderizar una plantilla de tu elección usando la opción de renderización del comando down:

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

Redireccionamiento de las solicitudes de modo de mantenimiento

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

php artisan down --redirect=/

Desactivando el modo de mantenimiento

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

php artisan up

Puede personalizar la plantilla del modo de mantenimiento por defecto definiendo su propia plantilla en resources/views/errors/503.blade.php.

Modo de Mantenimiento y Colas

Mientras su solicitud esté en modo de mantenimiento, no se manejará queued jobs. Los trabajos continuarán siendo manejados normalmente una vez que la aplicación esté fuera del modo de mantenimiento.

Alternativas al modo de mantenimiento

Dado que el modo de mantenimiento requiere que su aplicación tenga varios segundos de inactividad, considere alternativas como Envoyer para lograr un despliegue con cero tiempo de inactividad con Laravel.