Star Template Engine - Master Visual Map

╔═════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                     TEMPLATE PROCESSING PIPELINE                                        ║
╚═════════════════════════════════════════════════════════════════════════════════════════════════════════╝

┌──────────────────┐
│    INPUT DATA    │     // Context passed to template
│   ────────────   │
│ $ctx = [         │
│   'user' => [    │
│     'name'=>'A'  │
│   ],             │
│   'items'=>[...] │
│ ]                │
└────────┬─────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                    STEP 1: LOAD TEMPLATE CHAIN                                          │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────┘

┌────────────────────────────┐      ┌───────────────────────────┐      ┌──────────────────────────┐
│      page.tpl (Child)      │      │   layout.tpl (Parent)     │      │    base.tpl (Root)       │
│  ────────────────────────  │      │  ───────────────────────  │      │  ──────────────────────  │
│ {% extends "layout.tpl" %} │────> │ {% extends "base.tpl" %}  │─────>│  <!doctype html>         │
│                            │      │                           │      │  <html>                  │
│ {% block title %}          │      │ {% block header %}        │      │  {% block title %}       │
│   My Page                  │      │   <h1>Site</h1>           │      │    Default               │
│ {% endblock %}             │      │ {% endblock %}            │      │  {% endblock %}          │
│                            │      │                           │      │  {% block header %}      │
│ {% block content %}        │      │ {% block content %}       │      │  {% endblock %}          │
│   Hello {{ user.name }}    │      │   {{ super() }}           │      │  {% block content %}     │
│   {% for item in items %}  │      │   <footer>Extra</footer>  │      │  {% endblock %}          │
│   {% include "item.tpl" %} │      │ {% endblock %}            │      │  </html>                 │
│   {% endfor %}             │      │                           │      │                          │
│ {% endblock %}             │      │                           │      │                          │
└────────────────────────────┘      └───────────────────────────┘      └──────────────────────────┘
         │                             │                                                    │
         └─────────────────────────────┴────────────────────────────────────────────────────┘
                                       │
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                  STEP 2: REVERSE & MERGE BLOCKS                                         │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Processing order: base.tpl → layout.tpl → page.tpl

┌─────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│  BLOCK TRACKING TABLE                                                                                   │
│  ═══════════════════════                                                                                │
│                                                                                                         │
│  Block Name  │  After base.tpl      │  After layout.tpl         │  After page.tpl (FINAL)               │
│  ───────────────────────────────────────────────────────────────────────────────────────────────────────│
│  title       │  "Default"           │  "Default"                │  "My Page"                            │
│  header      │  ""                  │  "<h1>Site</h1>"          │  "<h1>Site</h1>"                      │
│  content     │  ""                  │  "" + "<footer>Extra..."  │  "Hello {{user.name}}..."             │
│                                                                                                         │
│  {{ super() }} in layout.tpl replaced with previous content from base.tpl                               │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────┘
                                       │
                                       ▼
┌──────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│  MERGED TEMPLATE (base.tpl structure with final blocks)                                                  │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────┘

<!doctype html>
<html>
  <title>My Page</title>                               ← Block 'title' from page.tpl
  <h1>Site</h1>                                        ← Block 'header' from layout.tpl
  Hello {{ user.name }}                                ← Block 'content' from page.tpl
  {% for item in items %}                              ← Loop in content block
    {% include "partials/item.tpl" with entry=item %}  ← Include with parameter
  {% endfor %}
  <footer>Extra</footer>                               ← From layout.tpl via super()
</html>
                                       │
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                              STEP 3: RESOLVE INCLUDES (Compile-time)                                    │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────┘

┌────────────────────────────────────┐
│  partials/item.tpl (Include)       │
│  ────────────────────────────      │        // Loaded & compiled inline
│  <li>{{ entry }}</li>              │        // entry = item (from with param)
└────────────────────────────────────┘
                  │
                  ▼ Inlined with context manipulation
                  
Include gets replaced with:
<?php $__saved_ctx = $ctx; $ctx['entry'] = $ctx['item']; ?>
  <li><?php echo htmlspecialchars($ctx['entry']); ?></li>
<?php $ctx = $__saved_ctx; ?>
                                       │
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                STEP 4: COMPILE TO PHP                                                   │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Template Syntax          ══▶   Compiled PHP Code
───────────────────────────────────────────────────────────────────────────────────────

{{ user.name }}           ══▶   <?php $__v = star_ctx_get($ctx, 'user.name');
                                if ($__v !== NULL) { echo star_e($__v); } ?>

{% for item in items %}  ══▶   <?php $__list = star_ctx_get($ctx, 'items');
                                if (is_array($__list)) {
                                  foreach ($__list as $__k => $__v) {
                                    $ctx['item'] = $__v;
                                    $ctx['item_key'] = $__k; ?>

{% endfor %}             ══▶   <?php } } ?>

{% if user.age >= 18 %}  ══▶   <?php if (star_eval_condition('user.age >= 18', $ctx)) { ?>
  Adult                       Adult
{% else %}               ══▶   <?php } else { ?>
  Minor                       Minor
{% endif %}              ══▶   <?php } ?>

{{ raw(html) }}          ══▶   <?php $__v = star_ctx_get($ctx, 'html');
                                if ($__v !== NULL) {
                                  echo (star_is_raw($__v)) ? $__v['html'] : (string)$__v;
                                } ?>
                                       │
                                       ▼
┌──────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                   STEP 5: CACHE COMPILED PHP                                             │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────┘

cache/74a7dbf2831ed066620d84d1a43dd346.php    ← MD5 hash of template name
──────────────────────────────────────────
<!doctype html>
<html>
  <title>My Page</title>
  <h1>Site</h1>
  Hello <?php $__v = star_ctx_get($ctx, 'user.name');
        if ($__v !== NULL) { echo star_e($__v); } ?>
  <?php $__list = star_ctx_get($ctx, 'items');
  if (is_array($__list)) { foreach ($__list as $__k => $__v) {
    $ctx['item'] = $__v; $ctx['item_key'] = $__k; ?>
    <?php $__saved_ctx = $ctx; $ctx['entry'] = $ctx['item']; ?>
      <li><?php echo htmlspecialchars($ctx['entry']); ?></li>
    <?php $ctx = $__saved_ctx; ?>
  <?php } } ?>
  <footer>Extra</footer>
</html>

Cache invalidation: Checks mtime of ALL templates in chain
If any template modified → recompile → save new cache
                                       │
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                  STEP 6: EXECUTE & OUTPUT                                               │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Context: $ctx = ['user' => ['name' => 'Alice'], 'items' => ['apple', 'banana']]
                                       │
                                       ▼ Execute cached PHP with context
                                       │
┌─────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                      FINAL HTML OUTPUT                                                  │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────┘

<!doctype html>
<html>
  <title>My Page</title>
  <h1>Site</h1>
  Hello Alice
  <li>apple</li>
  <li>banana</li>
  <footer>Extra</footer>
</html>

╔═════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                      PERFORMANCE CHARACTERISTICS                                        ║
╚═════════════════════════════════════════════════════════════════════════════════════════════════════════╝

FIRST RENDER (Cold Cache):
  1. Load template chain          ← File I/O (3 files)
  2. Merge blocks                 ← Regex processing
  3. Resolve includes             ← Recursive compilation
  4. Compile to PHP               ← Regex transformations
  5. Save to cache               ← File write
  6. Execute                      ← PHP execution

SUBSEQUENT RENDERS (Hot Cache):
  1. Check cache validity         ← mtime comparison
  2. Execute cached PHP           ← Direct PHP execution (FAST!)

CACHE INVALIDATION TRIGGERS:
  • base.tpl modified             → Recompile
  • layout.tpl modified           → Recompile
  • page.tpl modified             → Recompile
  • Any included partial modified → Recompile
★ STAR TEMPLATE ENGINE - COMPLETE VISUAL MAP ★
