Templates & Rendering

No Blade. No Twig. No Mustache. PHP IS the component engine. ZealPHP components are plain .php files — loops, conditionals, expressions, classes, everything you know works. Zero learning curve, full language power.

Pass data, render a component

$app->route('/users/{id}', function($id) {
    $user = User::find($id);
    if (!$user) return 404;

    App::render('profile', [
        'user'    => $user,
        'posts'   => $user->posts(),
        'isAdmin' => $user->role === 'admin',
    ]);
});

<h1><?= htmlspecialchars($user->name) ?></h1>

<?php if ($isAdmin): ?>
  <span class="badge">Admin</span>
<?php endif; ?>

<h2>Posts (<?= count($posts) ?>)</h2>
<ul>
  <?php foreach ($posts as $post): ?>
    <li>
      <a href="/post/<?= $post->id ?>">
        <?= htmlspecialchars($post->title) ?>
      </a>
      <small><?= $post->created_at ?></small>
    </li>
  <?php endforeach; ?>
</ul>

Every key in the $args array becomes a local variable in the component via extract(). No magic syntax — just PHP.

Layouts & composition

Components can render other components. Build a layout system with a single master layout composing smaller components:

<?php use ZealPHP\App;
App::render('_master', ['title' => 'About Us', 'page' => 'about']);

<!doctype html>
<html>
<head><title><?= htmlspecialchars($title) ?></title></head>
<body>
  <?= App::component('/_nav', ['active' => $page]) ?>

  <main>
    <?= App::component("/$page/" . basename($page)) ?>   <!-- template/about/about.php -->
  </main>

  <?= App::component('/_footer') ?>
</body>
</html>

Components with slots

Reusable UI components that accept data as arguments:

<div class="card">
  <div class="card-icon"><?= $icon ?></div>
  <h3><?= htmlspecialchars($title) ?></h3>
  <p><?= htmlspecialchars($body) ?></p>
  <?php if (!empty($href)): ?>
    <a href="<?= htmlspecialchars($href) ?>">Read more</a>
  <?php endif; ?>
</div>

<?php foreach ($features as $f): ?>
  <?= App::component('card', [
      'icon'  => $f['icon'],
      'title' => $f['name'],
      'body'  => $f['desc'],
      'href'  => $f['url'],
  ]) ?>
<?php endforeach; ?>

Path resolution

render() and component() resolve a name by the same rule. In each place name.php comes before the partial _name.php; a missing template's error lists every place it looked.

Relative names resolve from the request's page, not from the file making the call.

Which page is a request on?

The page is the public file being served: its SCRIPT_NAME without the leading / and the .php. App::include() sets SCRIPT_NAME (with PHP_SELF and SCRIPT_FILENAME, as Apache does) before it runs the file, and every public page is served through it: the implicit /{file} routes, directory index pages, and your own App::include() calls.

• SCRIPT_NAME, not PHP_SELF. PHP_SELF is SCRIPT_NAME plus the client's PATH_INFO, so reading it let /index.php/users choose template/users/. When only PHP_SELF is set (code that sets it by hand), its PATH_INFO is stripped first.
• It's per request, and it's the served file. A component or layout asking for a relative name gets the page's folder, wherever its own file lives. A route that calls App::include() switches the page for the rest of that request.

From a public file to the page

render() serves the page; everything inside the page is a component. One request, end to end:

public/invoices.php                     App::render('invoices', ['invoices' => $list])
  → template/invoices/invoices.php      the page's own template, in the page's folder
    → App::component('row', $invoice)   → template/invoices/components/row.php   (this page only)
    → App::component('card', [...])     → template/components/card.php           (shared)

<?php use ZealPHP\App;
App::render('invoices', [
    'invoices' => Billing\Invoices::open(),
]);

<h1>Invoices</h1>
<?= App::component('card', ['title' => 'Open',
    'slot' => App::component('total', ['invoices' => $invoices])]) ?>
<table>
  <?php foreach ($invoices as $invoice): ?>
    <?= App::component('row', ['invoice' => $invoice]) ?>
  <?php endforeach; ?>
</table>

Where components can be used

The rules behind this layout are in Where code goes.

The rendering methods — render() and component()

Rendering comes down to two methods. App::render() renders a page or a response; its options select a fragment, make the render htmx-aware, or return a stream. App::component() returns markup as a value and never echoes; use it to compose. Both run the template through one private core (App::executeFile()) and apply the universal return contract. App::include() runs a file from public/ the same way, and App::fragment() runs inside a template to mark a named region the framework can extract by name. See the fragments section below.

App::render() options

App::render('_master', ['page' => 'home']);              // echo the page (public/*.php)
return App::render('users/show', ['user' => $u]);         // a route's response
return App::render('search', $args, htmx: true);          // fragment for htmx, page otherwise
return App::render('contacts', $args, fragment: 'row-7'); // one App::fragment() region
return App::render('feed', $args, stream: true);          // a Generator, flushed chunk by chunk

$html = App::component('card', ['title' => 'Hi']);        // markup as a value, never echoed

Deprecated helpers

Earlier releases had a separate method for each way of rendering. They still work until 1.0, but new code should use the two methods above.

App::includeFile() is the deprecated alias for App::include() — kept for backward compatibility (the WordPress showcase and existing scaffolds still call it). New code should use App::include().

Template fragments — one file, two responses

App::fragment($name, $fn) turns any template into a dual-mode file: the same template serves either the complete page (App::render('page', $args), no fragment selector → every App::fragment() block runs inline) or just one named region (App::render('page', $args, fragment: 'name') → that region's buffer is cleared, only its closure runs, the rest of the template short-circuits via HaltException). Same template, same route handler, two different responses on the same URL — the htmx-essay template-fragment pattern without separate partial files.

<ul id="contacts">
<?php foreach ($contacts as $c): ?>
  <?php App::fragment("contact-{$c['id']}", function() use ($c) { ?>
    <li id="contact-<?= $c['id'] ?>"><?= htmlspecialchars($c['name']) ?></li>
  <?php }); ?>
<?php endforeach; ?>
</ul>

$app->route('/contacts', function($g) {
    // No selector → full <ul> with every row inline.
    // ?fragment=contact-2 → just that one <li> on the wire.
    $fragment = is_string($g->get['fragment'] ?? null) ? $g->get['fragment'] : null;
    return App::render('contacts/list', ['contacts' => Contact::all()], fragment: $fragment);
});

Inside the closure, the universal contract applies — return 404; for auth, return ['id'=>1]; for JSON, return (fn(){ yield ...; })(); for streaming. Three behaviours worth knowing:

• Missing fragment → 404 per the universal return contract. Asking for ?fragment=does-not-exist doesn't silently fall back to the full page.
• First match wins when the same name appears twice — the first block extracts, the rest of the template short-circuits.
• Nested renders compose — an App::render() called from inside a fragment closure does not inherit the parent's fragment selector. Each render's scope is saved+restored.

SSR Streaming — yield from templates

App::render($tpl, $args, stream: true) returns a Generator and never echoes. If the template file returns a Generator (via IIFE), it delegates with yield from. If the template echoes normally, the output is captured and yielded as one chunk. Both patterns compose in the same streaming pipeline.

<?php
// Declare what data this template needs —
// framework injects by name (like route handlers)
return function($users) {
    yield "<section class='users'>";
    foreach ($users as $user) {
        yield "<div class='card'>"
            . htmlspecialchars($user->name)
            . "</div>\n";
    }
    yield "</section>";
};

$app->route('/users', function() {
    return (function() {
        // Regular template → single chunk
        yield from App::render(
            'shell-open', ['title' => 'Users'],
            stream: true
        );

        // Streaming template → per-user chunks
        yield from App::render(
            'users/stream',
            ['users' => User::all()],
            stream: true
        );

        yield from App::render('shell-close', stream: true);
    })();
});

The template declares function($users) — the framework injects $users from the args array by name, exactly like route parameter injection. Each yield flushes to the browser immediately.

Three streaming template styles

All three compose in the same yield from App::render(..., stream: true) pipeline.

Yield from everywhere

Generators work in route handlers, public/ files, API handlers, and template files:

<?php
// File: public/feed.php → GET /feed
// Returns a Generator — framework streams each yield to the browser
use ZealPHP\App;

return (function() {
    yield from App::render('shell-open', ['title' => 'Live Feed'], stream: true);
    yield "<h1>Feed</h1>";

    foreach (fetchFeedItems() as $item) {
        yield "<article>{$item->title}</article>\n";
    }

    yield from App::render('shell-close', stream: true);
})();

<?php
// File: api/events/stream.php → GET /api/events/stream
$stream = function() {
    return (function() {
        yield '{"events":[';
        $first = true;
        foreach (Event::cursor() as $event) {
            if (!$first) yield ',';
            yield json_encode($event);
            $first = false;
        }
        yield ']}';
    })();
};

PHP template patterns cheat sheet

Why PHP over Blade/Twig/Mustache?