michaelschiemer/docs/guides/configuration.md

# Configuration Best Practices

Leitlinien für effektives Configuration Management im Custom PHP Framework.

## Problem: .env Bloat

**Symptom**: Zunehmende Anzahl von Environment-Variablen in `.env.example`

**Negative Auswirkungen**:
- Schwer zu überschauen, welche Variablen wirklich wichtig sind
- Viele Parameter, die Entwickler nie ändern werden
- Unklare Defaults für optionale Parameter
- Erhöhter Wartungsaufwand

## Lösung: Sensible Defaults + Minimal Configuration

### Prinzip 1: "Convention over Configuration"

**Regel**: Nur Werte, die Entwickler WIRKLICH ändern müssen oder wollen, gehören in `.env`

**Gute .env Kandidaten**:
- ✅ Credentials (DB_PASSWORD, API_KEYS)
- ✅ Umgebungs-spezifische Werte (APP_ENV, APP_URL)
- ✅ Infrastruktur-Konfiguration (DB_HOST, REDIS_HOST)
- ✅ Feature Toggles für Production (APP_DEBUG)

**Schlechte .env Kandidaten**:
- ❌ Performance Tuning Parameter (CACHE_TTL=60)
- ❌ Interne Framework-Defaults (CACHE_SIZE=100)
- ❌ Rarely Changed Feature Flags (FEATURE_ENABLED=true)
- ❌ Debug-only Flags (VERBOSE_LOGGING=false)

### Prinzip 2: Sensible Defaults im Code

**Vor der Refaktorierung** (4 .env Variablen):
```env
FILESYSTEM_VALIDATOR_CACHE=true          # Rarely disabled
FILESYSTEM_VALIDATOR_CACHE_TTL=60       # Never changed
FILESYSTEM_VALIDATOR_CACHE_SIZE=100     # Never changed
FILESYSTEM_STORAGE_CACHE=true           # Rarely disabled
```

**Nach der Refaktorierung** (1 .env Variable):
```env
# Filesystem Performance (caching enabled by default)
# Set to true only for debugging performance issues
# FILESYSTEM_DISABLE_CACHE=false
```

**Im Code** (FilesystemInitializer.php):
```php
// Sensible defaults hardcoded
$disableCache = filter_var($_ENV['FILESYSTEM_DISABLE_CACHE'] ?? 'false', FILTER_VALIDATE_BOOLEAN);

if ($disableCache) {
    return $validator;
}

return new CachedFileValidator(
    validator: $validator,
    cacheTtl: 60,        // Sensible default: 1 minute
    maxCacheSize: 100    // Sensible default: 100 entries
);
```

**Vorteile**:
- ✅ 75% weniger .env Variablen (4 → 1)
- ✅ Klarere Intention: "disable only for debugging"
- ✅ Production-optimized by default
- ✅ Einfacher für neue Entwickler

### Prinzip 3: Opt-Out statt Opt-In für Performance

**Schlechtes Pattern** (Opt-In):
```env
FEATURE_CACHE=false  # Muss explizit aktiviert werden
```
→ Entwickler vergessen es zu aktivieren → Performance-Probleme

**Gutes Pattern** (Opt-Out):
```env
# FEATURE_DISABLE_CACHE=false  # Caching standardmäßig aktiv
```
→ Production-optimiert by default → Explizit deaktivieren nur für Debugging

### Prinzip 4: Gruppierung und Kommentare

**Schlechtes Beispiel**:
```env
CACHE_ENABLED=true
CACHE_TTL=60
CACHE_SIZE=100
DB_CACHE=true
FILE_CACHE=true
API_CACHE=true
```

**Gutes Beispiel**:
```env
# Cache System (optimized by default)
# Disable only for debugging: DISABLE_ALL_CACHES=true
# DISABLE_ALL_CACHES=false

# Database-specific cache tuning (advanced)
# DB_CACHE_TTL=3600
```

## Refactoring-Strategie

### Schritt 1: Identifiziere "Never Changed" Parameter

Prüfe in der Codebase:
```bash
# Suche nach $_ENV usage
grep -r "ENV\['" src/

# Identifiziere Parameter, die nie geändert werden
# Kandidaten für Hardcoding
```

### Schritt 2: Extrahiere Sensible Defaults

**Vor**:
```php
$ttl = (int) ($_ENV['CACHE_TTL'] ?? 60);
$size = (int) ($_ENV['CACHE_SIZE'] ?? 100);
```

**Nach**:
```php
// Sensible defaults based on production experience
const DEFAULT_CACHE_TTL = 60;    // 1 minute
const DEFAULT_CACHE_SIZE = 100;  // 100 entries

$ttl = self::DEFAULT_CACHE_TTL;
$size = self::DEFAULT_CACHE_SIZE;
```

### Schritt 3: Konsolidiere Related Flags

**Vor** (3 separate flags):
```env
FILESYSTEM_VALIDATOR_CACHE=true
FILESYSTEM_STORAGE_CACHE=true
FILESYSTEM_CACHE_CLEARSTATCACHE=true
```

**Nach** (1 master flag):
```env
# FILESYSTEM_DISABLE_CACHE=false
```

**Im Code**:
```php
$disableCache = filter_var($_ENV['FILESYSTEM_DISABLE_CACHE'] ?? 'false', FILTER_VALIDATE_BOOLEAN);

// Affects all filesystem caching
$useValidatorCache = !$disableCache;
$useStorageCache = !$disableCache;
$optimizeClearstatcache = !$disableCache;
```

### Schritt 4: Dokumentiere Advanced Tuning

Für Experten, die wirklich tunen wollen:

```php
// Advanced tuning (usually not needed)
$ttl = (int) ($_ENV['FILESYSTEM_VALIDATOR_CACHE_TTL'] ?? 60);
$size = (int) ($_ENV['FILESYSTEM_VALIDATOR_CACHE_SIZE'] ?? 100);
```

**In Dokumentation** (nicht in .env.example):
```markdown
## Advanced Configuration

For expert performance tuning, these environment variables can be used:

- `FILESYSTEM_VALIDATOR_CACHE_TTL`: Cache TTL in seconds (default: 60)
- `FILESYSTEM_VALIDATOR_CACHE_SIZE`: Max cache entries (default: 100)

⚠️ **Warning**: Only change these if you have measured performance issues.
```

## Entscheidungsbaum

```
Braucht diese Variable in .env?
│
├─ Ist es eine Credential? → ✅ JA
├─ Ist es umgebungs-spezifisch (dev/prod)? → ✅ JA
├─ Muss es für Production geändert werden? → ✅ JA
├─ Wird es von Entwicklern oft geändert? → ✅ JA
│
└─ Ansonsten:
   ├─ Ist es ein Performance Tuning Parameter? → ❌ NEIN (Sensible Default im Code)
   ├─ Ist es ein internes Detail? → ❌ NEIN (Hardcode im Code)
   ├─ Ist es ein Debug Flag? → ⚠️ MAYBE (Opt-Out Pattern erwägen)
   └─ Ist es ein Feature Toggle? → ⚠️ MAYBE (Convention over Configuration)
```

## .env Organisation

### Empfohlene Struktur

```env
# ============================================================
# CORE APPLICATION
# ============================================================
APP_ENV=development
APP_DEBUG=true
APP_URL=https://localhost

# ============================================================
# DATABASE
# ============================================================
DB_HOST=db
DB_PORT=5432
DB_DATABASE=michaelschiemer
DB_USERNAME=postgres
DB_PASSWORD=your_secure_password

# ============================================================
# EXTERNAL SERVICES
# ============================================================
SPOTIFY_CLIENT_ID=your_client_id
SPOTIFY_CLIENT_SECRET=your_client_secret

# ============================================================
# PERFORMANCE & DEBUGGING (optimized by default)
# ============================================================
# Uncomment only for debugging:
# FILESYSTEM_DISABLE_CACHE=false
# DISABLE_QUERY_LOG=false
# VERBOSE_ERROR_PAGES=false
```

## Beispiele aus dem Framework

### ✅ Gutes Beispiel: Filesystem Performance

**Vorher** (4 Variablen):
```env
FILESYSTEM_VALIDATOR_CACHE=true
FILESYSTEM_VALIDATOR_CACHE_TTL=60
FILESYSTEM_VALIDATOR_CACHE_SIZE=100
FILESYSTEM_STORAGE_CACHE=true
```

**Nachher** (1 Variable):
```env
# FILESYSTEM_DISABLE_CACHE=false
```

**Einsparung**: 75% weniger Variablen, gleiche Funktionalität

### ❌ Anti-Pattern: Zu granulare Konfiguration

```env
# DON'T DO THIS
ENABLE_USER_CACHE=true
USER_CACHE_TTL=60
USER_CACHE_SIZE=100
ENABLE_POST_CACHE=true
POST_CACHE_TTL=120
POST_CACHE_SIZE=200
ENABLE_COMMENT_CACHE=true
COMMENT_CACHE_TTL=30
COMMENT_CACHE_SIZE=50
```

**Besser**:
```env
# Cache System (enabled by default with sensible defaults)
# DISABLE_ALL_CACHES=false
```

**Im Code** (wenn wirklich Tuning nötig):
```php
// Expert tuning available via environment, but not advertised
$userCacheTtl = (int) ($_ENV['USER_CACHE_TTL'] ?? 60);
$postCacheTtl = (int) ($_ENV['POST_CACHE_TTL'] ?? 120);
```

## Zusammenfassung

**Goldene Regel**: Jede .env Variable muss rechtfertigen, warum sie NICHT ein Sensible Default im Code sein kann.

**Checklist für neue .env Variablen**:
- [ ] Ist es eine Credential oder Secret? → .env
- [ ] Ist es umgebungs-spezifisch? → .env
- [ ] Ändern Entwickler es regelmäßig? → .env
- [ ] Ist es ein Performance Parameter? → Sensible Default im Code
- [ ] Ist es ein Debug Flag? → Opt-Out Pattern (commented out in .env.example)
- [ ] Ist es ein internes Detail? → Hardcode im Code, nicht konfigurierbar

**Ergebnis**: Übersichtliche .env.example, production-optimized by default, trotzdem flexibel für Experten.