Carga las variables de entorno de .env a getenv(), $_ENV y $_SERVER automáticamente.
¿Por qué .env?
Nunca debe almacenar credenciales sensibles en su código. Almacenar la configuración en el entorno es uno de los principios de una aplicación de doce factores. Cualquier cosa que pueda cambiar entre los entornos de despliegue – como las credenciales de la base de datos o las credenciales para los servicios de terceros – debe ser extraído del código en las variables de entorno.
Básicamente, un archivo .env es una manera fácil de cargar las variables de configuración personalizadas que su aplicación necesita sin tener que modificar los archivos .htaccess o los hosts virtuales de Apache/nginx. Esto significa que no tendrá que editar ningún archivo fuera del proyecto, y todas las variables de entorno siempre se establecen sin importar cómo su proyecto – Apache, Nginx, CLI, e incluso el servidor web incorporado de PHP. Es mucho más fácil que todas las otras maneras que usted conoce para establecer las variables de entorno, y te va a encantar!
- NO editar hosts virtuales en Apache o Nginx
- NO añadir banderas
php_valuea los archivos .htaccess - Fácil portabilidad y compartición de los valores ENV requeridos
- COMPATIBLE con el servidor web incorporado de PHP y el CLI runner
PHP dotenv es una versión PHP del Rubydotenv original.
Instalación
La instalación es súper fácil a través de Composer:
$ composer require vlucas/phpdotenv
o añadirlo a mano a su archivo composer.json.
Actualización
Seguimos el versionado semántico, lo que significa que pueden ocurrir cambios de ruptura entre las principales versiones. Tenemos guías de actualización disponibles para V2 a V3, V3 a V4 y V4 a V5 disponibles aquí.
Uso
El archivo .env se mantiene generalmente fuera del control de versiones ya que puede contener claves y contraseñas sensibles de la API. Se crea un archivo .env.example separado con todas las variables de entorno necesarias definidas, excepto las sensibles, que son suministradas por el usuario para sus propios entornos de desarrollo o se comunican en otro lugar a los colaboradores del proyecto. Los colaboradores del proyecto copian entonces de forma independiente el archivo .env.example a un .env local y se aseguran de que todos los ajustes son correctos para su entorno local, rellenando las claves secretas o proporcionando sus propios valores cuando sea necesario. En este uso, el archivo .env debe agregarse al archivo .gitignore del proyecto para que nunca sea comprometido por los colaboradores. Este uso asegura que no hay contraseñas sensibles o claves de la API nunca estará en el historial de control de versiones por lo que hay menos riskof una violación de la seguridad, y los valores de producción nunca tendrá que ser compartida con todos los colaboradores del proyecto.
Agregar la configuración de su aplicación a un archivo .env en la raíz de suproject. Asegúrese de que el archivo .env se añade a su .gitignore por lo que no se comprueba en el código
S3_BUCKET="dotenv"SECRET_KEY="souper_seekret_key"
Ahora crear un archivo llamado .env.example y comprobar esto en el proyecto. Esto debería tener las variables ENV que necesita tener establecidas, pero los valores deberían estar en blanco o rellenados con datos ficticios. La idea es dejar que la gente sepa qué variables son necesarias, pero no darles los valores sensibles de producción.
S3_BUCKET="devbucket"SECRET_KEY="abc123"
A continuación, puede cargar .env en su aplicación con:
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);$dotenv->load();
Para suprimir la excepción que se lanza cuando no hay un archivo .env, puede:
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);$dotenv->safeLoad();
Opcionalmente puedes pasar un nombre de archivo como segundo parámetro, si quieres usar algo distinto a .env:
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__, 'myconfig');$dotenv->load();
Todas las variables definidas están ahora disponibles en los $_ENV y $_SERVERsuperglobales.
$s3_bucket = $_ENV;$s3_bucket = $_SERVER;
Putenv y Getenv
Se desaconseja fuertemente el uso de getenv() y putenv() debido a que estas funciones no son seguras para los hilos, sin embargo todavía es posible instruir aPHP dotenv para que utilice estas funciones. En lugar de llamar a Dotenv::createImmutable, se puede llamar a Dotenv::createUnsafeImmutable, que añadirá la función PutenvAdapter entre bastidores. Sus variables de entorno estarán ahora disponibles utilizando el método getenv, así como las superglobales:
$s3_bucket = getenv('S3_BUCKET');$s3_bucket = $_ENV;$s3_bucket = $_SERVER;
Anidación de variables
Es posible anidar una variable de entorno dentro de otra, útil para reducir la repetición.
Esto se hace envolviendo una variable de entorno existente en ${…} por ejemplo.
BASE_DIR="/var/webroot/project-root"CACHE_DIR="${BASE_DIR}/cache"TMP_DIR="${BASE_DIR}/tmp"
Inmutabilidad y personalización del repositorio
La inmutabilidad se refiere a si Dotenv puede sobrescribir las variables de entorno existentes. Si desea que Dotenv sobrescriba las variables de entorno existentes, utilice createMutable en lugar de createImmutable:
$dotenv = Dotenv\Dotenv::createMutable(__DIR__);$dotenv->load();
En el fondo, esto indica al «repositorio» que permita la inmutabilidad o no. Por defecto, el repositorio está configurado para permitir la sobreescritura de los valores existentes por defecto, lo cual es relevante si uno está llamando al método «create» utilizando el RepositoryBuilder para construir un repositorio más personalizado:
$repository = Dotenv\Repository\RepositoryBuilder::createWithNoAdapters() ->addAdapter(Dotenv\Repository\Adapter\EnvConstAdapter::class) ->addWriter(Dotenv\Repository\Adapter\PutenvAdapter::class) ->immutable() ->make();$dotenv = Dotenv\Dotenv::create($repository, __DIR__);$dotenv->load();
El ejemplo anterior escribirá los valores cargados en $_ENV y putenv, pero al interpolar las variables de entorno, sólo leeremos de $_ENV. Además, nunca reemplazará las variables ya configuradas antes de cargar el archivo.
Por medio de otro ejemplo, también se puede especificar un conjunto de variables para que sean listadas. Es decir, sólo se cargarán las variables de la lista permitida:
$repository = Dotenv\Repository\RepositoryBuilder::createWithDefaultAdapters() ->allowList() ->make();$dotenv = Dotenv\Dotenv::create($repository, __DIR__);$dotenv->load();
Requiriendo que se establezcan las variables
PHP dotenv ha incorporado la funcionalidad de validación, incluso para hacer cumplir la presencia de una variable de entorno. Esto es particularmente útil para que la gente sepa cualquier variable requerida explícitamente que su aplicación no funcionará sin ella.
Puede utilizar una sola cadena:
$dotenv->required('DATABASE_DSN');
O una matriz de cadenas:
$dotenv->required();
Si falta alguna variable de entorno, Dotenv lanzará un RuntimeException como este:
One or more environment variables failed assertions: DATABASE_DSN is missingVariables vacías
Además de requerir simplemente que se establezca una variable, es posible que también necesite asegurarse de que la variable no esté vacía:
$dotenv->required('DATABASE_DSN')->notEmpty();
Si la variable de entorno está vacía, obtendrá una excepción:
One or more environment variables failed assertions: DATABASE_DSN is emptyVariables enteras
También puede necesitar asegurarse de que la variable tiene un valor entero. Puede hacer lo siguiente:
$dotenv->required('FOO')->isInteger();
Si la variable de entorno no es un número entero, obtendrá una Excepción:
One or more environment variables failed assertions: FOO is not an integer.Es posible que sólo quiera aplicar las reglas de validación cuando se establece una variable. Wesupport esto también:
$dotenv->ifPresent('FOO')->isInteger();
Variables booleanas
Puede que necesites asegurar una variable en forma de booleano, aceptando «true», «false», «On», «1», «Yes», «Off», «0» y «No». Puede hacer lo siguiente:
$dotenv->required('FOO')->isBoolean();
Si la variable de entorno no es un booleano, obtendrá una Excepción:
One or more environment variables failed assertions: FOO is not a boolean.De forma similar, se puede escribir:
$dotenv->ifPresent('FOO')->isBoolean();
Valores permitidos
También es posible definir un conjunto de valores que deben tener sus variables de entorno. Esto es especialmente útil en situaciones en las que sólo un puñado de opciones o controladores son realmente soportados por su código:
$dotenv->required('SESSION_STORE')->allowedValues();
Si la variable de entorno no estaba en esta lista de valores permitidos, obtendría una excepción similar:
One or more environment variables failed assertions: SESSION_STORE is not an allowed value.También es posible definir un regex que su variable de entorno debe ser.
$dotenv->required('FOO')->allowedRegexValues('(]{3})');
Puede comentar su archivo .env utilizando el carácter #. E.g.
# this is a commentVAR="value" # commentVAR=value # comment
Parsear sin cargar
A veces sólo quieres parsear el fichero y resolver las variables de entorno anidadas, dándonos una cadena, y que te devuelvan un array. Aunque esto ya es posible, es un poco complicado, por lo que hemos proporcionado una forma directa de hacerlo:
// Dotenv\Dotenv::parse("FOO=Bar\nBAZ=\"Hello ${FOO}\"");
Esto es exactamente lo mismo que:
Dotenv\Dotenv::createArrayBacked(__DIR__)->load();
sólo que, en lugar de proporcionar el directorio para encontrar el archivo, has proporcionado directamente el contenido del archivo.
Notas de uso
Cuando un nuevo desarrollador clona su base de código, tendrá un paso adicional de una sola vez para copiar manualmente el archivo .env.example a .env y rellenar sus propios valores (u obtener cualquier valor sensible de un compañero de proyecto).
Seguridad
Si descubre una vulnerabilidad de seguridad dentro de este paquete, por favor envíe un correo electrónico a Graham Campbell en [email protected]. Todas las vulnerabilidades de seguridad serán abordadas con prontitud. Puede ver nuestra política de seguridad completa aquí.
Licencia
PHP dotenv está licenciado bajo la licencia BSD de 3 cláusulas.
Para empresas
Disponible como parte de la suscripción Tidelift