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.

El artículo anterior trataba sobre como implementar autenticación social en Laravel.

¿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

Usar Configuraciones o Variables de Entorno en Laravel? - Opinión

En Laravel, uno de los temas más importantes al desarrollar una aplicación robusta es entender cómo manejar la configuración y las variables de entorno. Aunque ambos conceptos parecen similares, su propósito y momento de uso son distintos. En este artículo te explico, desde la práctica, cómo funcionan, cuándo conviene usar cada uno y cómo aplicarlos correctamente en proyectos reales.

¿Por qué Laravel separa configuraciones y variables de entorno?

Laravel organiza la información sensible y las configuraciones en dos niveles: las variables del entorno (.env) y los archivos de configuración (/config). Esta separación no es casual, sino una decisión clave para la seguridad y el mantenimiento del código.

El propósito del archivo .env

El archivo .env almacena datos que cambian según el entorno de ejecución: base de datos, API keys, servicios externos o modo de aplicación (desarrollo o producción). Laravel los gestiona a través del paquete Dotenv, que carga las variables al iniciar el framework.

Estas variables no deben compartirse ni versionarse. Son específicas del servidor, por lo que un cambio en producción no afecta a tu entorno local. Por ejemplo:

APP_ENV=local
APP_DEBUG=true
PAYPAL_CLIENT_ID=xxxx

Se trata de que tu cliente pueda inspeccionar la aplicación sin poner en riesgo su estabilidad. Es decir, que no pueda “romperla”, crear datos extraños o eliminar la información de ejemplo. Creo que ya queda bastante claro: el modo demo permite ver e interactuar con la app, pero sin alterar los registros establecidos.

Cómo funciona el sistema de configuración en /config/*.php

Los archivos de configuración, en cambio, definen los parámetros internos de la aplicación: logging, cache, correo, colas, etc. Cada archivo en /config contiene un arreglo PHP con valores que pueden hacer referencia a variables del .env.

Por ejemplo, en config/app.php:

'name' => env('APP_NAME', 'MiAplicacion'),
'debug' => env('APP_DEBUG', false),

Diferencias entre env() y config() en Laravel

La confusión más común es cuándo usar env() directamente o cuándo depender de config(). Aunque ambas funciones devuelven valores configurables, su ámbito y propósito son distintos.

Cuándo usar variables de entorno

Usa env() solo para inicializar configuraciones. Nunca deberías llamarla directamente dentro del código de tu aplicación (controladores, servicios, vistas). En esos lugares se recomienda usar config(), ya que las variables pueden quedar en caché y no actualizarse correctamente.

Cuándo crear una configuración personalizada

Cuando un valor afecta la lógica de negocio y no solo el entorno, conviene crear un archivo de configuración propio. Esto permite definir valores por defecto, mantener coherencia y evitar romper la aplicación si falta una variable.

Ejemplo práctico: modo demo controlado por variable de entorno

En mi caso, implementé un modo demo para una aplicación de ejemplo. Quería que los usuarios pudieran interactuar con la app sin alterar datos sensibles. Para eso creé una variable de entorno personalizada:

APP_DEMO=true

Y en el código la utilicé de forma simple:

if (env('APP_DEMO')) {
   // Bloquear ciertas acciones
}

¿Por qué no usar una configuración en lugar de variables de entorno?

Seguramente te preguntarás: ¿por qué demonios no empleé una configuración?
En mi canal de YouTube tengo varios videos donde comento sobre el uso de variables de entorno y configuraciones personalizadas.

Ambas son opciones válidas, pero en resumen, casi siempre recomiendo usar configuraciones, ya que trabajar directamente con variables de entorno puede ser riesgoso.

Por ejemplo, si una variable no está definida —imaginemos que borras la variable de entorno de PayPal—, romperías toda la aplicación, porque PayPal necesita esas claves sí o sí.

Cómo crear y leer configuraciones personalizadas en Laravel

Crear un archivo en /config

Puedes crear un archivo config/demo.php con contenido como:

return [
   'enabled' => env('APP_DEMO', false),
];

Acceder a valores desde controladores o vistas

Luego, puedes acceder al valor desde cualquier parte de tu aplicación:

if (config('demo.enabled')) {
   // Ejecutar modo demo
}

Este enfoque es más seguro, ya que mantiene la lógica centralizada y compatible con la caché de configuración.

Establecer valores por defecto seguros

Siempre define valores por defecto en las llamadas a env(). Así, si una variable no está presente, el sistema sabrá qué hacer:

'paypal_client_id' => env('PAYPAL_CLIENT_ID', 'default'),

Errores comunes y cómo evitarlos

Cuando usamos el esquema de configuraciones, el sistema está diseñado para que, por defecto, devuelva el valor de la variable de entorno si existe.
Esa es la de mayor prioridad. Pero si no está definida, entonces toma un valor por defecto.

Esto es lo que normalmente implementamos en el 99.9% de los casos.
Por eso digo que lo ideal es seguir esa estructura. Todo viene así por defecto: se usa la variable si está, y si no, se usa la configuración base.

Eliminar o renombrar una variable crítica puede romper la aplicación. Por eso es buena práctica definir configuraciones con valores por defecto.

En resumen, queremos obtener un valor ya sea desde la variable de entorno o desde la configuración, pero con seguridad de que exista.

Si lo hacemos bien, evitamos errores. Pero si lo hacemos mal y llamamos la variable directamente, es igual de riesgoso que no tener configuración alguna.

Cuándo sí crear una configuración personalizada

Cada vez que quieras crear una configuración personalizada —como hicimos en este curso con las de PayPal—, lo ideal es definirlas correctamente.
Aquí, por ejemplo, deberían estar las configuraciones de producción, aunque no las coloco por razones obvias (este es un proyecto de ejemplo).
Pero en una aplicación real sí deben estar establecidas.

Preguntas frecuentes sobre configuraciones y variables en Laravel

• ¿Cuál es la diferencia entre config() y env()?
  • env() lee variables del entorno, mientras que config() obtiene valores definidos en los archivos /config.
• ¿Dónde se guardan las configuraciones en Laravel?
  • En la carpeta /config, donde cada archivo define un conjunto de parámetros de la aplicación.
• ¿Es seguro usar variables de entorno directamente?
  • No. En producción deben accederse mediante config(), no con env() directamente.
• ¿Qué pasa si falta una variable en el .env?
  • Si no se define un valor por defecto, Laravel puede lanzar errores o comportarse de forma inesperada.

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.

La diferencia entre configuraciones y variables de entorno en Laravel es fundamental para desarrollar aplicaciones seguras, predecibles y escalables. Las variables de entorno sirven para definir el entorno y los datos sensibles; las configuraciones, para establecer el comportamiento interno de la aplicación.

En mi experiencia, prefiero mantener las cosas simples. Si solo necesito saber si algo está activo, uso una variable de entorno. Pero si el valor afecta la lógica del sistema o puede faltar, opto por una configuración con valor por defecto. Ese equilibrio entre simplicidad y robustez es la clave para un código limpio y estable.

Aprende ahora a como procesar tareas pesadas o de alta latencia en segundo plano con las colas y trabajos en Laravel.