michaelschiemer/docs/livecomponents/README.md

LiveComponents Documentation

Production-Ready Interactive Components for Custom PHP Framework

LiveComponents is a modern, secure, and performant system for building interactive web applications with minimal JavaScript. It combines server-side rendering with client-side interactivity, providing a reactive programming model similar to frameworks like Livewire or Phoenix LiveView.

Features at a Glance

✅ Zero-Config Reactivity - Automatic state synchronization between server and client ✅ Fragment-based Rendering - Update only changed parts of the DOM ✅ Optimistic UI - Instant feedback with automatic rollback on errors ✅ Request Batching - Automatic batching for improved network efficiency ✅ Chunked Uploads - Large file uploads with progress tracking ✅ Real-time Updates - Server-Sent Events (SSE) for live data ✅ Security First - CSRF protection, rate limiting, idempotency keys ✅ Production-Ready - Comprehensive error handling and recovery ✅ Developer Experience - DevTools overlay with performance profiling

Quick Start

1. Basic Component

<?php

namespace App\Application\Components;

use App\Framework\LiveComponents\LiveComponent;
use App\Framework\LiveComponents\Attributes\LiveAction;
use App\Framework\LiveComponents\Attributes\LiveProp;

final class Counter extends LiveComponent
{
    #[LiveProp]
    public int $count = 0;

    #[LiveAction]
    public function increment(): void
    {
        $this->count++;
    }

    #[LiveAction]
    public function decrement(): void
    {
        $this->count--;
    }

    public function render(): string
    {
        return $this->view('components/counter', [
            'count' => $this->count
        ]);
    }
}

2. Template (components/counter.view.php)

<div data-component-id="{component_id}" data-component-name="Counter">
    <h2>Counter: <span data-counter>{count}</span></h2>

    <button data-lc-action="increment">+</button>
    <button data-lc-action="decrement">-</button>
</div>

3. Usage in Controller

<?php

final readonly class HomeController
{
    #[Route(path: '/', method: Method::GET)]
    public function index(): ViewResult
    {
        return new ViewResult('home', [
            'counterComponent' => LiveComponent::mount(Counter::class)
        ]);
    }
}

4. Include in View

<div class="container">
    <h1>Welcome</h1>

    {counterComponent}
</div>

That's it! The counter is now fully interactive with zero JavaScript written.

Documentation Structure

Getting Started

• Installation & Setup - Initial setup and configuration
• Your First Component - Step-by-step tutorial
• Core Concepts - Understanding LiveComponents architecture

Guides

• Security Guide - CSRF, rate limiting, input validation
• Performance Guide - Optimization strategies and best practices
• Advanced Features - Fragments, batching, SSE, optimistic UI
• UI Integration Guide - Tooltips, loading states, dialogs, notifications

Reference

• API Reference - Complete API documentation
• Attributes Reference - All available attributes
• Events Reference - Client-side events and lifecycle

Best Practices

• Component Design - Structuring components
• State Management - Managing component state
• Testing Components - Unit and E2E testing

Troubleshooting

• Common Issues - Solutions to common problems
• Debugging Guide - Tools and techniques
• FAQ - Frequently asked questions

Key Concepts

Server-Side Components

Components are PHP classes that live on the server. State changes trigger re-renders, and only the changed HTML is sent to the client.

Reactive Properties

Properties marked with #[LiveProp] are automatically synchronized between server and client:

#[LiveProp]
public string $searchTerm = '';

#[LiveProp]
public array $filters = [];

Actions

Methods marked with #[LiveAction] can be triggered from the client:

#[LiveAction]
public function search(): void
{
    $this->results = $this->searchService->search($this->searchTerm);
}

Fragment Rendering

Update specific parts of your component without re-rendering everything:

<div data-lc-fragment="results">
    <!-- Only this part updates -->
    <for items="results" as="result">
        <div class="result">{result.title}</div>
    </for>
</div>

Optimistic UI

Provide instant feedback while waiting for server confirmation:

<button data-lc-action="like" data-optimistic="true">
    Like ({likeCount})
</button>

Real-time Updates

Keep components in sync with server-side events:

final class Dashboard extends LiveComponent
{
    #[LiveProp]
    public int $activeUsers = 0;

    public function mount(): void
    {
        $this->enableSse(); // Enable real-time updates
    }
}

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                       Client (Browser)                       │
├─────────────────────────────────────────────────────────────┤
│  LiveComponent.js  │  DevTools  │  DomPatcher  │  SSE Client│
└─────────────────────────────────────────────────────────────┘
                              │
                         HTTP/SSE
                              │
┌─────────────────────────────────────────────────────────────┐
│                    Server (PHP Framework)                    │
├─────────────────────────────────────────────────────────────┤
│  Component Classes  │  State Manager  │  Fragment Renderer  │
│  Action Dispatcher  │  Security Layer │  SSE Update Service │
└─────────────────────────────────────────────────────────────┘

Performance Characteristics

• Initial Render: Server-side, SEO-friendly HTML
• Action Latency: <100ms for simple actions
• Network Efficiency: 80%+ reduction via request batching
• UI Responsiveness: <50ms with optimistic updates
• Memory Usage: ~2MB per component in browser
• Scalability: 1000+ concurrent components per page

Browser Support

• Chrome/Edge: 90+
• Firefox: 88+
• Safari: 14+
• Mobile Safari: 14+
• Mobile Chrome: 90+

Required Features:

• ES2020 JavaScript
• Fetch API
• EventSource (SSE)
• MutationObserver
• Custom Elements (for future enhancements)

Production Checklist

• Enable CSRF protection (automatic)
• Configure rate limiting per component
• Set up idempotency keys for critical actions
• Enable fragment rendering for large components
• Configure request batching thresholds
• Set up SSE for real-time features
• Test error recovery scenarios
• Enable production error logging
• Configure CDN for static assets
• Set up monitoring for component performance

License

This documentation is part of the Custom PHP Framework project.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Security: security@example.com

---

Ready to build? Start with Installation & Setup →