Variables de entorno y configuraciones personalizadas en Laravel

▶

Cuando desarrollamos una aplicación en Laravel, es normal que ciertos valores cambien según el entorno: credenciales de base de datos, servicios externos, modo de depuración o URLs. Aquí es donde entran en juego las variables de entorno en Laravel, una pieza clave para mantener el código limpio, seguro y fácil de desplegar.

Sin embargo, aunque Laravel facilita mucho su uso, también es frecuente ver errores graves (sobre todo en producción) por no entender bien cuándo usar env(), cuándo usar config() y qué ocurre al cachear la configuración. En este artículo te explico todo eso con ejemplos prácticos y criterio real de uso.

Las variables de entorno son ideales para cuando queremos probar múltiples configuraciones en un proyecto de una manera rápida, o cuando varias personas están desarrollando sobre un mismo proyecto y tienen distintas configuraciones del proyecto, en otras palabras, ofrecen un enfoque ágil y rápido para acceder a múltiples configuraciones pero esto también puede traer inconvenientes, al poder cambiar o eliminar variables de entorno por error desde un solo archivo puede traer problemas al cambiar de un modo a otro sin darse cuenta o de borrar alguna variable de entorno necesaria por el proyecto, por lo tanto, emplearla en producción pueden acarrear problemas precisamente por esta libertad.

Los archivos de configuración son excelentes para tener las configuraciones finales de producción del proyecto, por lo tanto, es donde deberíamos emplear las variables de entorno en desarrollo y en producción las configuraciones y esto es algo que ya el framework nos lo dice, ya que si vemos algunas configuraciones, veremos muchas veces un esquema como el siguiente:

¿Qué es una variable de entorno en Laravel?

Una variable de entorno es un valor externo al código que se carga en tiempo de ejecución y que permite modificar el comportamiento de la aplicación sin tocar los archivos PHP.

En Laravel, estas variables se definen normalmente en el archivo .env y se cargan gracias al componente PHP Dotenv.

Por qué Laravel separa configuración y código

Laravel sigue una buena práctica fundamental del desarrollo moderno:
el código no debe cambiar entre entornos, la configuración sí.

Gracias a esto:

• El mismo código puede ejecutarse en local, staging o producción.
• Las credenciales no se suben al repositorio.
• Los despliegues son más seguros y predecibles.

Uno de los grande problemas en el desarrollo de software que consisten en que cuando estamos desarrollando una aplicación y cada cierto tiempo vamos presentando módulos a producción, es publicar junto con estos cambios nuestras configuraciones usadas solo en desarrollo y con el esquema presentado anteriormente se puede solventar con tan solo evitar subir el archivo de .env a producción y manteniendo los valores de producción en los archivos de configuración correspondientes.

Esto no quiere decir que no es recomendable o profesional emplear variables de entorno a producción, en lo posible se debería de evitar pero, puedes emplearla con extremo cuidado, manteniendo un mínimo variables de entorno en producción que pueden ser imprescindibles para mantenerlo lo más controlado posible.

Otro buen uso de las variables de entorno en producción es cuando hacemos grandes cambios en el proyecto y lo subimos a producción o hay un error a producción que se complica repararlo mediante la visualización del log y por lo tanto, queremos probar en producción si todo lo desarrollado funciona como se espera, en estos casos, puedes descomentar las variables de entorno en producción:

.env

APP_ENV=local 
APP_DEBUG=true

Probar el sistema en el servidor y cuando veamos que todo está funcionando como se espera, se vuelven a comentar:

.env

# APP_ENV=local 
# APP_DEBUG=true

Y con esto, se vuelve a evitar tocar las configuraciones del proyecto que son archivos que debemos de manejar con extremo cuidado.

Qué tipo de datos deberían ir en variables de entorno

Algunos ejemplos claros:

• Credenciales de base de datos
• API keys (Mailgun, AWS, Stripe…)
• Drivers de caché, colas o sesiones
• Flags como APP_ENV o APP_DEBUG

El archivo .env en Laravel

Para qué sirve el archivo .env

El archivo .env es donde definimos las variables de entorno locales del proyecto, siguiendo el formato:

CLAVE=VALOR

Laravel carga automáticamente este archivo al iniciar la aplicación.

Diferencias entre .env y .env.example

• .env
  • Contiene valores reales
  • Nunca debe subirse al repositorio
• .env.example
  • Sí se versiona
  • Sirve como plantilla
  • Indica qué variables son necesarias

Mantener un .env.example actualizado evita muchísimos problemas cuando alguien nuevo clona el proyecto o cuando se despliega en un nuevo entorno.

Por qué el archivo .env no debe subirse al repositorio

Subir el .env implica:

• Exponer credenciales
• Forzar configuraciones de desarrollo en producción
• Riesgos de seguridad muy serios

Laravel ya asume que el .env es privado, por eso viene ignorado por defecto en .gitignore.

Cómo funciona Laravel internamente con las variables de entorno

Desde Laravel 5, el framework usa PHP Dotenv para cargar las variables del .env y exponerlas a PHP a través de $_ENV.

Cómo y cuándo se cargan las variables

Las variables se cargan:

• Al iniciar la aplicación
• Antes de que se lean los archivos de configuración

Por eso verás muchas líneas como esta en config/*.php:

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

Esto es seguro incluso con la configuración cacheada.

Tipos de valores admitidos en el .env

Laravel interpreta algunos valores especiales:

| Valor en `.env` | Tipo real    |
| --------------- | ------------ |
| true / false    | boolean      |
| null            | null         |
| empty           | string vacío |
 

También puedes usar comillas si hay espacios:

APP_NAME="Mi Aplicación"

env() vs config(): la diferencia que evita errores en producción

Esta es una de las partes más importantes del artículo.

Cuándo usar env()

Solo dentro de los archivos de configuración (config/*.php)

Ejemplo correcto:

// config/app.php
'env' => env('APP_ENV', 'production'),

Por qué no deberías usar env() fuera de los archivos de configuración

Cuando ejecutas:

$ php artisan config:cache

Laravel:

• Combina toda la configuración en un solo archivo
• Deja de cargar el .env

En ese punto, cualquier env() usado fuera de config puede devolver null.

En producción, esto provoca errores difíciles de rastrear.

Más de una vez me he encontrado bugs en producción causados exactamente por esto.

Cómo consumir correctamente la configuración con config()

La forma correcta es:

• Leer env() en config/*.php
• Usar config() en el resto de la aplicación

• config('app.env');

Variables de entorno en desarrollo y producción

Uso recomendado en desarrollo

En desarrollo, el .env es ideal:

• Cambios rápidos
• Múltiples configuraciones
• Flexibilidad total

Aquí no hay problema en modificar variables con frecuencia.

Riesgos de usar .env directamente en producción

En producción, el .env:

Es fácil de modificar por error

• No está versionado
• Puede romper el sistema sin dejar rastro claro
• Por eso, en mi experiencia, la configuración final de producción debería vivir en config/*.php, no depender de un .env editable.

Casos excepcionales y cómo manejarlos con cuidado

Hay casos puntuales (errores complejos, validaciones urgentes) donde puede ser útil activar temporalmente:

APP_ENV=local
APP_DEBUG=true

Probar, verificar y volver a desactivarlo inmediatamente.

Es una técnica válida, pero solo si sabes exactamente lo que estás haciendo.

Caché de configuración y su impacto en las variables de entorno

Qué hace realmente php artisan config:cache

• Genera un único archivo con toda la configuración
• Mejora el rendimiento
• Desactiva la carga del .env

Qué pasa con env() cuando la configuración está en caché

Solo funcionará con variables de entorno del sistema, no del .env.

Por eso Laravel advierte claramente:

Nunca uses env() fuera de los archivos de configuración.

Errores comunes al desplegar a producción

• Cachear configuración y luego cambiar el .env
• Usar env() en controladores o servicios
• Olvidar limpiar la caché (config:clear)

Crear configuraciones personalizadas en Laravel

Es posible crear configuraciones personalizadas para nuestra aplicación, lo cual es extremadamente útil para poder personalizar estos parámetros cuando sean necesarios, por ejemplo, si quieres instalar alguna billetera electrónica como PayPal que requiere definir claves de acceso, lo más recomendado es manejar estos accesos mediante configuraciones para poder editarlas más fácilmente, también son útiles si necesitamos crear cualquier parámetro adicional para el correcto funcionamiento de la aplicación.

Para ello, debemos de seleccionar el archivo de configuración en donde queremos que esté alojada, aquí lo recomendado es que escojas el que más se asemeja segun la configuracion a crear, por ejemplo, si quieres emplear claves para acceder a Dropbox o Google Drive, puedes escoger el database.php o el de app.php si son credenciales de login social, puedes usar el de auth.php por ejemplo.

Cuándo tiene sentido crear una configuración propia

Por ejemplo:

• Claves de servicios externos
• Flags personalizados
• Parámetros específicos del negocio

Dónde ubicarla dentro de la carpeta config

Lo ideal es:

• Usar un archivo existente si encaja (app.php, services.php)
• Crear uno nuevo si es necesario

Al igual que las configuraciones existentes, es posible usar la función de ayuda env() para que tome el valor del .env si la misma existe allí:

// config/custom.php
return [
   'route' => env('APP_ROUTE', 'production'),
];

Cómo leer estas configuraciones desde la aplicación:

config('custom.route');

Este enfoque es mucho más seguro que usar env() directamente.

Ejemplo

config\app.php

'app_route' => env('APP_ROUTE', "production"),

.env

APP_ROUTE=local

Para acceder a estas configuraciones, usamos la función de ayuda config():

config('app')['env']

En la cual como primer parámetro se especifica el nombre del archivo de configuración y como siguiente parámetro la clave:

config('app')['env']

También podríamos referenciar directamente la variable de entorno:

env('APP_ROUTE', "production")

Validar variables de entorno y evitar fallos silenciosos

Problemas típicos cuando falta una variable

• Valores null
• Errores en tiempo de ejecución
• Bugs difíciles de reproducir

Uso de Env::getOrFail a partir de Laravel 10

Laravel 10 introduce un método muy útil:

use Illuminate\Support\Env;
Env::getOrFail('MAILGUN_SECRET');

Si la variable no existe, lanza una excepción inmediatamente.

Esto permite detectar errores al arrancar, no cuando ya falló algo crítico.

Detectar errores lo antes posible

Este enfoque es ideal para:

• Producción
• Servicios externos
• Configuración crítica

Gestión de múltiples entornos en Laravel

APP_ENV y detección del entorno

Laravel detecta el entorno con APP_ENV:

App::environment('local');

Archivos .env por entorno

Laravel soporta:

• .env
• .env.staging
• .env.testing

Esto facilita trabajar con múltiples entornos sin mezclar configuraciones.

Crear archivos personalizados

En caso de que sea necesario, podemos crear archivos de configuración personalizados, simplemente debemos de crear el archivo dentro de la carpeta config del proyecto en el cual, debemos de tener la misma estructura que mantienen los actuales, por ejemplo:

config\custom.php

<?php
return [
    'test_config' => env('TEST_CONFIG', 'VALUE'),
];

Y para acceder al archivo personalizado, lo hacemos de igual manera con los archivos de configuración actuales:

config('custom');

Buenas prácticas para equipos y despliegues

• .env.example siempre actualizado
• Variables mínimas en producción
• Configuración cacheada en deploy

Buenas prácticas finales para variables de entorno en Laravel

Checklist rápida para producción

• ✅ .env fuera del repositorio
• ✅ env() solo en config
• ✅ config() en el resto del código
• ✅ config:cache en producción
• ✅ Validación de variables críticas

Errores que deberías evitar:

• Usar env() en controladores
• Activar APP_DEBUG en producción
• Depender del .env para lógica crítica

Recomendaciones basadas en experiencia real

Centralizar la configuración y reducir al mínimo el .env en producción hace los despliegues más seguros, previsibles y fáciles de mantener.

Preguntas frecuentes sobre variables de entorno en Laravel (FAQ)

• ¿Debo subir el archivo .env al repositorio?
  • No. Nunca.
• ¿Puedo usar variables de entorno en producción?
  • Sí, pero con extremo cuidado y las mínimas necesarias.
• ¿Qué pasa si uso env() con config:cache?
  • Probablemente obtendrás valores null.
• ¿Es mejor Env::getOrFail que env()?
  • Para variables críticas, sí.

Conclusión

Las variables de entorno en Laravel son una herramienta poderosa, pero mal utilizadas pueden convertirse en una fuente constante de errores, especialmente en producción.

Entender la diferencia entre .env, env() y config(), junto con el impacto de config:cache, marca la diferencia entre un proyecto frágil y uno profesional.

Si aplicas estas buenas prácticas, tu aplicación será más segura, mantenible y preparada para crecer.