Contents
Introducción: por qué usar variables de entorno y dotenv en WordPress
Resumen: Gestionar credenciales y configuraciones sensibles mediante variables de entorno elimina la dependencia de secretos embebidos en el código, facilita despliegues seguros y separa configuración de código. Usar dotenv (vlucas/phpdotenv u otros mecanismos) para cargar variables en entornos locales y de staging ofrece comodidad sin comprometer seguridad en producción, donde lo ideal es definir las variables directamente en el entorno del servidor (systemd, contenedores, host, panel de hosting).
Ventajas principales
- Seguridad: evita almacenar credenciales (DB, API keys) en el repositorio.
- Portabilidad: la misma base de código funciona con distintas configuraciones por entorno.
- Facilidad de despliegue: los pipelines CI/CD y contenedores usan variables en runtime.
- Auditoría y rotación: cambiar credenciales sin tocar código.
Decisiones de diseño
Antes de implementar, defina:
- ¿Dónde va el archivo .env? (fuera del webroot es lo ideal)
- ¿Se usará vlucas/phpdotenv o solo getenv()/_ENV/_SERVER?
- ¿Se cargará en wp-config.php o en un mu-plugin inicial?
- ¿Cómo se gestionarán secretos en producción (variables de entorno del host, panel, o secreto de secret manager)?
Requisitos y consideraciones previas
- Acceso al archivo wp-config.php y al sistema de ficheros del servidor.
- Si usa composer: acceso a vendor/autoload.php para cargar phpdotenv.
- Agregar .env a .gitignore y asegurar permisos (600).
- En ambientes compartidos, preferir variables del sistema en vez de un .env en webroot.
Instalación de vlucas/phpdotenv (opcional pero recomendado)
Si su instalación de WordPress usa composer (por ejemplo en proyectos headless o en entornos controlados), es conveniente instalar phpdotenv. Si no usa composer, más abajo muestro alternativas ligeras.
Usando composer:
composer require vlucas/phpdotenv
Ubicación recomendada del archivo .env
Lo ideal es colocar el .env fuera del webroot. Ejemplos:
- /var/www/example.com/.env (si el webroot es /var/www/example.com/public)
- En contenedores, usar variables en docker-compose o secretos de Docker/Kubernetes.
Si no es posible, asegúrese de que el servidor no sirva ficheros .env y que tenga permisos restrictivos.
Cargar .env desde wp-config.php (método recomendado y temprano)
wp-config.php se ejecuta muy pronto en la carga de WordPress, por eso es un buen lugar para cargar variables necesarias para constantes como DB_NAME, AUTH_KEY, etc. El patrón habitual es intentar cargar composer autoload y phpdotenv si existe, con fallback a getenv() para producción.
Ejemplo de código para colocar al inicio de wp-config.php (antes de definir DB constants):
lt?php
// wp-config.php (fragmento al inicio)
// Ruta al directorio base del proyecto (ajústela según su estructura)
base_dir = dirname(__FILE__)
// Intentar cargar Composer autoload si existe
autoload = base_dir . /vendor/autoload.php
if (file_exists(autoload)) {
require_once autoload
// Usar phpdotenv si está instalada
if (class_exists(DotenvDotenv::class)) {
envPath = base_dir // o dirname(base_dir) si .env está un nivel arriba
dotenv = DotenvDotenv::createImmutable(envPath)
dotenv->safeLoad() // safeLoad no falla si no existe .env
}
}
// Helper para obtener variable con prioridad: getenv > _ENV > _SERVER > default
function env(key, default = null) {
value = getenv(key)
if (value !== false) return value
if (isset(_ENV[key])) return _ENV[key]
if (isset(_SERVER[key])) return _SERVER[key]
return default
}
// Ejemplo: definir constantes de DB usando variables de entorno
define(DB_NAME, env(DB_NAME, wordpress))
define(DB_USER, env(DB_USER, wp_user))
define(DB_PASSWORD, env(DB_PASSWORD, wp_pass))
define(DB_HOST, env(DB_HOST, localhost))
// Claves y salts
define(AUTH_KEY, env(AUTH_KEY, put-your-unique-phrase-here))
define(SECURE_AUTH_KEY, env(SECURE_AUTH_KEY, ))
define(LOGGED_IN_KEY, env(LOGGED_IN_KEY, ))
define(NONCE_KEY, env(NONCE_KEY, ))
define(AUTH_SALT, env(AUTH_SALT, ))
define(SECURE_AUTH_SALT, env(SECURE_AUTH_SALT, ))
define(LOGGED_IN_SALT, env(LOGGED_IN_SALT, ))
define(NONCE_SALT, env(NONCE_SALT, ))
// Continúa el resto del wp-config...
Notas sobre este enfoque
- Usar safeLoad() para evitar errores si no hay .env en producción (allí las variables estarán en el entorno).
- Si prefiere que la ausencia de .env provoque fallo en local, use load() en lugar de safeLoad().
- Mantener este bloque al principio de wp-config.php antes de usar cualquier constante que dependa de config.
Ejemplo de archivo .env (local)
# .env - ejemplo DB_NAME=mi_basedatos DB_USER=mi_usuario DB_PASSWORD=mi_password_secreto DB_HOST=127.0.0.1:3306 # Salts generados AUTH_KEY=k7G#s... SECURE_AUTH_KEY=... LOGGED_IN_KEY=... NONCE_KEY=... # Configs adicionales WP_DEBUG=true S3_KEY=AKIA... S3_SECRET=... MAILGUN_API_KEY=key-...
Alternativa sin Composer: cargar .env manualmente
Si no desea usar phpdotenv, puede parsear .env con un script mínimo. Es menos robusto pero funciona para simples necesidades.
lt?php
// Simple loader .env (no recomendado para producción compleja)
function load_dotenv_simple(path) {
if (!file_exists(path)) return
lines = file(path, FILE_IGNORE_NEW_LINES FILE_SKIP_EMPTY_LINES)
foreach (lines as line) {
if (strpos(trim(line), #) === 0) continue
if (!strpos(line, =)) continue
list(name, value) = explode(=, line, 2)
name = trim(name)
value = trim(value)
// eliminar comillas si existen
value = trim(value, )
if (!getenv(name)) {
putenv(name=value)
_ENV[name] = value
_SERVER[name] = value
}
}
}
// Uso:
// load_dotenv_simple(dirname(__FILE__) . /.env)
Despliegue en producción: no use archivos .env en repositorio
- En servidores gestionados, configure variables de entorno desde el panel (cPanel, Plesk, DigitalOcean App Platform, etc.).
- En contenedores, especifique variables en docker-compose.yml o use secretos de Docker/Kubernetes.
- En servidores propios con systemd, agregue Environment= en la unidad o use export en el script de arranque.
Ejemplo docker-compose (servicios)
version: 3.8
services:
wordpress:
image: wordpress:6.0-php8.0-apache
environment:
- WORDPRESS_DB_HOST=db:3306
- WORDPRESS_DB_USER=wp_user
- WORDPRESS_DB_PASSWORD=wp_pass
- WORDPRESS_DB_NAME=wp_db
- S3_KEY={S3_KEY} # desde .env del host o variables de entorno CI
volumes:
- ./wp:/var/www/html
depends_on:
- db
db:
image: mysql:5.7
environment:
MYSQL_ROOT_PASSWORD: rootpass
MYSQL_DATABASE: wp_db
MYSQL_USER: wp_user
MYSQL_PASSWORD: wp_pass
Métodos de carga alternativos
- Servidor web: definir variables con SetEnv en Apache (vhost) o fastcgi_param en Nginx.
- systemd: Environment=MI_VAR=valor en la unidad que gestione PHP-FPM o el proceso relevante.
- Panel de hosting: muchos paneles permiten definir variables ambientales por sitio.
Ejemplo Apache (vhost)
# En la configuración del VirtualHost (no en .htaccess para variables sensibles) SetEnv DB_NAME mi_basedatos SetEnv DB_USER mi_usuario SetEnv DB_PASSWORD mi_password
Ejemplo Nginx PHP-FPM (fastcgi_param)
# En la configuración del server o location que pasa a PHP-FPM fastcgi_param DB_NAME mi_basedatos fastcgi_param DB_USER mi_usuario fastcgi_param DB_PASSWORD mi_password
Buenas prácticas de seguridad
- Agregue .env a .gitignore:
.env
- Permisos restrictivos: chmod 600 .env y propiedad por el usuario que ejecuta PHP.
- No exponga .env en backups públicamente accesibles.
- Usar gestores de secretos (AWS Secrets Manager, HashiCorp Vault, Google Secret Manager) para producción si la infraestructura lo permite.
- Rotación periódica de claves y uso de claves con permisos mínimos.
- Para claves de terceros (AWS, Mailgun), cree usuarios con permisos limitados y no use root keys.
Ejemplo completo: flujo recomendado para un proyecto
- Desarrollo local:
- Colocar .env en la raíz del proyecto con credenciales de desarrollo.
- Instalar vlucas/phpdotenv con composer y cargar en wp-config.php.
- CI/CD:
- Agregar variables en el pipeline (GitHub Actions Secrets, GitLab CI variables).
- No incluir .env en artefactos publicados.
- Producción:
- Definir variables en el host o gestor de contenedores no suba .env al servidor público.
- Comprobar que wp-config.php usa getenv/env() y no valores hardcodeados.
Recuperar variables desde PHP en runtime
Puede usar env(KEY) (si implementó el helper) o directamente getenv(KEY). Evite depender solo de _ENV en entornos donde php.ini desactiva variables_order o variables_superglobals estén alteradas.
// Ejemplo de uso en plugins o themes aws_key = getenv(S3_KEY) ?: clave_por_defecto aws_secret = getenv(S3_SECRET)
Consideraciones especiales para WordPress multisite y constantes que cambian
- En multisite, si las bases de datos de sub-sitios usan las mismas credenciales, mantener DB_ en entorno es sencillo.
- Si necesita distintos DB_HOST por site, considere lógica en wp-config.php que detecte el host y seleccione variables.
Solución de problemas comunes
- Las variables no aparecen: comprobar si PHP-FPM/Apache carga el entorno y si getenv devuelve valores. Algunas configuraciones limpian el entorno.
- wp-config se ejecuta antes de cargar autoload: coloque el bloque loader al inicio del archivo.
- Valores vacíos en producción: en producción, asegúrese de definir las variables en el entorno del sistema (no depender de .env local).
- Error de permisos en .env: ajustar ownership al usuario de PHP y permisos a 600.
Lista de verificación antes de poner en producción
- .env no está en el repositorio y está excluido por .gitignore.
- Variables sensibles definidas en el entorno de producción o gestor de secretos.
- wp-config.php carga variables de entorno antes de definir constantes necesarias.
- Permisos del archivo .env restrictivos y no accesibles vía web.
- Tests básicos de conexión a DB y APIs en el entorno de preproducción.
Ejemplos rápidos de comandos útiles
Agregar .env a .gitignore:
echo .env >> .gitignore
Establecer permiso seguro:
chmod 600 /ruta/a/.env chown www-data:www-data /ruta/a/.env # ajuste el usuario según su sistema
Conclusión
Usar variables de entorno y dotenv en WordPress eleva la seguridad, facilita despliegues y separa configuración del código. Implementándolo correctamente (cargando temprano en wp-config.php, manteniendo .env fuera de repositorio y usando variables de entorno en producción) se logra un entorno de desarrollo y despliegue más seguro y manejable.
Recursos útiles
|
|
Acepto donaciones de BAT's mediante el navegador Brave 🙂 |