Documentación de Laravel 10.x
Aquí encontrarás fragmentos de código de Laravel y consejos útiles sobre desarrollo web.
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.
¿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
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.
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.
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.
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"
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.
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.
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.
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
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
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']);
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ónenv
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ónenv
solo devolverá variables de entorno externas a nivel de sistema.
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
entrue
. En tu entorno de producción, este valor siempre debe serfalse
. Si la variable se establece entrue
en producción, corres el riesgo de exponer valores de configuración sensibles a los usuarios finales de tu aplicación.
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
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&
.
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"
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=/
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
.
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.
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.