dockerfluxodecaixapro/rules/07_ENVIRONMENT_USAGE.md

Uso do Symfony Dotenv no SysCMS

Este documento explica como utilizar o sistema de variáveis de ambiente implementado com Symfony Dotenv no projeto SysCMS.

🚀 Dica Rápida: Se você está instalando o SysCMS pela primeira vez, utilize o Instalador Web (/install). Ele criará o arquivo .env automaticamente para você com base no .env.example.

Arquivos Principais

1. app/Helpers/Environment.php

Helper centralizado que fornece funções para carregar e acessar variáveis de ambiente.

2. .env

Arquivo que contém as variáveis de ambiente específicas do projeto (senhas, chaves de API, configurações locais). Nunca versione este arquivo!

3. .env.example

Modelo das variáveis necessárias. Este arquivo é versionado e serve como base para criar o .env.

4. bootstrap/app.php

Ponto de entrada onde o ambiente é carregado automaticamente.

Funções Disponíveis

load_env(?string $path = null): void

Carrega as variáveis de ambiente do arquivo .env. É chamado automaticamente na inicialização da aplicação.

get_env(string $key, $default = null)

Obtém uma variável de ambiente com valor padrão.

$dbHost = get_env('DB_HOST', 'localhost');
$appName = get_env('APP_NAME', 'SysCMS');

env(string $key, $default = null)

Alias para get_env() para manter compatibilidade.

$debug = env('APP_DEBUG', false);

env_bool(string $key, bool $default = false): bool

Obtém uma variável de ambiente como booleano.

$debug = env_bool('APP_DEBUG', false);
$cacheEnabled = env_bool('CACHE_ENABLED', true);

env_int(string $key, int $default = 0): int

Obtém uma variável de ambiente como inteiro.

$port = env_int('DB_PORT', 3306);
$timeout = env_int('TIMEOUT', 30);

get_db_config(): array

Retorna um array com a configuração do banco de dados completa.

$config = get_db_config();
// [
//     'driver' => 'mysql',
//     'host' => 'localhost',
//     'port' => '3306',
//     'database' => 'syscms',
//     'username' => 'root',
//     'password' => 'root',
//     'charset' => 'utf8mb4',
//     'collation' => 'utf8mb4_unicode_ci',
//     'prefix' => ''
// ]

get_app_config(): array

Retorna um array com a configuração da aplicação.

$config = get_app_config();
// [
//     'name' => 'SysCMS',
//     'env' => 'development',
//     'debug' => true,
//     'url' => 'http://localhost:16240',
//     'timezone' => 'America/Sao_Paulo',
//     'key' => '...'
// ]

get_mail_config(): array

Retorna um array com a configuração de email.

$config = get_mail_config();
// [
//     'transport' => 'smtp',
//     'host' => 'sandbox.smtp.mailtrap.io',
//     'port' => '2525',
//     'username' => '...',
//     'password' => '...',
//     'encryption' => 'tls',
//     'from_address' => '...',
//     'from_name' => 'SysCMS'
// ]

Exemplos de Uso

Em Controllers

<?php

namespace App\Controllers;

class ExampleController
{
    public function index()
    {
        $debugMode = env_bool('APP_DEBUG', false);
        $appName = get_env('APP_NAME', 'SysCMS');
        
        if ($debugMode) {
            echo "Modo debug ativado para {$appName}";
        }
        
        // Usar configuração do banco
        $dbConfig = get_db_config();
        $capsule = new \Illuminate\Database\Capsule\Manager;
        $capsule->addConnection($dbConfig);
    }
}

Em Models

<?php

namespace App\Models;

class UserModel
{
    public function getConnectionConfig()
    {
        return get_db_config();
    }
    
    public function isDebugMode()
    {
        return env_bool('APP_DEBUG', false);
    }
}

Em Scripts Independentes

<?php

require_once __DIR__ . '/vendor/autoload.php';
require_once __DIR__ . '/app/Helpers/Environment.php';

// Carregar ambiente manualmente
load_env();

// Usar variáveis
$dbConfig = get_db_config();
$appConfig = get_app_config();

echo "Banco de dados: " . $dbConfig['database'] . "\n";
echo "Aplicação: " . $appConfig['name'] . "\n";

Variáveis de Ambiente Disponíveis

Banco de Dados

• DB_CONNECTION ou DB_DRIVER: Driver do banco (mysql, pgsql, sqlite)
• DB_HOST: Host do banco de dados
• DB_PORT: Porta do banco de dados
• DB_DATABASE: Nome do banco de dados
• DB_USERNAME: Usuário do banco
• DB_PASSWORD: Senha do banco

Aplicação

• APP_NAME: Nome da aplicação
• APP_ENV: Ambiente (development, production, testing)
• APP_DEBUG: Modo debug (true/false)
• APP_URL: URL base da aplicação
• APP_KEY: Chave de criptografia
• APP_TIMEZONE: Fuso horário

Email

• MAIL_TRANSPORT: Tipo de transporte (smtp, mail, sendmail)
• MAIL_HOST: Host SMTP
• MAIL_PORT: Porta SMTP
• MAIL_USERNAME: Usuário SMTP
• MAIL_PASSWORD: Senha SMTP
• MAIL_ENCRYPTION: Criptografia (tls, ssl)
• MAIL_FROM_ADDRESS: Email de remetente
• MAIL_FROM_NAME: Nome do remetente

Boas Práticas

1. Nunca commitar o arquivo .env no controle de versão.
2. Sempre fornecer valores padrão ao usar get_env().
3. Usar funções tipadas (env_bool(), env_int()) quando possível.
4. Utilizar os getters de configuração (get_db_config(), get_app_config()) para obter configurações completas.
5. Documentar variáveis personalizadas no arquivo .env.example.

Compatibilidade

O helper foi implementado para ser compatível com a versão v3.0.3 do Symfony Dotenv instalada no projeto, utilizando a sintaxe new Dotenv() em vez de Dotenv::createImmutable() que está disponível apenas em versões mais recentes.