How pixeleecode/impulse works
Project type and purpose
• This is an open-source, full-stack micro-framework (“Impulse”) combining PHP (backend) and JavaScript (frontend) to build reactive, component-driven UIs without a heavy frontend stack.
• It exposes a tiny JS runtime (public/impulse.js) that turns annotated DOM elements into AJAX-driven, stateful PHP components.
Main architectural layers
A. Client (Browser)
• UI components annotated with impulse:* attributes
• The impulse.js runtime attaches listeners, serializes events, and applies partial DOM updates.
B. AJAX Gateway
• public/impulse.php (or your app’s symlink) is the single endpoint that receives all component requests.
C. PHP Core
1. Front controller: loads composer autoloader, reads impulse/config.json
2. ImpulseFactory → Instantiate the requested Component class (src/Components or user namespace)
3. Component Resolver / Config (src/Core/ComponentResolver, Config)
4. State & Method Collections (src/Collections) manage component state, queued actions, watchers
5. Handler Layer (src/Core/Handler/AjaxDispatcher) invokes the PHP method annotated #[Action]
6. Renderer Layer (src/Rendering/BladeRenderer, TwigRenderer or inline from Component::template())
7. Response Builder: packages the updated HTML fragment and any metadata as JSON
D. Optional Extensibility Points
• Custom renderers via bin/impulse make:renderer → implement TemplateRendererInterface
• CLI commands for scaffolding (src/Commands/MakeRendererCommand, RendererConfigureCommand)
• Configurable template engine (Twig, Blade, etc.)
How these components interact (data flow)
1. User triggers event in browser (e.g., click, input) → impulse.js captures it
2. JS sends AJAX POST to /public/impulse.php with: component identifier, current state, action name, args
3. PHP gateway loads ImpulseFactory → resolves component class → hydrates state
4. AjaxDispatcher invokes the action method → mutates component state
5. Renderer re-renders only the DOM fragment marked data-impulse-part
6. JSON response returns new HTML snippet (plus any instruction tokens)
7. impulse.js receives JSON → patches the DOM fragment in place
Key architectural patterns and principles
• Component-based: each PHP class extends Core\Component, encapsulating state, actions, template, and style
• Partial rendering: “DOM diffless” updates by replacing only marked fragments
• Dependency inversion & extensibility: TemplateRendererInterface abstracts the rendering engine
• Single-responsibility: Handler, Resolver, Factory, Renderer each do one thing
Essential elements
• Extensibility: “Custom Renderer” implements TemplateRendererInterface