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.

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

### `env(string $key, $default = null)`
Alias para `get_env()` para manter compatibilidade.

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

### `env_bool(string $key, bool $default = false): bool`
Obtém uma variável de ambiente como booleano.

```php
$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.

```php
$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.

```php
$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.

```php
$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.

```php
$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
<?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
<?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
<?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.