<h2>O que são Variáveis de Ambiente?</h2>
<p>Variáveis de ambiente são pares chave-valor armazenados no sistema operacional que sua aplicação pode acessar em tempo de execução. Em vez de hardcodear credenciais, URLs de bancos de dados ou chaves de API diretamente no código, você as armazena externamente. Isso garante segurança, portabilidade entre ambientes (desenvolvimento, teste, produção) e conformidade com boas práticas como a metodologia 12-factor app.</p>
<p>O phpdotenv é uma biblioteca PHP que carrega variáveis de um arquivo <code>.env</code> (texto simples) para o <code>$_ENV</code> e <code>$_SERVER</code>. Ele elimina a necessidade de configurar variáveis no servidor web e permite que seu código permaneça limpo e seguro. É amplamente usado em projetos Laravel, Symfony e aplicações standalone.</p>
<h2>Instalação e Configuração Básica</h2>
<h3>Instalando o phpdotenv</h3>
<p>Use o Composer para instalar a biblioteca:</p>
<pre><code class="language-bash">composer require vlucas/phpdotenv</code></pre>
<h3>Criando seu arquivo .env</h3>
<p>Crie um arquivo <code>.env</code> na raiz do seu projeto:</p>
<pre><code>APP_NAME=MeuApp
APP_DEBUG=true
DB_HOST=localhost
DB_USER=root
DB_PASSWORD=senha123
DB_NAME=meu_banco
API_KEY=abc123def456</code></pre>
<p><strong>Importante</strong>: adicione <code>.env</code> ao <code>.gitignore</code> para nunca commitá-lo no repositório. Crie um arquivo <code>.env.example</code> com as mesmas chaves mas valores dummy para documentar quais variáveis são necessárias.</p>
<h3>Carregando as variáveis</h3>
<pre><code class="language-php"><?php
require_once 'vendor/autoload.php';
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();
// Acessando variáveis
echo $_ENV['APP_NAME']; // MeuApp
echo $_ENV['DB_HOST']; // localhost</code></pre>
<p>O método <code>createImmutable()</code> cria uma instância que não permite sobrescrita de variáveis já definidas no sistema, oferecendo segurança adicional. A chamada <code>load()</code> lê o arquivo <code>.env</code> e popula o ambiente.</p>
<h2>Casos de Uso Avançados</h2>
<h3>Validação de Variáveis Obrigatórias</h3>
<pre><code class="language-php"><?php
require_once 'vendor/autoload.php';
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();
// Garantir que variáveis críticas existem
$dotenv->required(['DB_HOST', 'DB_USER', 'API_KEY'])->notEmpty();
// Com mensagens customizadas
$dotenv->required('DB_PASSWORD')->notEmpty()->allowedValues(['senha123', 'outra_senha']);</code></pre>
<p>Esse padrão previne erros silenciosos: se uma variável obrigatória estiver faltando ou vazia, uma exceção é lançada imediatamente, facilitando o debug.</p>
<h3>Múltiplos Arquivos .env</h3>
<pre><code class="language-php"><?php
require_once 'vendor/autoload.php';
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__, [
'.env',
'.env.local',
'.env.' . getenv('APP_ENV')
]);
$dotenv->load();</code></pre>
<p>Isso permite estruturas como <code>.env.production</code>, <code>.env.testing</code> que sobrescrevem valores do <code>.env</code> base quando necessário.</p>
<h3>Casting de Tipos</h3>
<pre><code class="language-php"><?php
require_once 'vendor/autoload.php';
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();
// O phpdotenv retorna strings; você deve fazer conversão
$debug = getenv('APP_DEBUG') === 'true'; // bool
$port = (int) getenv('DB_PORT'); // int
$timeout = (float) getenv('REQUEST_TIMEOUT'); // float
// Ou usar ternário para defaults
$max_connections = (int) (getenv('MAX_CONNECTIONS') ?: 10);</code></pre>
<p>Lembre-se: variáveis de ambiente sempre são strings. PHP não faz conversão automática, então o casting é responsabilidade do desenvolvedor.</p>
<h2>Exemplo Prático Completo</h2>
<pre><code class="language-php"><?php
// config/database.php
require_once __DIR__ . '/../vendor/autoload.php';
$dotenv = Dotenv\Dotenv::createImmutable(dirname(__DIR__));
$dotenv->load();
$dotenv->required(['DB_HOST', 'DB_USER', 'DB_NAME'])->notEmpty();
class DatabaseConnection {
private $host;
private $user;
private $password;
private $database;
private $connection;
public function __construct() {
$this->host = getenv('DB_HOST');
$this->user = getenv('DB_USER');
$this->password = getenv('DB_PASSWORD');
$this->database = getenv('DB_NAME');
}
public function connect() {
try {
$this->connection = new PDO(
"mysql:host={$this->host};dbname={$this->database}",
$this->user,
$this->password,
[PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]
);
return true;
} catch (PDOException $e) {
echo "Erro de conexão: " . $e->getMessage();
return false;
}
}
public function query($sql, $params = []) {
$stmt = $this->connection->prepare($sql);
$stmt->execute($params);
return $stmt->fetchAll(PDO::FETCH_ASSOC);
}
}
// Uso
$db = new DatabaseConnection();
$db->connect();
$users = $db->query("SELECT * FROM users WHERE id = ?", [1]);</code></pre>
<p><strong>Arquivo .env:</strong></p>
<pre><code>DB_HOST=localhost
DB_USER=root
DB_PASSWORD=minha_senha
DB_NAME=producao_db</code></pre>
<p>Dessa forma, sua classe de banco de dados nunca tem credenciais hardcoded, e você pode manter arquivos <code>.env</code> diferentes em cada servidor.</p>
<h2>Conclusão</h2>
<p>Ao dominar o phpdotenv, você adquire três competências essenciais: <strong>segurança</strong> (credenciais nunca no código), <strong>portabilidade</strong> (mesma aplicação, ambientes diferentes) e <strong>profissionalismo</strong> (seguindo padrões da indústria). A biblioteca é simples mas poderosa — validação de variáveis e suporte a múltiplos arquivos eliminam 90% dos problemas comuns. Comece sempre validando variáveis obrigatórias e use casting explícito para tipos não-string.</p>
<h2>Referências</h2>
<ul>
<li><a href="https://github.com/vlucas/phpdotenv" target="_blank" rel="noopener noreferrer">Documentação Oficial - vlucas/phpdotenv</a></li>
<li><a href="https://12factor.net/config" target="_blank" rel="noopener noreferrer">The Twelve-Factor App - Configuration</a></li>
<li><a href="https://www.php.net/manual/en/function.getenv.php" target="_blank" rel="noopener noreferrer">PHP: getenv() - Manual Oficial</a></li>
<li><a href="https://www.php-fig.org/psr/psr-12/" target="_blank" rel="noopener noreferrer">PSR-12: Extended Coding Style Guide</a></li>
<li><a href="https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html" target="_blank" rel="noopener noreferrer">OWASP: Secrets Management</a></li>
</ul>