Charge les variables d’environnement de .env à getenv(), $_ENV et $_SERVER automatiquement.
Pourquoi .env?
Vous ne devriez jamais stocker des informations d’identification sensibles dans votre code. Le stockage de la configuration dans l’environnement est l’un des principes d’une application à douze facteurs. Tout ce qui est susceptible de changer entre les environnements de déploiement – comme les informations d’identification de la base de données ou les informations d’identification pour les services tiers – doit être extrait du code dans des variables d’environnement.
Basiquement, un fichier .env est un moyen facile de charger les paramètres de configuration personnalisés dont votre application a besoin sans avoir à modifier les fichiers .htaccess ou les hôtes virtuels Apache/nginx. Cela signifie que vous n’aurez pas à éditer de fichiers en dehors du projet, et que toutes les variables d’environnement seront toujours définies, quel que soit le type de votre projet – Apache, Nginx, CLI, et même le serveur web intégré de PHP. C’est BEAUCOUP plus facile que toutes les autres façons que vous connaissez pour définir les variables d’environnement, et vous allez l’adorer !
- NO éditant les hôtes virtuels dans Apache ou Nginx
- NO ajoutant des drapeaux
php_valueaux fichiers .htaccess - Portabilité aisée et partage des valeurs ENV requises
- COMPATIBLE avec le serveur web intégré de PHP et le CLI runner
PHP dotenv est une version PHP du Rubydotenv original.
Installation
L’installation est super facile via Composer:
$ composer require vlucas/phpdotenv
ou l’ajouter à la main à votre fichier composer.json.
Mise à niveau
Nous suivons le versionnement sémantique, ce qui signifie que des breakingchanges peuvent se produire entre les versions majeures. Nous avons des guides de mise à niveau disponibles pour V2 à V3, V3 à V4 et V4 à V5 disponibles ici.
Utilisation
Le fichier .env est généralement maintenu hors du contrôle de version car il peut contenir des clés API et des mots de passe sensibles. Un fichier .env.example distinct est créé avec toutes les variables d’environnement requises définies, à l’exception des variables sensibles, qui sont soit fournies par les utilisateurs pour leurs propres environnements de développement, soit communiquées ailleurs aux collaborateurs du projet. Les collaborateurs du projet copient alors indépendamment le fichier .env.example sur un .env local et s’assurent que tous les paramètres sont corrects pour leur environnement local, en remplissant les clés secrètes ou en fournissant leurs propres valeurs si nécessaire. Dans cette utilisation, le fichier .env doit être ajouté au fichier .gitignore du projet afin qu’il ne soit jamais validé par les collaborateurs. Cette utilisation garantit qu’aucun mot de passe sensible ou clé API ne sera jamais dans l’historique de contrôle de version, il y a donc moins de risque de faille de sécurité, et les valeurs de production n’auront jamais à être partagées avec tous les collaborateurs du projet.
Ajouter la configuration de votre application à un fichier .env à la racine de votreprojet. Assurez-vous que le fichier .env est ajouté à votre .gitignore afin qu’il ne soit pas vérifié dans le code
S3_BUCKET="dotenv"SECRET_KEY="souper_seekret_key"
Créez maintenant un fichier nommé .env.example et vérifiez-le dans le projet. Ce fichier devrait contenir les variables ENV que vous devez avoir définies, mais les valeurs devraient être soit vides, soit remplies de données factices. L’idée est de faire savoir aux gens quelles variables sont nécessaires, mais de ne pas leur donner les valeurs de production sensibles.
S3_BUCKET="devbucket"SECRET_KEY="abc123"
Vous pouvez alors charger .env dans votre application avec:
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);$dotenv->load();
Pour supprimer l’exception qui est levée lorsqu’il n’y a pas de fichier .env, vous pouvez :
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);$dotenv->safeLoad();
Optionnellement, vous pouvez passer un nom de fichier comme deuxième paramètre, si vous souhaitez utiliser autre chose que .env:
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__, 'myconfig');$dotenv->load();
Toutes les variables définies sont maintenant disponibles dans les $_ENV et $_SERVERsuper-globales.
$s3_bucket = $_ENV;$s3_bucket = $_SERVER;
Putenv et Getenv
L’utilisation de getenv() et putenv() est fortement déconseillée en raison du fait que ces fonctions ne sont pas thread safe, cependant il est toujours possible de demander àPHP dotenv d’utiliser ces fonctions. Au lieu d’appelerDotenv::createImmutable, on peut appeler Dotenv::createUnsafeImmutable, qui ajoutera le PutenvAdapter en coulisse. Vos variables d’environnement seront maintenant disponibles en utilisant la méthode getenv, ainsi que les super-globales:
$s3_bucket = getenv('S3_BUCKET');$s3_bucket = $_ENV;$s3_bucket = $_SERVER;
Imbrication de variables
Il est possible d’imbriquer une variable d’environnement dans une autre, utile pour couper les répétitions.
Cela se fait en enveloppant une variable d’environnement existante dans ${…} par exemple.
BASE_DIR="/var/webroot/project-root"CACHE_DIR="${BASE_DIR}/cache"TMP_DIR="${BASE_DIR}/tmp"
Immutabilité et personnalisation du référentiel
L’immutabilité fait référence au fait de savoir si Dotenv est autorisé à écraser les variables d’environnement existantes. Si vous voulez que Dotenv écrase les variables d’environnement existantes,utilisez createMutable au lieu de createImmutable:
$dotenv = Dotenv\Dotenv::createMutable(__DIR__);$dotenv->load();
Dans les coulisses, il s’agit d’instruire le « référentiel » pour permettre l’immutabilitéou non. Par défaut, le référentiel est configuré pour permettre l’écrasement des valeurs existantes, ce qui est pertinent si l’on appelle la méthode « create » utilisant le RepositoryBuilder pour construire un référentiel plus personnalisé:
$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();
L’exemple ci-dessus écrira les valeurs chargées dans $_ENV et putenv, mais lors de l’interpolation des variables d’environnement, nous ne lirons que dans $_ENV. De plus, il ne remplacera jamais les variables déjà définies avant le chargement du fichier.
A l’aide d’un autre exemple, on peut aussi spécifier un ensemble de variables à lister. C’est-à-dire que seules les variables de la liste autorisée seront chargées :
$repository = Dotenv\Repository\RepositoryBuilder::createWithDefaultAdapters() ->allowList() ->make();$dotenv = Dotenv\Dotenv::create($repository, __DIR__);$dotenv->load();
Exiger que les variables soient définies
PHP dotenv a intégré une fonctionnalité de validation, notamment pour imposer la présence d’une variable d’environnement. Ceci est particulièrement utile pour faire connaître toute variable requise explicite sans laquelle votre application ne fonctionnera pas.
Vous pouvez utiliser une seule chaîne de caractères:
$dotenv->required('DATABASE_DSN');
Ou un tableau de chaînes de caractères:
$dotenv->required();
Si des vars ENV sont manquantes, Dotenv lancera un RuntimeException comme ceci :
One or more environment variables failed assertions: DATABASE_DSN is missingVariables vides
Au delà de simplement exiger qu’une variable soit définie, vous pourriez aussi avoir besoin de vous assurer que la variable n’est pas vide :
$dotenv->required('DATABASE_DSN')->notEmpty();
Si la variable d’environnement est vide, vous obtiendrez une Exception:
One or more environment variables failed assertions: DATABASE_DSN is emptyVariables entières
Vous pourriez également avoir besoin de vous assurer que la variable a une valeur entière. Vous pouvez faire ce qui suit:
$dotenv->required('FOO')->isInteger();
Si la variable d’environnement n’est pas un nombre entier, vous obtiendrez une Exception:
One or more environment variables failed assertions: FOO is not an integer.On peut vouloir appliquer les règles de validation uniquement lorsqu’une variable est définie. Wesupport ceci aussi:
$dotenv->ifPresent('FOO')->isInteger();
Variables booléennes
Vous pouvez avoir besoin de vous assurer qu’une variable est sous la forme d’un booléen, acceptant « true », « false », « On », « 1 », « Yes », « Off », « 0 » et « No ». Vous pouvez faire ce qui suit:
$dotenv->required('FOO')->isBoolean();
Si la variable d’environnement n’est pas un booléen, vous obtiendrez une Exception:
One or more environment variables failed assertions: FOO is not a boolean.De même, on peut écrire:
$dotenv->ifPresent('FOO')->isBoolean();
Valeurs autorisées
Il est également possible de définir un ensemble de valeurs que vos variables d’environnement devraient avoir. Ceci est particulièrement utile dans les situations où seulement une poignée d’options ou de pilotes sont réellement supportés par votre code:
$dotenv->required('SESSION_STORE')->allowedValues();
Si la variable d’environnement n’était pas dans cette liste de valeurs autorisées, vous obtiendriez une Exception similaire:
One or more environment variables failed assertions: SESSION_STORE is not an allowed value.Il est également possible de définir une regex que votre variable d’environnement devrait être.
$dotenv->required('FOO')->allowedRegexValues('(]{3})');
Vous pouvez commenter votre fichier .env en utilisant le caractère #. E.g.
# this is a commentVAR="value" # commentVAR=value # comment
Parsing Without Loading
Parfois vous voulez juste parser le fichier et résoudre les variables d’environnement imbriquées, en nous donnant une chaîne, et avoir un tableau retourné vers vous. Bien que cela soit déjà possible, c’est un peu laborieux, donc nous avons fourni un moyen direct de le faire:
// Dotenv\Dotenv::parse("FOO=Bar\nBAZ=\"Hello ${FOO}\"");
C’est exactement la même chose que:
Dotenv\Dotenv::createArrayBacked(__DIR__)->load();
seulement, au lieu de fournir le répertoire pour trouver le fichier, vous avez directement fourni le contenu du fichier.
Notes d’utilisation
Lorsqu’un nouveau développeur clone votre base de code, il aura une étape supplémentaire ponctuelle pour copier manuellement le fichier .env.example vers .env et remplir ses propres valeurs (ou obtenir toute valeur sensible d’un collègue du projet).
Sécurité
Si vous découvrez une vulnérabilité de sécurité dans ce paquet, veuillez envoyer un courriel à Graham Campbell à [email protected]. Toutes les vulnérabilités de sécurité seront rapidement traitées. Vous pouvez consulter notre politique de sécurité complète ici.
Licence
PHP dotenv est sous licence BSD 3-Clause License.
For Enterprise
Disponible dans le cadre de l’abonnement Tidelift
.