O que são Variáveis de Ambiente?
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.
O phpdotenv é uma biblioteca PHP que carrega variáveis de um arquivo .env (texto simples) para o $_ENV e $_SERVER. 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.
Instalação e Configuração Básica
Instalando o phpdotenv
Use o Composer para instalar a biblioteca:
composer require vlucas/phpdotenv
Criando seu arquivo .env
Crie um arquivo .env na raiz do seu projeto:
APP_NAME=MeuApp
APP_DEBUG=true
DB_HOST=localhost
DB_USER=root
DB_PASSWORD=senha123
DB_NAME=meu_banco
API_KEY=abc123def456
Importante: adicione .env ao .gitignore para nunca commitá-lo no repositório. Crie um arquivo .env.example com as mesmas chaves mas valores dummy para documentar quais variáveis são necessárias.
Carregando as variáveis
<?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
O método createImmutable() cria uma instância que não permite sobrescrita de variáveis já definidas no sistema, oferecendo segurança adicional. A chamada load() lê o arquivo .env e popula o ambiente.
Casos de Uso Avançados
Validação de Variáveis Obrigatórias
<?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']);
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.
Múltiplos Arquivos .env
<?php
require_once 'vendor/autoload.php';
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__, [
'.env',
'.env.local',
'.env.' . getenv('APP_ENV')
]);
$dotenv->load();
Isso permite estruturas como .env.production, .env.testing que sobrescrevem valores do .env base quando necessário.
Casting de Tipos
<?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);
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.
Exemplo Prático Completo
<?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]);
Arquivo .env:
DB_HOST=localhost
DB_USER=root
DB_PASSWORD=minha_senha
DB_NAME=producao_db
Dessa forma, sua classe de banco de dados nunca tem credenciais hardcoded, e você pode manter arquivos .env diferentes em cada servidor.
Conclusão
Ao dominar o phpdotenv, você adquire três competências essenciais: segurança (credenciais nunca no código), portabilidade (mesma aplicação, ambientes diferentes) e profissionalismo (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.