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

{{ variable }}
{{ object.property }}

Kontrollstrukturen

<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

<layout name="layouts/main" />

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

Components

<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

// 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

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

<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

   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:

// 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.