Em aplicações modernas, a configuração é um aspecto crucial: precisamos de credenciais de banco de dados, chaves de API, tokens de autenticação e outros parâmetros que variam entre ambientes (desenvolvimento, teste, produção). Armazenar essas informações diretamente no código é uma péssima prática, pois dificulta a manutenção e compromete a segurança. A solução é usar variáveis de ambiente, que permitem separar a configuração do código e adaptar o comportamento da aplicação sem alterar o código-fonte.

Nesta aula, você aprenderá a trabalhar com variáveis de ambiente em PHP, desde a criação de arquivos .env até o uso de funções nativas e bibliotecas populares. Também discutiremos boas práticas para gerenciar segredos e garantir que sua aplicação seja segura e flexível.

.env (visão geral)

O arquivo .env é um formato simples de texto que define variáveis de ambiente em pares CHAVE=VALOR. Ele é amplamente usado em frameworks como Laravel, Symfony e em projetos que seguem a metodologia de configuração baseada em ambiente. A ideia é que cada ambiente (desenvolvimento, staging, produção) tenha seu próprio arquivo .env ou que as variáveis sejam injetadas pelo próprio servidor (como no Docker ou em serviços de nuvem).

No PHP, o arquivo .env não é carregado automaticamente pelo interpretador; é necessário usar uma biblioteca como vlucas/phpdotenv para ler o arquivo e popular as variáveis de ambiente do sistema. Essa biblioteca é o padrão em projetos PHP modernos e oferece recursos como tratamento de variáveis obrigatórias, suporte a comentários e preservação de valores com espaços.

Exemplo de um arquivo .env básico:

APP_NAME=MeuApp
APP_ENV=local
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=meu_banco
DB_USERNAME=root
DB_PASSWORD=segredo123

Para usar esse arquivo em seu projeto, você pode instalar a biblioteca via Composer:

composer require vlucas/phpdotenv

E carregá-la no início do seu script:

require 'vendor/autoload.php';

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

Após carregar, todas as variáveis definidas no arquivo estarão disponíveis por meio de getenv(), $_ENV e $_SERVER (dependendo da configuração). A biblioteca também permite criar variáveis imutáveis (que não podem ser sobrescritas) e exigir que certas variáveis estejam presentes, lançando exceções caso não existam.

getenv

A função getenv() é a forma nativa do PHP para obter o valor de uma variável de ambiente. Ela retorna o valor da variável ou false se ela não estiver definida. Você pode passar o nome da variável como parâmetro ou chamar sem parâmetros para obter um array com todas as variáveis de ambiente.

Exemplos de uso:

$dbHost = getenv('DB_HOST');
if ($dbHost === false) {
    echo "Variável DB_HOST não definida";
} else {
    echo "Host: $dbHost";
}

// Obtém todas as variáveis de ambiente
$todas = getenv();
print_r($todas);

É importante notar que getenv() pode não funcionar em alguns ambientes como Apache CGI, dependendo das configurações do servidor. Nesses casos, você pode usar $_ENV ou $_SERVER. O comportamento também pode ser afetado pela diretiva variables_order no php.ini, que define quais superglobals são populadas.

Ao usar a biblioteca phpdotenv, você pode configurar quais superglobals serão preenchidas. Por exemplo, para popular também $_ENV, você pode usar o método createImmutable e depois chamar $dotenv->safeLoad() ou $dotenv->load(); por padrão, a biblioteca preenche $_ENV e $_SERVER. No entanto, a prática recomendada é usar getenv() ou um wrapper como env() para acessar as variáveis, pois isso evita conflitos com variáveis do servidor.

Veja um exemplo completo com tratamento de valores booleanos e numéricos:

$debug = getenv('APP_DEBUG');
if ($debug === 'true') {
    $debug = true;
} else {
    $debug = false;
}

$port = (int) getenv('DB_PORT');
echo "Debug: " . var_export($debug, true) . "\n";
echo "Porta: $port\n";

Para facilitar, muitas aplicações criam funções auxiliares como env() que retornam um valor padrão se a variável não existir:

function env($key, $default = null) {
    $value = getenv($key);
    if ($value === false) {
        return $default;
    }
    return $value;
}

Segredos

Segredos são informações confidenciais que não devem ser expostas em repositórios de código ou logs. Exemplos incluem senhas de banco de dados, chaves de API, tokens de autenticação e chaves de criptografia. O arquivo .env deve ser adicionado ao .gitignore para que não seja versionado, e você deve fornecer um arquivo de exemplo .env.example com valores fictícios para que outros desenvolvedores saibam quais variáveis são necessárias.

Além de proteger o arquivo, é crucial não exibir segredos em respostas HTTP, logs ou mensagens de erro. Use funções como error_log() com cuidado e evite fazer var_dump() de arrays que contenham segredos. Em ambientes de produção, é comum usar serviços de gerenciamento de segredos (como AWS Secrets Manager, HashiCorp Vault) ou variáveis de ambiente definidas no nível do servidor, em vez de um arquivo .env.

Para ilustrar, um exemplo de como acessar uma chave de API:

$apiKey = getenv('API_KEY');
if (!$apiKey) {
    throw new Exception('API_KEY não configurada');
}
// Usa a chave para fazer uma requisição
$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.exemplo.com/dados', [
    'headers' => [
        'Authorization' => "Bearer $apiKey"
    ]
]);

Nunca coloque a chave real no código ou em logs. Se você estiver usando um framework como Laravel, ele já possui mecanismos para proteger variáveis sensíveis e criptografar dados.

Outra prática é usar arquivos .env.local para configurações locais que não são compartilhadas com a equipe, e .env.production para produção. O phpdotenv permite carregar diferentes arquivos conforme o ambiente, mas o mais comum é usar o mesmo nome e deixar que o servidor defina as variáveis reais.

Boas práticas

Para manter sua aplicação segura e fácil de configurar, siga estas boas práticas:

  • Nunca versionar o arquivo .env: adicione .env ao .gitignore e crie um .env.example com valores fictícios.
  • Defina um valor padrão: ao acessar uma variável, sempre forneça um valor padrão ou trate a ausência da variável, para evitar erros em ambientes de teste.
  • Valide as variáveis obrigatórias: use a biblioteca phpdotenv com o método required() para garantir que variáveis críticas existam.
  • Use nomes consistentes: defina um padrão de nomenclatura (ex.: DB_HOST, APP_DEBUG) e documente no .env.example.
  • Evite usar $_ENV diretamente: prefira getenv() ou uma função auxiliar, pois $_ENV pode não ser populado dependendo da configuração do PHP.
  • Não exponha segredos em logs: configure o nível de log e evite registrar valores de variáveis sensíveis.
  • Use criptografia quando necessário: para dados muito sensíveis, considere usar serviços de gerenciamento de segredos.

Exemplo de validação com phpdotenv:

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();
$dotenv->required(['DB_HOST', 'DB_PORT', 'DB_DATABASE', 'DB_USERNAME', 'DB_PASSWORD'])->notEmpty();

Isso lançará uma exceção se alguma dessas variáveis estiver ausente ou vazia, evitando que a aplicação rode com configuração incorreta.

Referências

Exercícios

  1. Explique por que é importante usar variáveis de ambiente em vez de hardcoded no código. Dê dois exemplos de situações em que isso facilita a manutenção da aplicação.

    ✓ Resposta: Variáveis de ambiente permitem que a mesma base de código rode em diferentes ambientes sem alterações. Por exemplo, a string de conexão com o banco de dados muda entre desenvolvimento e produção; usar variáveis evita modificar o código. Outro exemplo: chaves de API para serviços externos podem ser diferentes por ambiente, e colocá-las no código seria um risco de segurança.

  2. Crie um script PHP que leia uma variável de ambiente chamada APP_ENV e imprima uma mensagem diferente se o valor for 'production' ou outro. Use getenv() e forneça um valor padrão 'development'.

    ✓ Resposta: 
    $env = getenv('APP_ENV') ?: 'development';
if ($env === 'production') {
    echo "Estamos em produção!";
} else {
    echo "Ambiente: $env";
}

  3. Escreva um exemplo de arquivo .env.example para uma aplicação que usa banco de dados e um serviço de envio de e-mail. Inclua pelo menos 6 variáveis, com comentários explicativos.

    ✓ Resposta: 
    # Configuração do aplicativo
APP_NAME=MeuApp
APP_ENV=local
APP_DEBUG=true

# Banco de dados
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=meu_banco
DB_USERNAME=root
DB_PASSWORD=

# E-mail
MAIL_DRIVER=smtp
MAIL_HOST=smtp.mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=tls

  4. Descreva pelo menos três boas práticas para gerenciar segredos em uma aplicação PHP. Cite uma ferramenta ou técnica para cada uma.

    ✓ Resposta:
    • Nunca versionar o .env: adicione ao .gitignore e use .env.example como referência.
    • Usar serviços de gerenciamento de segredos: AWS Secrets Manager, HashiCorp Vault, ou variáveis de ambiente do provedor de hospedagem.
    • Rotacionar segredos periodicamente: agendar a troca de chaves e senhas.
    • Limitar o acesso: conceder permissões mínimas para cada serviço.

  5. Considere o seguinte trecho de código que carrega um arquivo .env com phpdotenv. O que acontece se a variável DB_PASSWORD não estiver definida no arquivo? Como você pode garantir que ela será obrigatória?

    require 'vendor/autoload.php';
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();

    ✓ Resposta: Se DB_PASSWORD não estiver definida, getenv('DB_PASSWORD') retornará false, e a aplicação pode falhar em tempo de execução. Para torná-la obrigatória, use o método required: 
    $dotenv->required('DB_PASSWORD')->notEmpty();
    Isso lançará uma exceção se a variável não existir ou estiver vazia, forçando a configuração correta antes de prosseguir.

Observações Finais

Nesta aula, você aprendeu a importância de configurar aplicações PHP com variáveis de ambiente e como usar arquivos .env para separar a configuração do código. A função getenv() é a ferramenta nativa para acessar essas variáveis, enquanto a biblioteca phpdotenv simplifica o carregamento de arquivos .env. Lembre-se sempre de proteger segredos e seguir boas práticas de segurança, como não versionar arquivos sensíveis e validar variáveis obrigatórias. Com essas técnicas, suas aplicações estarão prontas para diferentes ambientes e mais seguras.