vlucas / phpdotenv

Carrega variáveis de ambiente de .env a getenv(), $_ENV e $_SERVERautomagicamente.

Porque .env?

Você nunca deve armazenar credenciais sensíveis no seu código. Armazenarconfiguração no ambiente é um dos princípios de um aplicativo de doze fatores. Qualquer coisa que possa mudar entre ambientes de implantação – como credenciais de banco de dados ou credenciais para serviços de terceiros – deve ser extraída do código para variáveis de ambiente.

Basicamente, um arquivo .env é uma maneira fácil de carregar variáveis de configuração personalizadas que sua aplicação precisa sem ter que modificar arquivos .htaccess ou hosts virtuaisApache/nginx. Isto significa que você não terá que editar nenhum arquivo fora do projeto, e todas as variáveis de ambiente são sempre definidas não importa como seu projeto é – Apache, Nginx, CLI, e até mesmo o servidor web embutido do PHP. É SEMPRE mais fácil do que todas as outras formas que você conhece de definir variáveis de ambiente, e você vai adorar!

• NO editando hosts virtuais no Apache ou Nginx
• NO adicionando php_value flags para .htaccess files
• Portabilidade fácil e compartilhamento de valores ENV requeridos
• COMPATÍVEL com o servidor web embutido do PHP e o executor CLI

PHP dotenv é uma versão PHP do Rubydotenv original.

Instalação

Instalação é super fácil via Composer:

$ composer require vlucas/phpdotenv

ou adicione-o à mão ao seu composer.json file.

Actualização

Seguimos a versão semântica, o que significa que podem ocorrer mudanças entre as versões principais. Temos guias de atualização disponíveis para V2 a V3, V3 a V4 e V4 a V5 aqui.

Usage

O arquivo .env é geralmente mantido fora do controle de versão, uma vez que ele pode conter chaves API sensíveis e senhas. Um arquivo separado .env.example é criado com todas as variáveis de ambiente necessárias definidas, exceto para os “sensitiveones”, que são fornecidos pelo usuário para seus próprios ambientes de desenvolvimento ou são comunicados em outro lugar aos colaboradores do projeto. O colaborador do projeto copia independentemente o arquivo .env.example para um arquivo local .env e garante que todas as configurações estejam corretas para seu ambiente local, preenchendo as chaves secretas ou fornecendo seus próprios valores quando necessário. Neste uso, o arquivo .env deve ser adicionado ao arquivo .gitignore do projeto para que ele nunca seja comprometido pelos colaboradores. Este uso garante que nenhuma senha sensível ou chaves API estará no histórico de controle de versão, portanto há menos risco de quebra de segurança, e os valores de produção nunca terão que ser compartilhados com todos os colaboradores do projeto.

Adicionar a configuração da sua aplicação a um arquivo .env na raiz do seu projeto. Certifique-se que o ficheiro .env é adicionado ao seu .gitignore para que não seja verificado no código

S3_BUCKET="dotenv"SECRET_KEY="souper_seekret_key"

Crie agora um ficheiro com o nome .env.example e verifique isto no projecto. Isto deve ter as variáveis ENV que você precisa ter definido, mas os valores devem estar em branco ou preenchidos com dados fictícios. A idéia é deixar as pessoas saberem quais variáveis são necessárias, mas não dar-lhes os valores sensíveis de produção.

S3_BUCKET="devbucket"SECRET_KEY="abc123"

Pode então carregar .env na sua aplicação com:

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);$dotenv->load();

Para suprimir a excepção que é lançada quando não há nenhum ficheiro .env, pode:

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);$dotenv->safeLoad();

Pode passar num nome de ficheiro como segundo parâmetro, se quiser usar algo diferente de .env:

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__, 'myconfig');$dotenv->load();

Todas as variáveis definidas estão agora disponíveis em $_ENV e $_SERVERsuper-globals.

$s3_bucket = $_ENV;$s3_bucket = $_SERVER;

Putenv e Getenv

Usar getenv() e putenv() é fortemente desencorajado devido ao facto destas funções não serem seguras para threads, no entanto ainda é possível instruirPHP dotenv para usar estas funções. Ao invés de chamar Dotenv::createImmutable, pode-se chamar Dotenv::createUnsafeImmutable, que adicionará o PutenvAdapter nos bastidores. Suas variáveis de ambiente estarão disponíveis usando o método getenv, assim como os super-globais:

$s3_bucket = getenv('S3_BUCKET');$s3_bucket = $_ENV;$s3_bucket = $_SERVER;

Nesting Variables

É possível aninhar uma variável de ambiente dentro de outra, útil para cortar a repetição.

>

Isso é feito envolvendo uma variável de ambiente existente em ${…} e.g.

BASE_DIR="/var/webroot/project-root"CACHE_DIR="${BASE_DIR}/cache"TMP_DIR="${BASE_DIR}/tmp"

Imitabilidade e Personalização do Repositório

Immutabilidade refere-se a se Dotenv é permitido sobrepor variáveis de ambiente existentes. Se você quiser que Dotenv sobrescreva variáveis de ambiente existentes, use createMutable em vez de createImmutable:

$dotenv = Dotenv\Dotenv::createMutable(__DIR__);$dotenv->load();

Nos bastidores, isto está instruindo o “repositório” a permitir a imutabilidade ou não. Por padrão, o repositório é configurado para permitir sobrescrever valores existentes por padrão, o que é relevante se alguém estiver chamando o método “criar” usando o método RepositoryBuilder para construir um repositório mais 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();

O exemplo acima irá escrever valores carregados para $_ENV e putenv, mas ao interpolar variáveis de ambiente, nós só iremos ler de $_ENV. Além disso, ele nunca substituirá nenhuma variável já definida antes de carregar o arquivo.

Por meio de outro exemplo, pode-se também especificar um conjunto de variáveis a serem permitidas listadas. Ou seja, somente as variáveis na lista de permissão serão carregadas:

$repository = Dotenv\Repository\RepositoryBuilder::createWithDefaultAdapters() ->allowList() ->make();$dotenv = Dotenv\Dotenv::create($repository, __DIR__);$dotenv->load();

Requerendo que as variáveis sejam definidas

PHP dotenv tem incorporado a funcionalidade de validação, inclusive para reforçar a presença de uma variável de ambiente. Isto é particularmente útil para permitir que as pessoas saibam quaisquer variáveis explícitas necessárias que a sua aplicação não irá funcionar sem.

Você pode usar uma única string:

$dotenv->required('DATABASE_DSN');

Or um array de strings:

$dotenv->required();

Se alguma variável ENV estiver faltando, Dotenv lançará um RuntimeException como este:

One or more environment variables failed assertions: DATABASE_DSN is missing

Variáveis Vazias

Além de simplesmente requerer que uma variável seja definida, você também pode precisar garantir que a variável não esteja vazia:

$dotenv->required('DATABASE_DSN')->notEmpty();

Se a variável de ambiente estiver vazia, você pode ter uma Exceção:

One or more environment variables failed assertions: DATABASE_DSN is empty

Variáveis Inteiras

Você também pode precisar garantir que a variável seja de um valor inteiro. Você pode fazer o seguinte:

$dotenv->required('FOO')->isInteger();

Se a variável de ambiente não for um número inteiro, você obteria uma Exceção:

One or more environment variables failed assertions: FOO is not an integer.

Uma pessoa só pode querer impor regras de validação quando uma variável é definida. Wesuporte isso também:

$dotenv->ifPresent('FOO')->isInteger();

Variáveis booleanas

Você pode precisar garantir que uma variável esteja na forma de um booleano, aceitando “true”, “false”, “On”, “1”, “Yes”, “Off”, “0” e “No”. Você pode fazer o seguinte:

$dotenv->required('FOO')->isBoolean();

Se a variável de ambiente não for booleana, você terá uma Exceção:

One or more environment variables failed assertions: FOO is not a boolean.

Simplesmente, pode-se escrever:

$dotenv->ifPresent('FOO')->isBoolean();

Valores Permitidos

Também é possível definir um conjunto de valores que as variáveis de ambiente devem ser. Isto é especialmente útil em situações onde apenas um punhado de opções ou drivers são realmente suportados pelo seu código:

$dotenv->required('SESSION_STORE')->allowedValues();

Se a variável de ambiente não estivesse nesta lista de valores permitidos, você obteria uma Exceção tão similar:

One or more environment variables failed assertions: SESSION_STORE is not an allowed value.

Também é possível definir um regex que a sua variável de ambiente deve ser.

$dotenv->required('FOO')->allowedRegexValues('(]{3})');

Você pode comentar o seu arquivo .env usando o caractere #. E.g.

# this is a commentVAR="value" # commentVAR=value # comment

Parsing Without Loading

Por vezes você só quer analisar o arquivo e resolver as variáveis de ambiente aninhadas, dando-nos uma string, e ter um array de volta para você. Apesar de isso já ser possível, é um pouco complicado, então nós fornecemos uma maneira direta de fazer isso:

// Dotenv\Dotenv::parse("FOO=Bar\nBAZ=\"Hello ${FOO}\"");

Isso é exatamente o mesmo que:

Dotenv\Dotenv::createArrayBacked(__DIR__)->load();

somente, ao invés de fornecer o diretório para encontrar o arquivo, você forneceu diretamente o conteúdo do arquivo.

Notas de Uso

Quando um novo desenvolvedor clona sua base de código, ele terá um passo adicional no tempo para copiar manualmente o arquivo .env.example para .env e preencher seus próprios valores (ou obter qualquer valor sensível de um colega de trabalho do projeto).

Segurança

Se você descobrir uma vulnerabilidade de segurança dentro deste pacote, por favor envie um e-mail para Graham Campbell em [email protected]. Todas as vulnerabilidades de segurança serão prontamente resolvidas. Você pode ver nossa política de segurança completa aqui.

Licença

PHP dotenv é licenciada sob a Licença BSD 3-Clause.

Para Empresas

Disponível como parte da Assinatura Tidelift