Carica le variabili d’ambiente da .env a getenv(), $_ENV e $_SERVER automaticamente.
Perché .env? Memorizzare la configurazione nell’ambiente è uno dei principi di un’applicazione a dodici fattori. Tutto ciò che è probabile che cambi tra gli ambienti di distribuzione – come le credenziali del database o le credenziali per i servizi di terze parti – dovrebbe essere estratto dal codice in variabili d’ambiente.
Fondamentalmente, un file .env è un modo semplice per caricare variabili di configurazione personalizzate di cui la vostra applicazione ha bisogno senza dover modificare i file .htaccess o gli host virtuali Apache/nginx. Questo significa che non dovrai modificare nessun file al di fuori del progetto, e che tutte le variabili d’ambiente sono sempre impostate, indipendentemente da come viene eseguito il tuo progetto – Apache, Nginx, CLI, e anche il webserver integrato di PHP. È MOLTO più facile di tutti gli altri modi che conosci per impostare le variabili d’ambiente, e ti piacerà!
- Non modificare gli host virtuali in Apache o Nginx
- Non aggiungere flag
php_valueai file .htaccess - FACILE portabilità e condivisione dei valori ENV richiesti
- COMPATIBILE con il server web integrato di PHP e con il CLI runner
PHP dotenv è una versione PHP dell’originale Rubydotenv.
Installazione
L’installazione è super-facile tramite Composer:
$ composer require vlucas/phpdotenv
o aggiungilo a mano al tuo file composer.json.
Aggiornamento
Seguiamo il versioning semantico, il che significa che possono verificarsi cambiamenti tra le versioni principali. Abbiamo guide all’aggiornamento dalla V2 alla V3, dalla V3 alla V4 e dalla V4 alla V5 disponibili qui.
Uso
Il file .env è generalmente tenuto fuori dal controllo di versione poiché può contenere chiavi API e password sensibili. Un file .env.example separato viene creato con tutte le variabili d’ambiente necessarie definite tranne quelle sensibili, che sono fornite dall’utente per i propri ambienti di sviluppo o comunicate altrove ai collaboratori del progetto. I collaboratori al progetto copiano quindi indipendentemente il file .env.example in un .env locale e si assicurano che tutte le impostazioni siano corrette per il loro ambiente locale, compilando le chiavi segrete o fornendo i propri valori quando necessario. In questo uso, il file .env dovrebbe essere aggiunto al file .gitignore del progetto in modo che non sia mai impegnato dai collaboratori. Questo uso assicura che nessuna password sensibile o chiave API sarà mai nella storia del controllo di versione, quindi c’è meno rischio di una violazione della sicurezza, e i valori di produzione non dovranno mai essere condivisi con tutti i collaboratori del progetto.
Aggiungi la configurazione della tua applicazione a un file .env nella root del tuo progetto. Assicurati che il file .env sia aggiunto al tuo .gitignore in modo che non sia controllato nel codice
S3_BUCKET="dotenv"SECRET_KEY="souper_seekret_key"
Ora crea un file chiamato .env.example e controllalo nel progetto. Questo dovrebbe avere le variabili ENV che avete bisogno di impostare, ma i valori dovrebbero essere vuoti o riempiti con dati fittizi. L’idea è di far sapere alle persone quali variabili sono richieste, ma non dare loro i valori sensibili di produzione.
S3_BUCKET="devbucket"SECRET_KEY="abc123"
Puoi quindi caricare .env nella tua applicazione con:
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);$dotenv->load();
Per sopprimere l’eccezione che viene lanciata quando non c’è un file .env, puoi:
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);$dotenv->safeLoad();
Opzionalmente puoi passare un nome di file come secondo parametro, se vuoi usare qualcosa di diverso da .env:
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__, 'myconfig');$dotenv->load();
Tutte le variabili definite sono ora disponibili nei $_ENV e $_SERVERsuper-global.
$s3_bucket = $_ENV;$s3_bucket = $_SERVER;
Putenv e Getenv
L’uso di getenv() e putenv() è fortemente sconsigliato a causa del fatto che queste funzioni non sono thread safe, tuttavia è ancora possibile istruirePHP dotenv a usare queste funzioni. Invece di chiamareDotenv::createImmutable, si può chiamare Dotenv::createUnsafeImmutable, che aggiungerà PutenvAdapter dietro le quinte. Le vostre variabili d’ambiente saranno ora disponibili usando il metodo getenv, così come le super-globali:
$s3_bucket = getenv('S3_BUCKET');$s3_bucket = $_ENV;$s3_bucket = $_SERVER;
Nesting Variables
È possibile annidare una variabile d’ambiente dentro un’altra, utile per ridurre le ripetizioni.
Questo viene fatto avvolgendo una variabile d’ambiente esistente in ${…}, ad esempio
BASE_DIR="/var/webroot/project-root"CACHE_DIR="${BASE_DIR}/cache"TMP_DIR="${BASE_DIR}/tmp"
Immutabilità e personalizzazione del repository
L’immutabilità si riferisce al fatto che Dotenv può sovrascrivere le variabili d’ambiente esistenti. Se vuoi che Dotenv sovrascriva le variabili d’ambiente esistenti, usa createMutable invece di createImmutable:
$dotenv = Dotenv\Dotenv::createMutable(__DIR__);$dotenv->load();
Dietro le quinte, questo sta istruendo il “repository” a permettere l’immutabilità o no. Per impostazione predefinita, il repository è configurato per permettere la sovrascrittura dei valori esistenti, il che è rilevante se si chiama il metodo “create” usando il RepositoryBuilder per costruire un repository più personalizzato:
$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’esempio precedente scriverà i valori caricati in $_ENV e putenv, ma quando si interpolano le variabili di ambiente, leggeremo solo da $_ENV. Inoltre, non sostituirà mai nessuna variabile già impostata prima di caricare il file.
Con un altro esempio, si può anche specificare un insieme di variabili da non elencare. Cioè, solo le variabili nella lista permessa saranno caricate:
$repository = Dotenv\Repository\RepositoryBuilder::createWithDefaultAdapters() ->allowList() ->make();$dotenv = Dotenv\Dotenv::create($repository, __DIR__);$dotenv->load();
Richiedere che le variabili siano impostate
PHP dotenv ha una funzionalità di validazione incorporata, anche per imporre la presenza di una variabile d’ambiente. Questo è particolarmente utile per far conoscere alle persone qualsiasi variabile esplicitamente richiesta che la vostra applicazione non funzionerà senza.
Puoi usare una singola stringa:
$dotenv->required('DATABASE_DSN');
O un array di stringhe:
$dotenv->required();
Se manca qualche variabile d’ambiente, Dotenv lancerà un RuntimeException come questo:
One or more environment variables failed assertions: DATABASE_DSN is missingVariabili vuote
Oltre a richiedere semplicemente che una variabile sia impostata, potresti anche aver bisogno di assicurarti che la variabile non sia vuota:
$dotenv->required('DATABASE_DSN')->notEmpty();
Se la variabile d’ambiente è vuota, otterrai un’eccezione:
One or more environment variables failed assertions: DATABASE_DSN is emptyVariabili intere
Potresti anche aver bisogno di assicurarti che la variabile abbia un valore intero. Puoi fare come segue:
$dotenv->required('FOO')->isInteger();
Se la variabile d’ambiente non è un intero, otterrai un’eccezione:
One or more environment variables failed assertions: FOO is not an integer.Si potrebbe voler applicare le regole di validazione solo quando una variabile è impostata. Wesupporta anche questo:
$dotenv->ifPresent('FOO')->isInteger();
Variabili booleane
Potreste aver bisogno di assicurarvi che una variabile sia nella forma di un booleano, accettando “true”, “false”, “On”, “1”, “Yes”, “Off”, “0” e “No”. Si può fare come segue:
$dotenv->required('FOO')->isBoolean();
Se la variabile d’ambiente non è un booleano, si otterrà un’eccezione:
One or more environment variables failed assertions: FOO is not a boolean.Similmente, si può scrivere:
$dotenv->ifPresent('FOO')->isBoolean();
Valori consentiti
È anche possibile definire un insieme di valori che le variabili d’ambiente dovrebbero avere. Questo è particolarmente utile in situazioni in cui solo una manciata di opzioni o driver sono effettivamente supportati dal tuo codice:
$dotenv->required('SESSION_STORE')->allowedValues();
Se la variabile d’ambiente non fosse in questa lista di valori consentiti, otterresti un’eccezione simile:
One or more environment variables failed assertions: SESSION_STORE is not an allowed value.È anche possibile definire una regex che la tua variabile d’ambiente dovrebbe essere.
$dotenv->required('FOO')->allowedRegexValues('(]{3})');
Puoi commentare il tuo file .env usando il carattere #. Es.
# this is a commentVAR="value" # commentVAR=value # comment
Parsing Without Loading
A volte vuoi semplicemente analizzare il file e risolvere le variabili d’ambiente annidate, dandoci una stringa, e farti restituire un array. Mentre questo è già possibile, è un po’ complicato, così abbiamo fornito un modo diretto per farlo:
// Dotenv\Dotenv::parse("FOO=Bar\nBAZ=\"Hello ${FOO}\"");
Questo è esattamente lo stesso di:
Dotenv\Dotenv::createArrayBacked(__DIR__)->load();
solo che, invece di fornire la directory per trovare il file, avete fornito direttamente il contenuto del file.
Note d’uso
Quando un nuovo sviluppatore clona il tuo codebase, avrà un ulteriore passo per copiare manualmente il file .env.example in .env e inserire i propri valori (o ottenere qualsiasi valore sensibile da un collega di progetto).
Sicurezza
Se scopri una vulnerabilità di sicurezza in questo pacchetto, invia una email a Graham Campbell a [email protected]. Tutte le vulnerabilità di sicurezza saranno prontamente affrontate. Puoi vedere la nostra politica di sicurezza completa qui.
Licenza
PHP dotenv è concesso in licenza sotto la BSD 3-Clause License.
Per le imprese
Disponibile come parte dell’abbonamento Tidelift