michaelschiemer/docs/TEMPLATE-SYSTEM-ANALYSIS.md

# Template System - Analyse & Verbesserungsvorschläge

## Status Quo - Aktuelle Architektur

### Core Components

**1. Template Engine (`Engine.php`)**
- Hauptverantwortlich für Template-Rendering
- Verwendet `TemplateLoader` zum Laden
- Verwendet `TemplateProcessor` zur Verarbeitung
- Smart Caching System (derzeit deaktiviert wegen ForProcessor Issue)
- Performance-Tracking integriert

**2. Template Loader System**
- **Multiple Resolver Strategies**:
  - `DiscoveryResolver` - Automatische Template-Erkennung
  - `TemplateMapResolver` - Mapping-basierte Auflösung
  - `DefaultPathResolver` - Standard-Pfad-Logik
  - `ComponentResolver` - Component-Templates
  - `ControllerResolver` - Controller-spezifische Templates
  - `LayoutResolver` - Layout-Templates

**3. Template Processing Pipeline**
- `TemplateProcessor` - Hauptverarbeitung
- `EnhancedTemplateProcessor` - Erweiterte Features
- `DomComponentService` - DOM-basierte Component-Verarbeitung
- **Viele Prozessoren**:
  - CsrfReplaceProcessor
  - PhpVariableProcessor
  - CommentStripProcessor
  - SwitchCaseProcessor
  - EscapeProcessor
  - DateFormatProcessor
  - SlotProcessor
  - IncludeProcessor
  - RemoveEmptyLinesProcessor
  - usw.

**4. Component System**
- `ComponentRenderer` - Component-Rendering
- `DomComponentService` - DOM-basierte Components
- `ComponentCache` - Component-Caching

**5. Caching System**
- **Multi-Level Caching**:
  - `CacheManager` - Zentrale Cache-Verwaltung
  - `SmartTemplateAnalyzer` - Intelligente Cache-Strategie-Auswahl
  - `FragmentCache` - Fragment-basiertes Caching
  - `TaggedFragmentCache` - Tag-basiertes Cache-Invalidierung
- **Cache Strategies**:
  - `FullPageCacheStrategy`
  - `FragmentCacheStrategy`
  - `ComponentCacheStrategy`
  - `NoCacheStrategy`

**6. Table System**
- Dedicated Table-Rendering System
- `TableBuilder`, `TableProcessor`
- Multiple Formatters (Boolean, Currency, Date, Number, Status, Masked)
- Generators für verschiedene Datentypen

**7. Template Functions**
- `UrlFunction` - URL-Generierung
- `ImageSlotFunction` - Image-Slot-Management

## Aktuelle Template-Syntax

### Platzhalter
```html
{{ variable }}
{{ object.property }}
```

### Kontrollstrukturen
```html
<if condition="{{ variable }}">
    <p>Content when true</p>
</if>

<for items="{{ items }}" as="item">
    <p>{{ item.name }}</p>
</for>

<switch value="{{ status }}">
    <case value="active">Active</case>
    <case value="inactive">Inactive</case>
    <default>Unknown</default>
</switch>
```

### Layouts & Slots
```html
<layout name="layouts/main" />

<slot name="header">
    <h1>Custom Header</h1>
</slot>
```

### Components
```html
<include component="button" props="{{ buttonProps }}" />
```

## Stärken des aktuellen Systems

✅ **Sehr flexibel**
- Multiple Resolver-Strategien
- Umfangreiches Processing-Pipeline
- Component-basierte Architektur

✅ **Performance-optimiert**
- Smart Caching mit verschiedenen Strategien
- Fragment-Caching
- Intelligent Analysis für beste Cache-Strategy

✅ **Feature-reich**
- Table-Rendering System
- Form-Processing
- CSRF-Protection integriert
- Meta-Tag-Management

✅ **Framework-konform**
- Readonly Classes
- Value Objects
- Dependency Injection
- Attribute-basierte Discovery

## Schwächen & Verbesserungspotential

### 1. ❌ Komplexität
**Problem**: Das System ist sehr komplex mit vielen Abstraktionsebenen
- Zu viele Resolver-Strategien
- Zu viele Prozessoren
- Schwer zu verstehen für neue Entwickler

**Lösung**:
- Dokumentation der wichtigsten Flows
- Vereinfachung der Resolver-Chain
- Klare Naming Conventions

### 2. ❌ Caching ist deaktiviert
**Problem**: Smart Caching wegen ForProcessor-Issue deaktiviert
```php
// FORCE DIRECT RENDERING - Bypass all caching to fix ForProcessor issue
return $this->renderDirect($context);
```

**Lösung**:
- ForProcessor Issue identifizieren und fixen
- Smart Caching wieder aktivieren
- Performance-Gewinn durch Caching nutzen

### 3. ❌ Template-Ordnerstruktur unklar
**Problem**: Templates liegen an verschiedenen Stellen
- `src/Framework/View/templates/` - Framework-Templates
- `src/Application/Admin/templates/` - Admin-Templates
- `src/Application/Website/templates/` - Website-Templates (sollte existieren)

**Lösung**:
- Klare Konvention definieren
- Template-Discovery verbessern
- Bessere Namespace-Organisation

### 4. ❌ Fehlende Admin-Form-Patterns
**Problem**: Kein standardisiertes Pattern für CRUD-Forms
- Jeder Controller baut Forms manuell
- Keine Wiederverwendung
- Inkonsistente UX

**Lösung**:
- Admin-Form-Builder erstellen
- CRUD-Template-Pattern definieren
- Form-Validation integrieren

### 5. ❌ Component System unternutzt
**Problem**: Component-System existiert, wird aber wenig genutzt
- Viel Duplicate Code in Templates
- Keine UI-Component-Library

**Lösung**:
- Wiederverwendbare UI-Components erstellen
- Component-Library aufbauen
- Storybook-ähnliche Übersicht

### 6. ❌ Template-Syntax inkonsistent
**Problem**: Mix aus verschiedenen Syntaxen
- Manchmal `{{ }}` Platzhalter
- Manchmal DOM-Tags `<if>`, `<for>`
- Verwirrend für Entwickler

**Lösung**:
- Einheitliche Syntax definieren
- Migration-Guide erstellen
- Linting-Rules für Templates

## Verbesserungsvorschläge - Priorisiert

### 🎯 Phase 1: Grundlagen stabilisieren (Jetzt)

**1. ForProcessor Issue fixen**
- Debug-Logs analysieren
- Issue identifizieren und beheben
- Smart Caching wieder aktivieren

**2. Template-Konventionen dokumentieren**
- Template-Ordnerstruktur definieren
- Naming Conventions festlegen
- Resolver-Priority-Chain dokumentieren

**3. Admin-Template-Patterns**
- Generic CRUD-Templates erstellen
- Form-Builder-Pattern implementieren
- Index/Create/Edit/Show-Templates

### 🚀 Phase 2: Admin-System modernisieren

**1. Admin-Form-Builder**
```php
final readonly class AdminFormBuilder
{
    public function buildForm(string $entity, array $fields, ?object $data = null): array
    {
        return [
            'fields' => $this->buildFields($fields, $data),
            'actions' => $this->buildActions($entity),
            'validation' => $this->buildValidation($fields),
            'csrf_token' => $this->generateCsrfToken()
        ];
    }
}
```

**2. CRUD-Templates**
```
templates/admin/crud/
├── index.view.php     # List view with table
├── create.view.php    # Create form
├── edit.view.php      # Edit form
├── show.view.php      # Detail view
└── components/
    ├── form-field.view.php
    ├── table-row.view.php
    └── action-buttons.view.php
```

**3. Table-Builder Integration**
- Bestehenden TableBuilder nutzen
- Admin-spezifische Table-Formatters
- Pagination & Sorting

### 🎨 Phase 3: Component Library

**1. UI-Components erstellen**
```
components/
├── buttons/
│   ├── primary-button.view.php
│   ├── secondary-button.view.php
│   └── danger-button.view.php
├── forms/
│   ├── text-input.view.php
│   ├── select-input.view.php
│   └── checkbox-input.view.php
├── cards/
│   ├── card.view.php
│   ├── card-header.view.php
│   └── card-body.view.php
└── alerts/
    ├── success-alert.view.php
    ├── error-alert.view.php
    └── warning-alert.view.php
```

**2. Component-Usage-Pattern**
```html
<component name="button" type="primary" size="large">
    Save Campaign
</component>

<component name="form/text-input"
    name="title"
    label="Campaign Title"
    value="{{ campaign.title }}"
    required="true" />
```

### ⚡ Phase 4: Performance & DX

**1. Template-Caching optimieren**
- Smart Cache wieder aktivieren
- Cache-Warmup-Strategy
- Development-Mode ohne Cache

**2. Developer Experience**
- Template-Syntax-Highlighting
- VS Code Extension für Templates
- Template-Linting
- Hot-Reload für Template-Änderungen

**3. Testing**
- Template-Unit-Tests
- Component-Tests
- Visual Regression Tests

## Konkrete Nächste Schritte

### Sofort (Diese Session):

1. **ForProcessor Issue analysieren**
   ```bash
   tail -f /tmp/debug.log
   # Logs während Template-Rendering beobachten
   ```

2. **Admin-Form-Builder Prototype**
   - PreSave Campaign Forms als Beispiel
   - Generic Form-Builder-Klasse
   - Admin-CRUD-Templates

3. **Template-Konventionen dokumentieren**
   - Wo welche Templates liegen
   - Naming Conventions
   - Best Practices

### Nächste Session:

4. **Component Library starten**
   - Basic UI Components
   - Wiederverwendbare Form-Fields
   - Alert/Message Components

5. **Caching-System reparieren**
   - ForProcessor debuggen
   - Smart Cache aktivieren
   - Performance-Tests

### Langfristig:

6. **Template-Syntax vereinheitlichen**
7. **Developer Tools**
8. **Visual Regression Testing**

## Empfehlung für Pre-Save System

**Sofort umsetzbar**:
1. Generic Admin-CRUD-Templates erstellen
2. Diese für Pre-Save Campaign Admin nutzen
3. Public Template für Landing Page mit Component-Pattern

**Code-Beispiel - Admin-Form-Builder Integration**:
```php
// In PreSaveCampaignAdminController
public function create(): ViewResult
{
    $formBuilder = new AdminFormBuilder();

    $form = $formBuilder->buildForm('presave-campaign', [
        ['name' => 'title', 'type' => 'text', 'required' => true],
        ['name' => 'artist_name', 'type' => 'text', 'required' => true],
        ['name' => 'cover_image_url', 'type' => 'url', 'required' => true],
        ['name' => 'description', 'type' => 'textarea'],
        ['name' => 'release_date', 'type' => 'date', 'required' => true],
        ['name' => 'track_urls', 'type' => 'repeatable', 'fields' => [
            ['name' => 'platform', 'type' => 'select', 'options' => ['spotify', 'apple_music']],
            ['name' => 'url', 'type' => 'text']
        ]]
    ]);

    return new ViewResult('admin/crud/create', [
        'title' => 'Create Pre-Save Campaign',
        'form' => $form,
        'resource' => 'presave-campaigns'
    ]);
}
```

## Fazit

Das Template-System ist sehr mächtig, aber:
- ❌ Zu komplex für einfache Use-Cases
- ❌ Caching deaktiviert (Performance-Loss)
- ❌ Fehlende Standards für Admin-Forms
- ✅ Gute Basis für Verbesserungen

**Next Action**: Admin-Form-Builder + CRUD-Templates implementieren, dann Pre-Save System darauf aufbauen.