IncludeTracker

The IncludeTracker transforms standard PHP include operations into structured components. It wraps the output in an identifiable container (<div pp-component="...">) and handles prop extraction, bridging the gap between server-side rendering and client-side reactivity.

Concept

When you render a file using this tracker, it doesn't just dump the HTML. It creates a "boundary" around that content. This boundary allows the PulsePoint frontend to target, update, or hydrate that specific section of the page independently.

API Reference

static render(string $filePath, array $props = [], string $mode = 'include_once'): void

1. File Path: Absolute or relative path to the PHP file.

2. Props: Associative array of data. These are:

Extracted into the file's local scope (e.g., ['title' => 'Hi'] becomes $title).
Injected as HTML attributes on the wrapper div for frontend access.

3. Mode: Standard PHP include modes ('include', 'require', etc.).

Generated Output

The tracker generates a wrapper ID based on the file path checksum (CRC32).

PHP Input

IncludeTracker::render(
  'views/card.php', 
  ['title' => 'Hello World']
);

HTML Output

<div 
  pp-component="s1x2k3a" 
  title="Hello World"
>
   <!-- Content of views/card.php -->
</div>

Usage Examples

1. Basic Partial Rendering

<?php
use PP\IncludeTracker;

// Include a header
IncludeTracker::render('components/header.php');
?>

2. Passing Reactive Props (PulsePoint)

Use the Mustache syntax {variable} to bind props to PulsePoint frontend state.

<?php
use PP\IncludeTracker;
?>

<!-- Bind the 'count' prop to the frontend 'count' signal -->
<?php IncludeTracker::render(APP_PATH . '/inc/count.php', [
    'count' => '{count}',
    'setCount' => '{setCount}',
]); ?>

<!-- Define the state in your JS -->
<script>
    const [count, setCount] = pp.state(0);
</script>

⚡ Template Compiler Integration

The class automatically runs TemplateCompiler on the output. It intelligently converts camelCase prop keys (e.g., setCount) to kebab-case attributes (e.g., set-count) to ensure HTML compliance while maintaining Javascript variable naming conventions.