michaelschiemer/examples/README.md

# Usage Examples

Praktische Beispiele für verschiedene Framework-Features.

## Verfügbare Examples

### Performance Profiling (`performance-profiling-usage.php`)

Demonstriert die Verwendung des NestedPerformanceTracker für:
- Nested Performance Tracking
- Flamegraph-Visualisierung (Brendan Gregg Format)
- Chrome DevTools Timeline Export
- Performance Budget Validation
- Automatische Bottleneck-Erkennung
- Memory Usage Analysis

**Ausführung**:
```bash
php examples/performance-profiling-usage.php
```

**Generierte Dateien**:
- `tests/tmp/flamegraph.txt` - Flamegraph-Daten für flamegraph.pl
- `tests/tmp/chrome-trace.json` - Chrome DevTools Timeline Format

**Visualisierung**:
```bash
# SVG mit flamegraph.pl generieren
flamegraph.pl tests/tmp/flamegraph.txt > tests/tmp/flamegraph.svg

# In Chrome DevTools öffnen
# 1. Chrome öffnen: chrome://tracing
# 2. Load → tests/tmp/chrome-trace.json auswählen
```

### LiveComponent Performance Profiling (`livecomponent-profiling-usage.php`)

Demonstriert Performance-Profiling für LiveComponents:
- Component Lifecycle Profiling (onMount, onUpdate, action execution)
- Component Render Pipeline Profiling (cache → render → template)
- Nested Template Processor Profiling
- Performance Budget Validation für Components
- Chrome DevTools Timeline für Component-Lifecycle

**Ausführung**:
```bash
php examples/livecomponent-profiling-usage.php
```

**Generierte Dateien**:
- `tests/tmp/livecomponent-trace.json` - Chrome DevTools Timeline für LiveComponents

**Use Cases**:
- Identifizierung langsamer Component Actions
- Optimierung des Render-Pipelines
- Validierung von Performance-Budgets
- Analyse der Template-Verarbeitung
- Lifecycle Hook Performance

### Action Execution Profiling (`action-profiling-usage.php`)

Demonstriert erweiterte Action-Profiling-Funktionen mit ActionProfiler:
- Detaillierte Security-Check-Profiling (CSRF, Authorization, Rate Limiting)
- Parameter Binding Performance Analysis
- Action Execution Metrics (Min, Max, Avg)
- Component Performance Summaries
- System-Wide Performance Reports
- Idempotency Cache Effectiveness Measurement

**Ausführung**:
```bash
php examples/action-profiling-usage.php
```

**Features**:
- Einzelne Action Phase Profiling
- Aggregierte Action Metrics über mehrere Executions
- Component-basierte Performance Summaries
- System-weite Performance Reports
- Idempotency Cache Impact Analysis

**Use Cases**:
- Identifizierung von Security-Check-Overhead
- Parameter Binding Optimization
- Action Execution Performance Monitoring
- Cache Effectiveness Validation
- Production Performance Reporting

### Memory Profiling (`memory-profiling-usage.php`)

Demonstriert erweiterte Memory-Profiling-Funktionen mit MemoryProfiler:
- Memory Hotspot Identification (top memory-consuming operations)
- Memory Leak Detection mit konfigurierbaren Thresholds
- Memory Efficiency Scoring (0-100 scale mit Rating)
- Comprehensive Memory Reports (by category, with hotspots)
- Memory Tracking Over Time mit Trend Analysis
- Memory Budget Validation für kritische Operations
- A/B Comparison für Memory Optimizations

**Ausführung**:
```bash
php examples/memory-profiling-usage.php
```

**Features**:
- Leak-Erkennung mit kumulativer Memory-Tracking
- Efficiency Scoring (Memory vs. Execution Time)
- Budget Violation Reporting
- Trend Analysis (rapidly_growing, stable, decreasing)
- Operation A/B Testing für Optimierungen

**Use Cases**:
- Identifizierung von Memory Hotspots
- Erkennung und Verhinderung von Memory Leaks
- Memory Efficiency Monitoring über Zeit
- Validierung von Memory Budgets in Production
- Vergleich von Memory-Verbrauch zwischen Implementierungen

### DOM Parser (`dom-parser-usage.php`)

Demonstriert die Verwendung des DOM Parser Systems.

**Ausführung**:
```bash
php examples/dom-parser-usage.php
```

### StateManager + LiveComponentState Integration (`tests/debug/test-statemanager-livecomponent-integration.php`)

Demonstriert die Integration von LiveComponentState mit dem Framework's StateManagement-Modul:
- Type-safe State Management für LiveComponents
- Persistent State Storage mit TTL Support
- Atomic State Updates
- Generic Type Parameter System für vollständige Typisierung
- Seamless Integration zwischen Application Layer (LiveComponentState) und Framework Layer (StateManager)
- **NEU**: `LiveComponentStateManager` - Domain-specific wrapper für component-aware API
- **NEU**: `ComponentStateCache` nutzt jetzt StateManager für type-safe caching
- **NEU**: `StateManagerFactory::createForLiveComponents()` für einfache StateManager-Erstellung

**Ausführung**:
```bash
docker exec php php tests/debug/test-statemanager-livecomponent-integration.php
```

**Features**:
- LiveComponentState extends SerializableState für StateManager-Kompatibilität
- ComponentState implements SerializableState für Framework-Cache-Integration
- Vollständige Type Safety: Components behalten konkrete State-Typen (z.B. ShoppingCartState, nicht LiveComponentState)
- IDE Auto-Completion funktioniert für alle domain-spezifischen Properties und Methods
- StateManager mit Generic Type Parameters (@template T of SerializableState)
- Factory Methods für typsichere StateManager-Instanzen
- In-Memory und Cache-based Implementations verfügbar
- **CacheKey Value Object** für type-safe key generation (Format: `{componentName}:{instanceId}`)
- **Comprehensive Test Coverage**: 32 Pest tests validieren die gesamte Integration

**Type Safety Demonstration**:
```php
// Option 1: Direct StateManager usage
$stateManager = InMemoryStateManager::for(ShoppingCartState::class);
$cartState = ShoppingCartState::fromArray([...]);
$stateManager->setState('user-123', $cartState, Duration::fromHours(1));
$retrieved = $stateManager->getState('user-123');
// $retrieved is ShoppingCartState, not mixed or LiveComponentState!

// Option 2: LiveComponentStateManager (NEW - Recommended)
$factory = new StateManagerFactory($cache, $logger);
$stateManager = $factory->createForLiveComponents(
    stateClass: ShoppingCartState::class,
    componentName: 'shopping-cart',
    defaultTtl: Duration::fromHours(24)
);

$manager = new LiveComponentStateManager($stateManager);
$componentId = ComponentId::create('shopping-cart', 'user-123');

// Store with component-aware API
$manager->setComponentState($componentId, $cartState);

// Retrieve - TYPE PRESERVED!
$retrieved = $manager->getComponentState($componentId);
// $retrieved is ShoppingCartState! IDE auto-completion works!
$retrieved->discountCode; // ✅ Works
$retrieved->items;        // ✅ Works

// Atomic updates - race-condition free
$updated = $manager->updateComponentState(
    $componentId,
    fn($cart) => $cart->withDiscountCode('SAVE20', 20)
);

// Statistics
$stats = $manager->getStatistics();
echo "Hit rate: {$stats->hitRate}%\n";
```

**ComponentStateCache Integration** (NEW):
```php
use App\Framework\LiveComponents\Cache\ComponentStateCache;
use App\Framework\LiveComponents\ValueObjects\ComponentId;
use App\Framework\LiveComponents\ValueObjects\ComponentState;

// ComponentStateCache now uses StateManager internally
$cache = new ComponentStateCache($stateManager);

$componentId = ComponentId::create('counter', 'instance-1');
$state = ComponentState::fromArray(['count' => 5]);

// Store with automatic TTL based on component type
$cache->storeWithAutoTTL($componentId, $state, 'counter'); // 5 min TTL
$cache->storeWithAutoTTL($componentId, $state, 'chart');   // 30 min TTL
$cache->storeWithAutoTTL($componentId, $state, 'card');    // 2 hour TTL

// Atomic updates
$updated = $cache->update(
    $componentId,
    fn($s) => ComponentState::fromArray([
        'count' => $s->toArray()['count'] + 1
    ])
);

// CacheKey is used internally: "counter:instance-1"
```

**Integration Benefits**:
- Domain-specific states (ShoppingCartState, CounterState, etc.) können StateManager nutzen
- Persistent state storage mit automatic serialization/deserialization
- TTL support für state expiration
- Atomic updates via StateManager::updateState()
- Performance metrics via StateManager::getStatistics()
- Framework-compliant: readonly, final, Value Object patterns
- Testing: InMemoryStateManager für Unit Tests, CacheBasedStateManager für Production

## Weitere Ressourcen

- **Dokumentation**: `docs/claude/performance-profiling.md`
- **Tests**: `tests/Unit/Framework/Performance/`
- **MCP Integration**: `docs/claude/mcp-integration.md`