Prisma PHP Logo

IncludeTracker

The IncludeTracker transforms standard PHP include operations into structured components. It automatically wraps 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 creates a "boundary" around that content. This boundary allows the PulsePoint frontend to target, update, or hydrate that specific section of the page independently. By default, this boundary is a <div>, but it can be customized to any semantic HTML tag.

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 passed to the view. This array serves two purposes:

  • Data Extraction: Keys are extracted into the file's local scope (e.g., ['title' => 'Hi'] becomes $title).
  • Attribute Injection: Data is injected as HTML attributes on the wrapper for frontend access.
  • Reserved 'as' Key: Use ['as' => 'tagName'] to change the wrapper element. This key is consumed by the tracker and is not passed as an attribute.
3. Mode:

Standard PHP include modes ('include', 'require', etc.).

Usage Examples

1. Basic Partial Rendering 

<?php
use PP\IncludeTracker;

// Renders components/header.php wrapped in a <div>
IncludeTracker::render('components/header.php');
?>

2. Semantic Wrappers (Using 'as')

To improve SEO and accessibility, you can override the default container by passing the as key.

PHP Input 
IncludeTracker::render(
  'views/article.php', 
  [
    'as' => 'article',
    'id' => 'post-1'
  ]
);
HTML Output 
<article 
  pp-component="s1x..." 
  id="post-1"
>
   <!-- Content... -->
</article>

3. Passing Reactive Props (PulsePoint)

Use the Mustache syntax {variable} to bind props to PulsePoint frontend state. Note how camelCase keys are automatically converted to kebab-case attributes. 

<?php
use PP\IncludeTracker;
?>

<!-- Bind props to signals. 'setCount' becomes 'set-count' in HTML -->
<?php IncludeTracker::render(APP_PATH . '/inc/counter.php', [
    'as'       => 'section',
    'count'    => '{count}',
    'setCount' => '{setCount}',
]); ?>

<!-- Frontend State -->
<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.