Laadt omgevingsvariabelen van .env naar getenv(), $_ENV en $_SERVER automagisch.
Waarom .env?
Je moet nooit gevoelige informatie in je code opslaan. Het opslaan van configuratie in de omgeving is een van de grondbeginselen van een twaalf-factor app. Alles wat waarschijnlijk zal veranderen tussen implementatie-omgevingen – zoals databasegegevens of referenties voor services van derden – moet uit de code worden gehaald in omgevingsvariabelen.
In principe is een .env-bestand een eenvoudige manier om aangepaste configuratievariabelen te laden die uw toepassing nodig heeft zonder dat u .htaccess-bestanden of Apache/nginx virtuele hosts hoeft te wijzigen. Dit betekent dat je geen bestanden buiten het project hoeft aan te passen, en alle omgevingsvariabelen zijn altijd ingesteld, ongeacht hoe je je project opstart – Apache, Nginx, CLI, en zelfs PHP’s ingebouwde webserver. Het is VEEL makkelijker dan alle andere manieren die je kent om omgevingsvariabelen in te stellen, en je zult het geweldig vinden!
- NO het bewerken van virtuele hosts in Apache of Nginx
- NO het toevoegen van
php_valuevlaggen aan .htaccess bestanden - EASY portability and sharing of required ENV values
- COMPATIBLE met PHP’s ingebouwde web server en CLI runner
PHP dotenv is een PHP versie van de originele Rubydotenv.
Installatie
Installatie is super-eenvoudig via Composer:
$ composer require vlucas/phpdotenv
of voeg het met de hand toe aan uw composer.json bestand.
Upgraden
We volgen semantische versionering, wat betekent dat er breukwijzigingen kunnen optreden tussen grote releases. We hebben opwaarderingsgidsen beschikbaar voor V2 naar V3, V3 naar V4 en V4 naar V5.
Gebruik
Het .env bestand wordt over het algemeen buiten versiebeheer gehouden omdat het gevoelige API sleutels en wachtwoorden kan bevatten. Een apart .env.example bestand wordt aangemaakt met alle benodigde omgevingsvariabelen, behalve de gevoelige, die ofwel door de gebruiker worden aangeleverd voor hun eigen ontwikkelomgeving of elders worden meegedeeld aan projectmedewerkers. De projectmedewerkers kopiëren vervolgens onafhankelijk het .env.example-bestand naar een lokale .env en zorgen ervoor dat alle instellingen correct zijn voor hun lokale omgeving, door de geheime sleutels in te vullen of hun eigen waarden te geven indien nodig. Bij dit gebruik moet het .env-bestand worden toegevoegd aan het .gitignore-bestand van het project, zodat het nooit zal worden vastgelegd door medewerkers. Dit gebruik zorgt ervoor dat er nooit gevoelige wachtwoorden of API sleutels in de versie beheer geschiedenis komen te staan, zodat er minder risico is op een inbreuk op de beveiliging, en productiewaarden nooit gedeeld hoeven te worden met alle project medewerkers.
Voeg uw applicatie configuratie toe aan een .env bestand in de root van uw project. Zorg ervoor dat het .env bestand is toegevoegd aan uw .gitignore zodat het niet wordt gecontroleerd in de code
S3_BUCKET="dotenv"SECRET_KEY="souper_seekret_key"
Maak nu een bestand aan met de naam .env.example en controleer dit in het project. Dit zou de ENV variabelen moeten bevatten die je ingesteld moet hebben, maar de waarden zouden of leeg moeten zijn of gevuld met dummy data. Het idee is om mensen te laten weten welke variabelen nodig zijn, maar ze niet de gevoelige productiewaarden te geven.
S3_BUCKET="devbucket"SECRET_KEY="abc123"
U kunt .env vervolgens in uw toepassing laden met:
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);$dotenv->load();
Om de uitzondering te onderdrukken die wordt gegooid wanneer er geen .env-bestand is, kunt u:
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);$dotenv->safeLoad();
Optioneel kunt u een bestandsnaam als tweede parameter opgeven, als u iets anders wilt gebruiken dan .env:
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__, 'myconfig');$dotenv->load();
Alle gedefinieerde variabelen zijn nu beschikbaar in de $_ENV en $_SERVERsuper-globals.
$s3_bucket = $_ENV;$s3_bucket = $_SERVER;
Putenv en Getenv
Het gebruik van getenv() en putenv() wordt sterk afgeraden omdat deze functies niet thread safe zijn, het is echter nog steeds mogelijk om PHP dotenv te instrueren deze functies te gebruiken. In plaats van Dotenv::createImmutable aan te roepen, kunt u Dotenv::createUnsafeImmutable aanroepen, die de PutenvAdapter achter de schermen zal toevoegen. Uw omgevingsvariabelen zullen nu beschikbaar zijn via de getenv methode, evenals de super-globals:
$s3_bucket = getenv('S3_BUCKET');$s3_bucket = $_ENV;$s3_bucket = $_SERVER;
Nesting Variabelen
Het is mogelijk om een omgevingsvariabele in een andere te nesten, handig om herhalingen te verminderen.
Dit wordt gedaan door een bestaande omgevingsvariabele te wikkelen in ${…} bijv.
BASE_DIR="/var/webroot/project-root"CACHE_DIR="${BASE_DIR}/cache"TMP_DIR="${BASE_DIR}/tmp"
Onveranderlijkheid en Repository Customization
Onveranderlijkheid heeft betrekking op de vraag of Dotenv bestaande omgevingsvariabelen mag overschrijven. Als u wilt dat Dotenv bestaande omgevingsvariabelen overschrijft, gebruik dan createMutable in plaats van createImmutable:
$dotenv = Dotenv\Dotenv::createMutable(__DIR__);$dotenv->load();
Achter de schermen is dit het instrueren van de “repository” om immutability toe te staan of niet. Standaard is het archief geconfigureerd om het overschrijven van bestaande waarden toe te staan, wat relevant is als men de “create” methode aanroept door gebruik te maken van de RepositoryBuilder om een meer aangepast archief te construeren:
$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();
Het bovenstaande voorbeeld zal geladen waarden schrijven naar $_ENV en putenv, maar bij het interpoleren van omgevingsvariabelen, zullen we alleen lezen van $_ENV. Bovendien zal het nooit variabelen vervangen die al waren ingesteld voordat het bestand werd geladen.
Met behulp van een ander voorbeeld, kan men ook een set variabelen opgeven die niet mogen worden vermeld. Dat wil zeggen dat alleen de variabelen op de lijst met toegestane variabelen worden geladen:
$repository = Dotenv\Repository\RepositoryBuilder::createWithDefaultAdapters() ->allowList() ->make();$dotenv = Dotenv\Dotenv::create($repository, __DIR__);$dotenv->load();
Vereisen dat variabelen zijn ingesteld
PHP dotenv heeft validatiefunctionaliteit ingebouwd, onder andere voor het afdwingen van de aanwezigheid van een omgevingsvariabele. Dit is vooral nuttig om mensen te laten weten welke variabelen expliciet vereist zijn en zonder welke uw app niet zal werken.
U kunt een enkele string gebruiken:
$dotenv->required('DATABASE_DSN');
Of een array van strings:
$dotenv->required();
Als er ENV-vars ontbreken, zal Dotenv een RuntimeException als volgt afgeven:
One or more environment variables failed assertions: DATABASE_DSN is missingLege variabelen
Naast het feit dat een variabele moet zijn ingesteld, moet u er misschien ook voor zorgen dat de variabele niet leeg is:
$dotenv->required('DATABASE_DSN')->notEmpty();
Als de omgevingsvariabele leeg is, krijgt u een Exception:
One or more environment variables failed assertions: DATABASE_DSN is emptyInteger Variables
U moet er misschien ook voor zorgen dat de variabele een gehele waarde heeft. U kunt het volgende doen:
$dotenv->required('FOO')->isInteger();
Als de omgevingsvariabele geen geheel getal is, krijgt u een Exception:
One or more environment variables failed assertions: FOO is not an integer.Het kan zijn dat u alleen validatieregels wilt afdwingen als een variabele is ingesteld. Wesupport dit ook:
$dotenv->ifPresent('FOO')->isInteger();
Booleaanse variabelen
Het kan nodig zijn om ervoor te zorgen dat een variabele de vorm heeft van een booleaans, waarbij “true”, “false”, “On”, “1”, “Yes”, “Off”, “0” en “No” worden geaccepteerd. U kunt het volgende doen:
$dotenv->required('FOO')->isBoolean();
Als de omgevingsvariabele geen booleaans is, krijgt u een Exception:
One or more environment variables failed assertions: FOO is not a boolean.Op dezelfde manier kunt u schrijven:
$dotenv->ifPresent('FOO')->isBoolean();
Toegestane waarden
Het is ook mogelijk om een set waarden te definiëren die uw omgevingsvariabelen zouden moeten hebben. Dit is vooral nuttig in situaties waarin slechts een handvol opties of stuurprogramma’s daadwerkelijk door uw code worden ondersteund:
$dotenv->required('SESSION_STORE')->allowedValues();
Als de omgevingsvariabele niet in deze lijst van toegestane waarden voorkomt, krijgt u een soortgelijke Uitzondering:
One or more environment variables failed assertions: SESSION_STORE is not an allowed value.Het is ook mogelijk om een regex te definiëren die uw omgevingsvariabele zou moeten zijn.
$dotenv->required('FOO')->allowedRegexValues('(]{3})');
U kunt uw .env bestand becommentariëren met het # teken. Bv.
# this is a commentVAR="value" # commentVAR=value # comment
Parsing Without Loading
Soms wilt u gewoon het bestand parsen en de geneste omgevingsvariabelen oplossen, door ons een string te geven, en een array naar u teruggestuurd te krijgen. Hoewel dit al mogelijk is, is het een beetje omslachtig, dus hebben we een directe manier om dit te doen:
// Dotenv\Dotenv::parse("FOO=Bar\nBAZ=\"Hello ${FOO}\"");
Dit is precies hetzelfde als:
Dotenv\Dotenv::createArrayBacked(__DIR__)->load();
alleen, in plaats van de directory op te geven om het bestand te vinden, hebt u direct de inhoud van het bestand opgegeven.
Gebruiksaanwijzingen
Wanneer een nieuwe ontwikkelaar uw codebase kloont, moet hij het .env.example-bestand handmatig naar .env kopiëren en zijn eigen waarden invullen (of gevoelige waarden van een projectmedewerker krijgen).
Beveiliging
Als u een beveiligingslek in dit pakket ontdekt, stuur dan een e-mail naar Graham Campbell op [email protected]. Alle veiligheidslekken zullen onmiddellijk worden aangepakt. U kunt ons volledige beveiligingsbeleid hier bekijken.
Licentie
PHP dotenv is gelicenseerd onder The BSD 3-Clause License.
Voor Enterprise
Beschikbaar als onderdeel van het Tidelift Abonnement