# PHPue AI Knowledge (full text)

> The companion AI knowledge base for PHPue 0.0.3, with coding-agent rules, verified examples and downloadable skills. Official framework documentation: https://phpue.co.uk/docs.

PHPue version: 0.0.3 | Updated: 2026-10-12 | Index: https://ai.phpue.co.uk/llms.txt


---

<!-- Source: https://ai.phpue.co.uk/ | Markdown: https://ai.phpue.co.uk/knowledge/overview.md -->

# What PHPue is (and is not)

> **PHPue** is a server-side PHP framework by Edward Patch that compiles Vue-like single-file components (`.pvue` files) into plain PHP. A `.pvue` file has a `<script>` block (PHP), a `<header>` block (head tags), a `<template>` block (HTML with `{{ }}`, `p-if` and `p-for`) and a `<cscript>` block (browser JavaScript). There is no Node.js, bundler or required build step: two PHP files (`index.php` and `conversion.php`) route, compile and serve the app. The current release is **PHPue 0.0.3**, which needs **PHP 8.0 or newer**.

Tagline: *Giving U Back Control.* Official site: [phpue.co.uk](https://phpue.co.uk). Source: [github.com/PHPue/PHPue](https://github.com/PHPue/PHPue).

## Key facts

| Fact | Value |
|---|---|
| Current version | 0.0.3 (bug-fix release; 0.0.2 projects still exist) |
| Requirements | PHP 8.0+ (0.0.3 uses `str_contains()`); any web server that can route to `index.php` |
| Framework files | `index.php` (server, router, builder) and `conversion.php` (`.pvue` to PHP compiler) |
| Component format | `.pvue` single-file components with `script`, `header`, `template`, `cscript` blocks |
| Template syntax | `{{ $expr }}` (escaped echo), `p-if="cond"`, `p-for="$item in $list"`, raw `<?php ?>` |
| Routing | File-based: `views/about.pvue` is `/about`, `views/index.pvue` is `/` |
| Browser calls | `@AJAX('POST')` / `@AJAX('GET')` PHP functions called with `fetch` |
| Rendering | Server-side only; no virtual DOM, no hydration, no reactivity |
| Optional client layer | Plain JS in `<cscript>`, AlpineJS, the x-ssr Alpine extension, HTMX |
| Build | Optional: `php index.php build` writes a precompiled `.dist/` for production |
| Licence | Apache 2.0 |

## PHPue is NOT Vue

The syntax looks like Vue, but the model is classic server-rendered PHP:

- Everything inside `{{ }}`, `p-if` and `p-for` runs **once, on the server**, per request.
- There is no virtual DOM, no reactivity, no hydration, no props, no slots, no emits and no `v-model`.
- The `<script>` block is **PHP**, not JavaScript. Browser code goes in `<cscript>`.
- Components have **no prop API by design**: a component is inlined into its parent at compile time, so it sees every variable the parent has (like a PHP `include`).
- **Raw PHP is always allowed and idiomatic.** When a directive cannot express something, write `<?php if (...): ?>`, `<?php foreach (...): ?>` or `<?= ... ?>` in the template.
- **Privacy-first forms**: there is no input binding or keystroke tracking. Forms are submitted on purpose (a normal POST, or an explicit `fetch` to an `@AJAX` function).

Rule of thumb from the author: *PHP owns the server. The browser layer is optional.*

## Project layout

```text
www/                     web root and working directory (all paths are relative to it)
├── index.php            framework: server, router, builder
├── conversion.php       framework: .pvue -> PHP compiler
├── App.pvue             root layout: global <header>, navbar/footer, <View/>
├── views/               one .pvue per route (top level only): index.pvue -> "/", about.pvue -> "/about"
├── components/          reusable .pvue files (any depth), pulled in with @require
├── backend/             *.php auto-required on every request (classes, singletons, endpoints)
├── httpReqs/            http404.php + http404Head.php (custom 404 page)
├── assets/              css/ js/ img/, served statically at /assets/...
├── .htaccess            front controller + security rules (Apache)
└── .dist/               build output (when present, the server uses it instead of the .pvue sources)
```

## How a request is served

1. `index.php` turns the URL path into a route slug (`/about` is `about`, `/` is `index`) and finds `views/<slug>.pvue`. Unknown slugs get the 404 page with HTTP status 404.
2. `conversion.php` compiles `App.pvue` and the view into PHP (or the precompiled `.dist/` files are used).
3. The compiled App runs: every `backend/*.php` is loaded, the session is handled, and if the request names an `@AJAX` function (`action`), that function runs and the request ends.
4. Otherwise the App `<script>` runs, the `<head>` is printed (App header + view header), and the App template renders, replacing `<View/>` with the current view.
5. Each block's `<cscript>` is printed as a `<script>` tag after its markup.

## The smallest complete app

```html
<!-- www/App.pvue -->
<script>
    #require 'views/index.pvue';
</script>

<header>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
</header>

<template>
    <View/>
</template>
```

```html
<!-- www/views/index.pvue -->
<script>
    $title = 'Hello PHPue';
    $features = ['No build step', 'Server-side rendering', 'Plain PHP underneath'];
</script>

<header>
    <title>Home</title>
</header>

<template>
    <h1>{{ $title }}</h1>
    <ul>
        <li p-for="$feature in $features">{{ $feature }}</li>
    </ul>
</template>
```

Run it with `cd www && php -S localhost:3000` and open `http://localhost:3000`.

## Where to go next

- Writing PHPue with an AI assistant or coding agent: [Rules for AI coding agents](/docs?topic=ai-rules).
- First app step by step: [Quick start](/docs?topic=quickstart).
- Syntax in depth: [.pvue files](/docs?topic=pvue-files), [Templates](/docs?topic=templates), [Components](/docs?topic=components), [Routing](/docs?topic=routing), [@AJAX](/docs?topic=ajax).
- Something renders wrong: [Common mistakes](/docs?topic=gotchas).
- Everything in one file for an LLM: [/llms-full.txt](/llms-full.txt).


---

<!-- Source: https://ai.phpue.co.uk/docs?topic=ai-rules | Markdown: https://ai.phpue.co.uk/knowledge/ai-rules.md -->

# Rules for AI coding agents

> Read this before generating any PHPue code. PHPue is new and small, so general training data about it is thin and often wrong. When this page disagrees with older blog posts or docs (for example `{{ $user.name }}`, `p-model` or "PHP 7.1+"), **this page reflects what the PHPue 0.0.3 compiler actually does**. Every rule here was verified by compiling real `.pvue` files.

## Step 1: check the version

```bash
grep -m1 PHPUE_VERSION www/index.php     # define('PHPUE_VERSION', '0.0.3');
```

These rules are for **0.0.3**. 0.0.2 is much stricter about markup layout; if the project is on 0.0.2, read [Upgrading from 0.0.2](/docs?topic=upgrade) first and either upgrade (replace `index.php` **and** `conversion.php` together) or follow the 0.0.2 rules there. Never write 0.0.3-only markup into a 0.0.2 project.

## The hard rules

1. **A `.pvue` file has up to four top-level blocks, in this order:** `<script>` (PHP, no `<?php` tags), `<header>` (head tags), `<template>` (HTML), `<cscript>` (browser JS). Each appears at most once. Anything outside them is ignored. Never write `<html>`, `<head>` or `<body>`.
2. **`{{ }}` converts expressions that start with `$` or a function/static call:** `{{ $user['name'] }}`, `{{ $a ? 'x' : 'y' }}`, `{{ count($items) }}`. Output is `htmlspecialchars`-escaped. Anything else (`{{ !$x }}`, `{{ (int)$x }}`, `{{ item.name }}`) stays literal text. **Never `{{ $user.name }}`**: `.` is PHP string concatenation. Use `$user['name']` or `$user->name`. Arrays inside `{{ }}` throw. Raw HTML: `<?= $trustedHtml ?>`.
3. **`p-if="cond"`** works on any closed element (or void element): one line, multi-line, nested same-tag children, `{{ }}` in other attributes. There is **no `p-else`, `p-else-if` or `p-show`**: write a negated second `p-if` or raw `<?php if: ?> ... <?php else: ?> ... <?php endif; ?>`.
4. **`p-for="$item in <expr>"`** or `p-for="$key => $value in <expr>"`; `<expr>` can be any PHP expression (`$rows`, `$data['items']`, `range(1, 5)`, a `PDOStatement`, a generator). Non-iterables render nothing. `p-for` and `p-if` on the same element loop first, then filter each item.
5. **Components:** declare with `@require Card 'components/Card.pvue';` in `<script>` (path from the web root), use as `<Card/>`, `<Card />` or `<Card></Card>`. **No attributes, no props, no slots, no children** (only `p-if`/`p-for` on the tag). A component is inlined and **inherits every variable of the parent** at that point. Set variables before the tag (`<?php $cardTitle = 'X'; ?><Card/>`) or reuse a `p-for` loop variable, and default them in the component (`$cardTitle = $cardTitle ?? '';`). Do not invent a props mechanism.
6. **Views are routes:** `views/<name>.pvue` is `/<name>`, `views/index.pvue` is `/`. Only top-level files; no nested paths (`/blog/post` is a 404), use query strings (`/blog?post=slug`). Register every view in `App.pvue` with `#require 'views/name.pvue';` (no name before the path). `<View/>` appears only in `App.pvue`.
7. **The view `<header>` is static HTML** (`{{ $x }}` prints a literal `$x`, PHP is not run). Only `App.pvue`'s header is dynamic, and only for `{{ $var }}`, `{{ $arr['k'] }}` and `{{ $obj->prop }}`, injected **raw**. Build dynamic meta strings in the App script (or use the MetaControl extension).
8. **Scope:** App, each view and `@AJAX` handlers run in separate scopes. App variables are **not** visible in views. Share data through `backend/` singletons, `$_SESSION`, `define()` or `$GLOBALS`.
9. **`@AJAX('POST')` / `@AJAX('GET')`** goes directly before `function name($input) { ... }` in a `<script>` block. Handlers must **`echo`** (usually `json_encode`), because return values are discarded. They run **before** the page script, so they see no page variables. The declared method is enforced (wrong method: 405). Function names are global, so keep them unique. Client: `fetch('', {method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({action: 'name', ...})})` or `fetch('?action=name&x=1')`. Only JSON bodies dispatch; `FormData` does not.
10. **`<cscript>` becomes a `<script>` tag.** Inside it `{{ $expr }}` becomes `json_encode($expr)`, so never wrap it in quotes (`"{{ $name }}"` produces `""Ada""`). Function calls are not converted there: `<?= json_encode(count($x)) ?>`.
11. **A block cannot contain its own closing tag**, even in a string or comment: a literal closing script tag inside the PHP block ends it. Split it: `'</scr' . 'ipt>'`. Same for `</cscript>` and `</header>`.
12. **No named functions or classes in components** (redeclared when the component is used twice or in a loop). Put them in `backend/`, or use closures. Avoid top-level `let`/`const` in a reused component's `<cscript>`.
13. **Use `getcwd()` for file paths**, not `__DIR__` (in `.pvue` code `__DIR__` changes once the app is built into `.dist/`).
14. **Sessions:** with `PHPUE_SESSION = 'lazy'` (recommended for public sites), call `phpue_session(true)` before writing `$_SESSION` while rendering a page. POST `@AJAX` handlers get a session automatically. `$_GET['page']` is reserved for the route: paginate with `?p=`.
15. **If `.dist/` exists, edits to `.pvue` files do nothing** (the compiled copy is served). Delete `.dist/` while developing, or rebuild with `php index.php build`.
16. **Never edit `index.php` or `conversion.php`** to make a feature work. They are the framework core, shared by every PHPue project. If a framework change seems necessary, say so.

## Never bring in

| From | Do not write | PHPue way |
|---|---|---|
| Vue | `v-if`, `v-for`, `:prop`, `@event` on components, `v-model`, `<style scoped>`, `<script setup>` with JS | `p-if`, `p-for`, inherited variables, explicit form submits, `<style>` in the template, JS in `<cscript>` |
| Vue/PHPue myths | `p-else`, `p-show`, `p-model`, `p-bind` | negated `p-if`, raw PHP, `value="{{ $x }}"` |
| React/Next.js | JSX, `useState`, `useEffect`, client routers, hydration | PHP variables, server-side data fetching, file routes |
| Laravel Blade | `@if`, `@foreach`, `@include`, `{!! !!}` | `p-if`, `p-for`, `<Component/>`, `<?= ?>` |
| Tooling | npm bundlers, Vite, webpack, Composer at the project root | nothing (optional Tailwind CLI); vendor code goes in `backend/` |

`p-model` still exists in `conversion.php` only as an abandoned placeholder. Never use it: write `name="email" value="{{ $email }}"` and submit on purpose.

## Where code goes

| Need | Put it in |
|---|---|
| Data loading, form handling, page logic | the view's `<script>` |
| Markup | `<template>` |
| Page title and meta for one static page | the view's `<header>` |
| Dynamic title/meta, global CSS/JS, analytics | `App.pvue` `<header>` + App `<script>` |
| Browser behaviour | `<cscript>` (or `/assets/js/*.js`) |
| Classes, DB access, helpers, API clients | `backend/*.php` (singletons with `getInstance()`) |
| Browser-callable server actions | `@AJAX` functions in the view (or App for site-wide actions) |
| File uploads, non-JSON endpoints | a `backend/` endpoint file (`?api&endpoint=...`) |

## Verify before you answer

1. Compile the file you changed and syntax-check the result (run from `www/`):

```bash
php -r 'define("PHPUE_VERSION","0.0.3"); define("PHPUE_LANG","en"); require "conversion.php"; echo convert_pvue_file("views/page.pvue");' | php -l
php -r 'define("PHPUE_VERSION","0.0.3"); define("PHPUE_LANG","en"); require "conversion.php"; echo convert_pvue_file("App.pvue", true);' | php -l
```

Drop the `| php -l` to read the compiled PHP. In source mode the dev server also shows it: `http://localhost:3000/?compile=views/page.pvue`.

2. Run the app: `cd www && php -S localhost:3000`, open `http://localhost:3000` (add `?live` for hot reload). Make sure no stale `.dist/` exists.
3. Test `@AJAX` handlers with curl: `curl -X POST -H 'Content-Type: application/json' -d '{"action":"save","name":"Ada"}' http://localhost:3000/page`. A full HTML page in the response means the action name did not match an `@AJAX` function; a 405 means the method is wrong.

## Agent Skill (Claude Code, Codex)

The fastest way to teach a coding agent PHPue is the downloadable skill: [phpue.zip](/skills/phpue.zip) is the PHPue author's own skill: these rules, in-depth references, a starter app and compile/lint scripts. Install instructions: [/skills](/skills).

## AGENTS.md / CLAUDE.md for PHPue projects

Copy this into the root of any PHPue project so coding agents (Claude Code, Codex, Cursor, Copilot, Gemini CLI) follow the rules:

```markdown
# PHPue project rules

This is a PHPue app (https://phpue.co.uk). PHPue compiles .pvue files to PHP on the server. It is NOT Vue.
Full reference for agents: https://ai.phpue.co.uk/llms-full.txt (index: https://ai.phpue.co.uk/llms.txt)

- Check the version first: grep -m1 PHPUE_VERSION www/index.php. These rules are for 0.0.3.
- .pvue blocks, in order: <script> (PHP, no <?php tags), <header> (head tags), <template> (HTML), <cscript> (browser JS).
- {{ $expr }} = escaped echo. Use $arr['k'] or $obj->p, never $obj.p. Raw HTML: <?= $html ?>.
- p-if="cond" and p-for="$item in $list" on closed elements. No p-else / p-show / p-model: use a negated p-if or raw PHP.
- Components: @require Name 'components/Name.pvue'; then <Name/>. No props/attributes/slots: components inherit the parent's variables. Default them with $x = $x ?? ''.
- Routes: views/<name>.pvue -> /<name>. Flat only; use query strings. #require 'views/<name>.pvue'; in App.pvue.
- View <header> is static. Dynamic meta goes through App.pvue's header (or the MetaControl extension).
- App variables are not visible in views. Share via backend/ singletons, $_SESSION, define().
- @AJAX('POST') function name($input) { echo json_encode(...); } - echo, don't return. Call with fetch('', {method:'POST', headers:{'Content-Type':'application/json'}, body: JSON.stringify({action:'name', ...})}).
- <cscript>: {{ $var }} is json_encode'd - never wrap it in quotes.
- No named functions/classes in components; put them in backend/. Use getcwd() for paths, not __DIR__.
- Never edit index.php or conversion.php. Delete .dist/ while developing.
- Verify: compile with convert_pvue_file() and pipe to php -l; run with cd www && php -S localhost:3000.
```

## Prompt for chat assistants

When using a chat assistant (ChatGPT, Claude, Gemini, Perplexity) that can browse, start with:

```text
Before answering, read https://ai.phpue.co.uk/llms-full.txt. It is the canonical reference for PHPue 0.0.3,
a server-side PHP framework with Vue-like .pvue files. PHPue is new: do not rely on general knowledge or on Vue
behaviour. Use only the syntax documented there, say when something is not covered, and link the relevant topic
from https://ai.phpue.co.uk/llms.txt.
```


---

<!-- Source: https://ai.phpue.co.uk/skills | Markdown: https://ai.phpue.co.uk/knowledge/agent-skill.md -->

# PHPue Agent Skill for Claude Code and Codex

> Download the **PHPue skill** ([phpue.zip](/skills/phpue.zip)) to teach a coding agent PHPue. It is the same skill the PHPue author uses with Claude Code and Codex: a `SKILL.md` with the hard rules and workflow, detailed references verified against the 0.0.3 compiler, a starter app to copy, and two PHP scripts that compile and lint `.pvue` files with your project's own `conversion.php`. The agent loads it automatically whenever it works on a PHPue project.

## What's inside

```text
phpue/
├── SKILL.md                       rules, workflow and reference map (loaded by the agent)
├── agents/openai.yaml             display metadata for Codex
├── assets/                        icons
├── references/
│   ├── vanilla.md                 complete PHPue Vanilla reference (blocks, directives, components, AJAX, backend, scope)
│   ├── alpine-xssr.md             AlpineJS + the x-ssr directive in depth
│   ├── runtime-build-deploy.md    serving modes, dev tools, .dist builds, deployment, 404 pages, security
│   ├── engine-gotchas.md          verified input -> output table of compiler behaviour (0.0.3 and 0.0.2)
│   ├── extensions.md              MetaControl, Matrix CMS, x-ssr, LanguageSelector
│   └── htmx-spa.md                HTMX navigation, partials, NGINX caching and lazy sessions
├── templates/                     starter app that passes the linter: App.pvue, views, components,
│                                  backend singleton, 404 pages, .htaccess, Tailwind, Alpine + x-ssr,
│                                  docker-compose.yaml, nginx config
└── scripts/
    ├── phpue-compile.php          print (and php -l) the PHP a .pvue file compiles to
    └── phpue-lint.php             version-aware linter for a whole PHPue project
```

The scripts need only PHP 8 on the command line. The references cover the same ground as this site in more depth; this site's topics are the shorter, public-facing version.

## Install for Claude Code

User-wide (every project):

```bash
curl -fsSL https://ai.phpue.co.uk/skills/phpue.zip -o phpue-skill.zip
unzip -o phpue-skill.zip -d ~/.claude/skills
```

Or for one project only (commit it so your whole team gets it): unzip into `.claude/skills` in the project root instead of `~/.claude/skills`.

Check it loaded: start Claude Code in a PHPue project and ask "which skills do you have?", or type `/phpue`.

## Install for Codex

```bash
curl -fsSL https://ai.phpue.co.uk/skills/phpue.zip -o phpue-skill.zip
unzip -o phpue-skill.zip -d ~/.codex/skills
```

Restart Codex so it picks up the new skill.

## Windows (PowerShell)

```powershell
Invoke-WebRequest https://ai.phpue.co.uk/skills/phpue.zip -OutFile phpue-skill.zip
Expand-Archive phpue-skill.zip -DestinationPath "$HOME\.claude\skills" -Force
```

Use `"$HOME\.codex\skills"` for Codex.

## Claude apps (claude.ai, desktop)

Upload `phpue.zip` as a custom skill in the app's skills settings (Settings, then Capabilities). The zip already has the expected layout: one `phpue/` folder with `SKILL.md` at its top.

## Let the agent install it

Paste this into Claude Code or Codex:

```text
Download https://ai.phpue.co.uk/skills/phpue.zip and unzip it into my user skills folder
(~/.claude/skills for Claude Code, ~/.codex/skills for Codex), replacing any older phpue skill.
Then list the files in the phpue skill folder.
```

## Using the scripts directly

From your project's `www/` folder (replace the path with where you installed the skill):

```bash
php ~/.claude/skills/phpue/scripts/phpue-compile.php views/page.pvue --lint
php ~/.claude/skills/phpue/scripts/phpue-compile.php App.pvue --root --lint
php ~/.claude/skills/phpue/scripts/phpue-lint.php .
```

The linter reads `PHPUE_VERSION` from `index.php` and applies the 0.0.2 or 0.0.3 rules (override with `--version=0.0.3`). It exits with code 1 when it finds errors, so it also works in CI.

## Updating

Download the zip again and unzip over the old folder (`unzip -o` replaces files). Start new projects from `templates/` in the skill folder.

## Other agents

Agents without skill support (Cursor, Copilot, Gemini CLI, Windsurf) can use the same knowledge through an `AGENTS.md` file ([template](/docs?topic=ai-rules)) or by reading [/llms-full.txt](/llms-full.txt).


---

<!-- Source: https://ai.phpue.co.uk/docs?topic=quickstart | Markdown: https://ai.phpue.co.uk/knowledge/quickstart.md -->

# Quick start: your first PHPue app

> A PHPue app needs PHP 8.0+, two framework files (`index.php`, `conversion.php`) and your `.pvue` files. No Node.js, Composer or bundler. Run it with PHP's built-in server, Docker, XAMPP, or any host that routes requests to `index.php`.

## 1. Get the framework

```bash
git clone https://github.com/PHPue/PHPue.git
cd PHPue/www
grep -m1 PHPUE_VERSION index.php      # should print 0.0.3
```

Or start empty: create a `www/` folder and copy only `index.php` and `conversion.php` into it. They are one release; always copy (or upgrade) both together.

## 2. Create the layout: `www/App.pvue`

```html
<script>
    @require Navbar 'components/Navbar.pvue';

    #require 'views/index.pvue';
    #require 'views/about.pvue';
</script>

<header>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <link rel="stylesheet" href="/assets/css/styles.css">
</header>

<template>
    <Navbar/>
    <main>
        <View/>
    </main>
</template>
```

`#require` registers each view. `<View/>` is replaced by the page for the current URL.

## 3. Add a component: `www/components/Navbar.pvue`

```html
<script>
    $navLinks = [
        ['url' => '/', 'label' => 'Home'],
        ['url' => '/about', 'label' => 'About'],
    ];
    $currentPath = parse_url($_SERVER['REQUEST_URI'] ?? '/', PHP_URL_PATH);
</script>

<template>
    <nav aria-label="Main">
        <a p-for="$link in $navLinks" href="{{ $link['url'] }}" aria-current="{{ $currentPath === $link['url'] ? 'page' : 'false' }}">{{ $link['label'] }}</a>
    </nav>
</template>
```

## 4. Add pages: `www/views/index.pvue` and `www/views/about.pvue`

```html
<script>
    $visits = (int) ($_GET['n'] ?? 0) + 1;
    $features = ['No build step', 'Server-side rendering', 'Plain PHP underneath'];
</script>

<header>
    <title>Home</title>
    <meta name="description" content="My first PHPue app">
</header>

<template>
    <h1>Hello PHPue</h1>
    <ul>
        <li p-for="$feature in $features">{{ $feature }}</li>
    </ul>
    <p p-if="$visits > 1">You have been here {{ $visits }} times.</p>
    <a href="/?n={{ $visits }}">Count again</a>
</template>

<cscript>
    console.log('Features from PHP:', {{ $features }});
</cscript>
```

```html
<header>
    <title>About</title>
</header>

<template>
    <h1>About</h1>
    <p>This page is views/about.pvue, served at /about.</p>
</template>
```

## 5. Run it

```bash
cd www
php -S localhost:3000
```

Open `http://localhost:3000` (use `localhost`, not `127.0.0.1`). Add `?live` to the URL for hot reload while you edit. Source mode compiles every `.pvue` on each request, so edits show up on refresh.

Docker alternative (nginx + php-fpm on port 3000): use the `docker-compose.yaml` and `nginx/default.conf` from the PHPue repository and run `docker compose up`.

## 6. Build and deploy

```bash
cd www
php index.php build        # compiles everything into .dist/
```

Upload `.dist/`, `assets/`, `httpReqs/`, `index.php`, `conversion.php` and `.htaccess` to any PHP 8 host. `index.php` serves the precompiled `.dist/` automatically. Delete `.dist/` locally when you go back to editing, otherwise the old build keeps being served. Details: [Build and deploy](/docs?topic=build-deploy).

## Next steps

- Add server actions without page reloads: [@AJAX](/docs?topic=ajax).
- Share data and classes between pages: [backend/ and scope](/docs?topic=backend).
- Style with Tailwind: add `tailwindcss` as a dev dependency, set `content` to `["./**/*.pvue", "./**/*.php"]`, build to `assets/css/tailwind-styles.css` and link it in the App header. Rebuild CSS after adding classes.
- Complete examples: [Recipes](/docs?topic=recipes).


---

<!-- Source: https://ai.phpue.co.uk/docs?topic=pvue-files | Markdown: https://ai.phpue.co.uk/knowledge/pvue-files.md -->

# .pvue files: the four blocks

> A `.pvue` file is a single-file component with up to four top-level blocks: `<script>` (server PHP), `<header>` (tags for `<head>`), `<template>` (HTML) and `<cscript>` (browser JavaScript). `conversion.php` compiles it to plain PHP. Every block is optional and appears at most once; keep them in this order.

```html
<!-- Comments outside the blocks are ignored -->
<script>
    // PHP without <?php tags. Runs on the server before the template.
    $items = ['One', 'Two'];
</script>

<header>
    <!-- Tags for <head>. App.pvue: dynamic. Views: static. Components: ignored. -->
    <title>Example</title>
</header>

<template>
    <!-- HTML + {{ $expr }} + p-if / p-for + raw <?php ?> + <Component/> -->
    <ul>
        <li p-for="$item in $items">{{ $item }}</li>
    </ul>
</template>

<cscript>
    // Browser JavaScript, printed as a <script> tag after this file's markup
    console.log({{ $items }});
</cscript>
```

## `<script>`: server PHP

- Plain PHP without `<?php` / `?>`. Anything PHP 8 can do works: `$_GET`, `$_POST`, `$_SESSION`, `$_SERVER`, `curl`, PDO through backend classes, closures.
- `<script setup>` is accepted as an alias.
- Three PHPue statements are only recognised here:
  - `@require Name 'components/Name.pvue';` imports a component (single or double quotes, path from the web root).
  - `#require 'views/name.pvue';` registers a view (only in `App.pvue`).
  - `@AJAX('POST')` / `@AJAX('GET')` before a function makes it callable from the browser.
- It is **PHP, not JavaScript**. A Vue habit of writing JS here produces a PHP parse error.

## `<header>`: tags for `<head>`

| File | Behaviour |
|---|---|
| `App.pvue` | Becomes a PHP heredoc. `{{ $var }}`, `{{ $arr['k'] }}` and `{{ $obj->prop }}` are injected **raw** (escape them yourself when building the string). Function calls and `??` are not converted; `<?php ?>` is printed literally. Avoid inline JS that uses `$` here. |
| `views/*.pvue` | Static HTML, added after the App header **only on that route**. `{{ $x }}` prints a literal `$x`; PHP is not run. `<title>` also names the route for `phpue_navigation()`. `<meta name="lang" content="fr">` sets `<html lang>` for that view. |
| components | Ignored. Put component CSS in a `<style>` inside its template. |

Never write `<html>`, `<head>` or `<body>`: PHPue prints them. The page is `<!DOCTYPE html><html lang="…"><head>` + App header + view header + `</head><body>` + App template + App cscript + `</body></html>`.

If both App and the view print a `<title>`, the App one comes first and wins. Pick one strategy: static titles in each view's header, or one dynamic title from the App header for every page.

## `<template>`: the HTML

The markup for this file, with `{{ }}`, `p-if`, `p-for`, raw PHP and component tags. See [Templates](/docs?topic=templates) and [Components](/docs?topic=components). In `App.pvue` the template contains `<View/>`, which is replaced by the current page.

Nested `<template>` elements (Alpine `<template x-for>`, `<template id>` for cloning) are fine as long as each one is closed.

## `<cscript>`: browser JavaScript

- Printed as `<script>…</script>` (or `<script type="module">` when a line starts with `import`/`export`) right after this file's markup. App cscript is printed before `</body>`.
- `{{ $expr }}` inside it becomes `json_encode($expr)`: numbers, strings (already quoted), arrays and objects arrive as JS values. Never wrap it in quotes.
- Raw PHP works inside it: `const n = <?= json_encode(count($items)) ?>;`.
- A component's cscript is repeated each time the component renders: avoid top-level `let`/`const` there.

Details: [cscript, AlpineJS and x-ssr](/docs?topic=client-js).

## How the compiler finds blocks (0.0.3)

- Only **top-level** tags count. Tag names inside comments, PHP strings or the template do not start or end blocks.
- `<script>`, `<header>` and `<cscript>` run to their **first** closing tag; `<template>` runs to its **matching** `</template>`.
- Consequence: a block cannot contain its own closing tag, even in a string or a comment. A literal closing script tag in a PHP string ends the PHP block and the rest of your code is silently dropped. Split it: `'</scr' . 'ipt>'`. Same for `</cscript>` and `</header>`.
- Only the first block of each kind is used.

## Naming conventions

- Views: kebab-case slugs, because the file name is the URL (`get-started.pvue` is `/get-started`).
- Components: PascalCase files in topic folders (`components/cards/ProductCard.pvue`).
- Booleans: `$b` prefix (`$bShowDetails`) in the author's code.
- Paths: always from the web root (`www/`), assets as absolute `/assets/...` URLs.


---

<!-- Source: https://ai.phpue.co.uk/docs?topic=templates | Markdown: https://ai.phpue.co.uk/knowledge/templates.md -->

# Templates: {{ }}, p-if, p-for and forms

> The `<template>` block is HTML plus four tools: `{{ $expr }}` for escaped output, `p-if="cond"` to render an element conditionally, `p-for="$item in $list"` to repeat an element, and raw `<?php ?>` / `<?= ?>` for anything else. All of it runs once, on the server, per request. There is no `p-else`, `p-show` or `p-model`.

## `{{ }}`: escaped output

`{{ $expr }}` compiles to `<?= htmlspecialchars($expr ?? "") ?>`. An expression that starts with a function or static call compiles to `<?= htmlspecialchars((string) (expr)) ?>`.

| Write | Result |
|---|---|
| `{{ $title }}` | escaped value |
| `{{ $row['label'] ?? '' }}`, `{{ $post->title }}` | array key / object property |
| `{{ $isActive ? 'active' : '' }}` | ternary; works inside attributes: `class="nav {{ $isActive ? 'active' : '' }}"` |
| `{{ $price * $qty }}` | arithmetic |
| `{{ count($items) }}`, `{{ number_format($price, 2) }}`, `{{ \App\Fmt::money($p) }}` | function and static calls (0.0.3) |
| `{{ $user.name }}` | **wrong**: `.` is PHP concatenation. Use `$user['name']` or `$user->name` |
| `{{ $tags }}` where `$tags` is an array | **TypeError**. Use `{{ implode(', ', $tags) }}` |
| `{{ !$x }}`, `{{ (int)$x }}`, `{{ item.name }}` | left as literal text (does not start with `$` or a call) |

- Raw, unescaped HTML (trusted content only): `<?= $html ?>`.
- A whole attribute cannot come from `{{ }}` because quotes are escaped: `{{ $on ? 'aria-current="page"' : '' }}` prints `aria-current=&quot;page&quot;`. Output the value instead: `aria-current="{{ $on ? 'page' : 'false' }}"`, or use `<?= ... ?>`.
- Alpine-looking `{{ total() }}` is compiled as a **PHP** call. Use `x-text="total()"` for Alpine output.

## `p-if`: conditional element

```html
<div p-if="$bShowDetails" class="card">
    <h2>Details</h2>
    <p>{{ $name }}</p>
</div>
<div p-if="!$bShowDetails" class="card">Nothing yet.</div>

<p p-if="count($errors) > 0" class="error">Please fix {{ count($errors) }} fields.</p>
<span p-if="$isNew" class="badge {{ $tone }}">New</span>
<input p-if="$editable" name="title" value="{{ $title }}">
```

Compiles to `<?php if(cond): ?>` + the element without the attribute + `<?php endif; ?>`.

- Works on one line or many, with nested same-tag children, with `{{ }}`, `>` or `=>` in other attributes, and on void elements.
- The element **must be closed** (or be void/self-closing). Otherwise only the opening tag is wrapped and the content always renders (the compiler logs `has no closing </tag>`).
- The condition is any PHP expression. Use single quotes inside a double-quoted attribute (`p-if="$user['role'] === 'admin'"`).
- `p-if` inside `<?php ?>`, HTML comments, `{{ }}` and `<script>`/`<style>` bodies is not converted.
- **There is no `p-else`.** Use a negated `p-if`, or raw PHP for if/elseif/else:

```html
<?php if ($user === null): ?>
    <a href="/login">Sign in</a>
<?php elseif ($user['admin']): ?>
    <AdminMenu/>
<?php else: ?>
    <p>Welcome back, {{ $user['name'] }}</p>
<?php endif; ?>
```

## `p-for`: repeated element

```html
<li p-for="$fruit in $fruits">{{ $fruit }}</li>

<a p-for="$route in $routes" href="{{ $route['url'] }}">{{ $route['title'] }}</a>

<tr p-for="$id => $product in $products">
    <td>{{ $id }}</td>
    <td>{{ $product['name'] }}</td>
</tr>

<option p-for="$n in range(1, 10)" value="{{ $n }}">{{ $n }}</option>

<li p-for="$n in $numbers" p-if="$n % 2 === 0">{{ $n }} is even</li>
```

Compiles to `<?php foreach (phpue_iterable((expr) ?? null) as $item): ?>…<?php endforeach; ?>`.

- Syntax: `$item in <expr>` or `$key => $value in <expr>`. `<expr>` can be a variable, an array index, a function call, a `PDOStatement`, an `ArrayIterator` or a generator.
- `null`, unset variables and scalars render nothing (no warning).
- Nested same-tag children are fine: `<div p-for="$r in $rows"><div>{{ $r['v'] }}</div></div>`.
- `p-for` + `p-if` on one element: loop first, then filter each item.
- A component tag can loop: `<ProductCard p-for="$product in $products" />` renders the component once per item, and the component reads `$product`.
- Invalid syntax (`p-for="item of $items"`) is not converted; the attribute becomes `data-phpue-invalid-p-for`.
- The loop variable stays defined after the loop (plain PHP `foreach`), so use specific names.

## Forms: no `p-model`, by design

PHPue is privacy-first: no two-way binding, no keystroke tracking. A `p-model` regex still exists in `conversion.php` only as an abandoned placeholder; **never use it**. Write the attributes yourself and submit on purpose:

```html
<form method="post">
    <input name="email" type="email" value="{{ $email }}" required>
    <textarea name="message">{{ $message }}</textarea>
    <select name="topic">
        <option p-for="$t in $topics" value="{{ $t }}">{{ $t }}</option>
    </select>
    <button type="submit" name="send" value="1">Send</button>
</form>
```

Handle it in the same view's `<script>` (`if (($_POST['send'] ?? '') === '1') { ... }`), or post JSON to an `@AJAX` function without a reload ([@AJAX](/docs?topic=ajax)). Live client-side state, if you need it, is the browser's job (plain JS or Alpine `x-model`), not a PHPue directive.

## Raw PHP in templates

`<?php ... ?>` and `<?= ... ?>` pass straight through. Use them for if/elseif/else, loops over complex data, setting variables that a following component will read, and trusted raw HTML.

```html
<?php foreach ($techStack as $tech => $data): ?>
    <div class="card {{ $data['color'] }}">
        <h4>{{ $tech }}</h4>
    </div>
<?php endforeach; ?>
```

## Inline `<style>` and `<script>`

- `<style>` inside a template is fine (component-local CSS, printed wherever the component renders).
- `<script src>`, `<script type="module">` and bare `<script>` tags inside a template are fine in 0.0.3. Prefer `<cscript>` for page JS. Do not put the text `<template>` inside a JS string in an inline script (it counts toward template nesting).

## Showing PHPue code as text (docs, tutorials)

The compiler would run code samples, so escape them:

- `{{ ... }}` as `&#123;&#123; $title &#125;&#125;`.
- Tags as `&lt;template&gt;`, `&lt;script&gt;`, `&lt;li p-for="$item in $items"&gt;` (escaped tags are never converted in 0.0.3).
- In PHP strings, split closing script tags: `'</scr' . 'ipt>'`.
- Or keep samples in a data file (markdown, JSON) and print them escaped with `<?= htmlspecialchars($code) ?>`, which is how this site shows its examples.


---

<!-- Source: https://ai.phpue.co.uk/docs?topic=components | Markdown: https://ai.phpue.co.uk/knowledge/components.md -->

# Components and inherited scope

> A PHPue component is any `.pvue` file pulled in with `@require Name 'path.pvue';` and placed with `<Name/>`. At compile time its PHP, markup and cscript are **inlined** where the tag is, so it runs in the parent's scope and sees every variable the parent has, exactly like a PHP `include`. That is why PHPue has **no props, slots or emits**: set a variable before the tag, and the component reads it.

## Declare and place

```html
<!-- views/products.pvue -->
<script>
    @require ProductCard 'components/cards/ProductCard.pvue';
    @require EmptyState 'components/EmptyState.pvue';

    $products = [
        ['name' => 'Tea', 'price' => 3.5],
        ['name' => 'Coffee', 'price' => 4.0],
    ];
</script>

<template>
    <section class="grid">
        <ProductCard p-for="$product in $products" />
    </section>
    <EmptyState p-if="count($products) === 0"/>
</template>
```

```html
<!-- components/cards/ProductCard.pvue -->
<script>
    // $product comes from the parent's p-for. Default it so the card also works on its own.
    $product = $product ?? ['name' => 'Unknown', 'price' => 0];
</script>

<template>
    <article class="card">
        <h3>{{ $product['name'] }}</h3>
        <p>£{{ number_format($product['price'], 2) }}</p>
    </article>
</template>
```

- `@require` takes single or double quotes; the path is relative to the web root (`www/`).
- Tags: `<Name/>`, `<Name />` or `<Name></Name>`. **No other attributes and no children.** The only exceptions are `p-if` and `p-for` on the tag (0.0.3).
- Components can `@require` other components. Paths are always from the web root.
- A missing file compiles to a comment and renders nothing. Using `<Name/>` without `@require` renders nothing useful either.

## Giving a component data (instead of props)

Set variables right before the tag, in raw PHP:

```html
<?php
    $panelTitle = 'Traffic';
    $panelRows  = $trafficRows;
?>
<StatsPanel/>

<?php
    $panelTitle = 'Revenue';
    $panelRows  = $revenueRows;
?>
<StatsPanel/>
```

```php
// components/StatsPanel.pvue <script>: normalise what you inherit
$panelTitle = $panelTitle ?? '';
$panelRows  = (isset($panelRows) && is_array($panelRows)) ? $panelRows : [];
```

- Use specific names (`$panelTitle`, not `$title`): a component's writes go straight into the parent scope and stay visible after it.
- Inside a loop no setup is needed: the component reads the loop variable.
- Do **not** invent a props mechanism (attributes, a `$props` array, `extract()`). It does not exist and is not needed.

## Rules for component code

- **No named functions or classes** in a component's `<script>`. The code runs once per placement, so a second use (or a `p-for`) fails with `Cannot redeclare`. Put helpers in `backend/` or use closures (`$fmt = fn($n) => number_format($n, 2);`).
- **`<header>` is ignored** in components. Put CSS in a `<style>` inside the component's template, or in the App/view header.
- **`<cscript>` repeats** every time the component renders. Top-level `let`/`const` then throws `Identifier has already been declared`. Use `function` declarations, `var`, or wrap the code in an IIFE with a guard:

```js
(function () {
    if (window.__cartWidgetReady) return;
    window.__cartWidgetReady = true;
    document.addEventListener('click', function (e) { /* ... */ });
})();
```

- **`@AJAX` in components** works in 0.0.3 (handlers are global and built into `.dist/ajax/ajax-component-<Name>.php`). Keeping handlers in the view that hosts the component is still the clearest layout.
- Avoid these variable names, which the compiled preamble resets: `$routing`, `$current_route`, `$b404`, `$input`, `$action`.

## Components in App.pvue vs views

Components placed in `App.pvue` (navbar, footer, cookie banner) run in the **App scope**; components placed in a view run in that **view's scope**. App variables are not visible in views and vice versa. Share data through a `backend/` singleton, `$_SESSION` or `define()` ([backend and scope](/docs?topic=backend)).

## Rendering one component on its own (partials)

Components only exist inlined at compile time. To return one component's HTML from an `@AJAX` handler (for HTMX or `fetch` + `innerHTML`), compile it with `convert_pvue_file()` in a backend helper and pass the variables it would normally inherit. See the `PHPueFragment` helper in [cscript, AlpineJS, x-ssr and HTMX](/docs?topic=client-js).


---

<!-- Source: https://ai.phpue.co.uk/docs?topic=routing | Markdown: https://ai.phpue.co.uk/knowledge/routing.md -->

# Views, routing and 404 pages

> PHPue routes by file name: `views/about.pvue` is served at `/about` and `views/index.pvue` at `/`. Only files directly inside `views/` are routes, so `/blog/my-post` is a 404. Use query strings (`/blog?post=my-post`) and branch inside one view. Register every view in `App.pvue` with `#require 'views/name.pvue';`.

## Routes

| File | URL |
|---|---|
| `views/index.pvue` | `/` |
| `views/about.pvue` | `/about` (also `/about/`) |
| `views/get-started.pvue` | `/get-started` |
| `views/blog/post.pvue` | not a route |

- The route slug is the URL path with slashes trimmed. It is stored in `$_GET['page']`, so **`page` is a reserved query parameter**: `?page=2` is overwritten. Paginate with `?p=2` or `?pagination=2`.
- Register views in `App.pvue` (one per line, no name before the path):

```php
#require 'views/index.pvue';
#require 'views/about.pvue';
```

`#require About 'views/about.pvue';` (with a name) is silently ignored: PHP treats it as a comment. Routing scans `views/*.pvue` regardless, but `#require` every view; it is the convention, and 0.0.2 builds depend on it.

- `<View/>` (or `<View />`, `<View></View>`) goes once in the App template and is replaced by the current page.

## Sub-pages with query parameters

```html
<!-- views/tutorials.pvue -->
<script>
    @require TutorialList 'components/tutorials/TutorialList.pvue';
    @require FirstApp 'components/tutorials/FirstApp.pvue';
    @require Styling 'components/tutorials/Styling.pvue';

    $tutorial = preg_replace('/[^a-z0-9-]/', '', $_GET['name'] ?? '');
</script>

<template>
    <?php if ($tutorial === 'first-app'): ?>
        <FirstApp/>
    <?php elseif ($tutorial === 'styling'): ?>
        <Styling/>
    <?php else: ?>
        <TutorialList/>
    <?php endif; ?>
</template>
```

Always sanitise or allow-list query values before using them in paths or queries.

For pretty URLs, the author's PrettyUrlRedirect extension 301-redirects `/page/key/value` to `/page?key=value`.

## Navigation helpers

Available in every `.pvue` file and in `backend/`:

- `phpue_navigation()` returns `[['name' => 'about', 'title' => 'About', 'url' => '/about'], ...]`. The title comes from each view's `<title>` (or `ucfirst(name)`). Order is file order, so sort or filter it yourself.
- `get_current_route()` returns the current slug (`index` for `/`).
- `phpue_current_meta()` returns the current view's parsed header meta.
- Active link: compare `parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH)` with the link URL and set `aria-current="{{ $isCurrent ? 'page' : 'false' }}"`.

```html
<!-- components/Navbar.pvue -->
<script>
    $navRoutes = array_filter(phpue_navigation(), fn($r) => $r['name'] !== 'admin');
    $navCurrent = get_current_route();
</script>

<template>
    <nav aria-label="Main">
        <a p-for="$r in $navRoutes" href="{{ $r['url'] }}" aria-current="{{ $r['name'] === $navCurrent ? 'page' : 'false' }}">{{ $r['title'] }}</a>
    </nav>
</template>
```

## 404 pages

Unknown routes return HTTP 404 and render inside the App layout (navbar and footer stay):

- `httpReqs/http404.php`: plain PHP/HTML body that replaces `<View/>`.
- `httpReqs/http404Head.php`: head tags for the 404 page:

```php
<?php
global $phpue_header;
$phpue_header = <<<HTML
    <title>404 - Page Not Found</title>
    <meta name="robots" content="noindex">
HTML;
$GLOBALS['phpue_http404_header'] = $phpue_header;
?>
```

Without these files PHPue prints a default "404 - Page Not Found" heading. Only 404 is built in; for other errors, set `http_response_code()` in the view script.

## Where the view's code runs

A view's compiled code runs inside a framework method, in its **own scope**, after the App script and App header. So:

- Variables from `App.pvue` are not visible in views. Use `backend/` singletons, `$_SESSION` or `define()`.
- Output is buffered, so `header()`, `setcookie()`, redirects (`header('Location: /login'); exit;`) and `http_response_code()` all work from a view's `<script>`.
- `phpue_set_lang()` is too late in a view (`<html lang>` is already printed); call it in the App script or `backend/`, or put `<meta name="lang" content="cy">` in the view header.


---

<!-- Source: https://ai.phpue.co.uk/docs?topic=ajax | Markdown: https://ai.phpue.co.uk/knowledge/ajax.md -->

# @AJAX: server functions for the browser

> Put `@AJAX('POST')` or `@AJAX('GET')` directly before a PHP function in a `<script>` block and the browser can call it: POST a JSON body with `"action": "functionName"`, or GET `?action=functionName`. The function receives the request data as `$input` and must **`echo`** its response (usually `json_encode`); return values are discarded. Handlers run before any page code and end the request.

## Server side

```php
<script>
    @AJAX('POST')
    function saveNote($input) {
        $text = trim((string) ($input['text'] ?? ''));
        header('Content-Type: application/json');

        if ($text === '' || mb_strlen($text) > 500) {
            http_response_code(422);
            echo json_encode(['ok' => false, 'error' => 'Write 1-500 characters']);
            return;
        }

        $_SESSION['notes'][] = $text;
        echo json_encode(['ok' => true, 'count' => count($_SESSION['notes'])]);
    }

    @AJAX('GET')
    function listNotes($input) {
        header('Content-Type: application/json');
        header('Cache-Control: no-store');
        echo json_encode($_SESSION['notes'] ?? []);
    }
</script>
```

- Declaration (0.0.3): `@AJAX('POST')` or `@AJAX("GET")`, then `function name(...)`. Typed parameters, defaults and return types are fine: `@AJAX('POST') function save(array $input = []): void {`.
- `$input` is the decoded JSON body for POST, or `$_GET` for GET (which also contains `page`). A function with no parameters is called with none.
- The declared method is **enforced**: the other method gets `405` with an `Allow:` header and `{"error": "@AJAX 'name' only accepts POST"}`.
- Only `@AJAX` functions can be called. If `action` names anything else, the request falls through and returns the normal HTML page (status 200), so check `response.ok` and the content type on the client.
- **`echo`, don't `return`.** Set `Content-Type: application/json` and use `http_response_code()` for errors.
- Handlers run **before** the App and view scripts: they cannot see variables from those scripts. Load what you need inside the handler (a `backend/` singleton, `$_SESSION`).
- POST handlers always have a session (PHPue starts one, even with lazy sessions). GET handlers only have one if the visitor already has a session cookie; call `phpue_session(true)` before writing.
- Function names are global across the whole app: keep them unique.
- Handlers from App, every view and every component are available on every page, in source mode and in the built `.dist/`. Posting to the page that owns the handler (`fetch('')`) is the clearest convention.

## Client side

```js
// POST: JSON body with an "action"
async function saveNote(text) {
    const res = await fetch('', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ action: 'saveNote', text })
    });
    const data = await res.json();
    if (!res.ok || !data.ok) throw new Error(data.error || 'Save failed');
    return data;
}

// GET: query string
const notes = await fetch('?action=listNotes').then(r => r.json());
```

`fetch('')` posts to the current URL. Use `window.location.pathname` if the page has query parameters you do not want to resend.

## Submitting a form through @AJAX

```html
<template>
    <form onsubmit="submitForm(event, 'subscribe')">
        <input name="email" type="email" required>
        <button type="submit">Subscribe</button>
    </form>
    <p id="subscribeResult" role="status"></p>
</template>

<cscript>
    async function submitForm(event, action) {
        event.preventDefault();
        const fields = Object.fromEntries(new FormData(event.target));
        const res = await fetch('', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ action, ...fields })
        });
        const data = await res.json();
        document.getElementById('subscribeResult').textContent = data.message;
    }
</cscript>
```

```php
@AJAX('POST')
function subscribe($input) {
    header('Content-Type: application/json');
    $email = filter_var($input['email'] ?? '', FILTER_VALIDATE_EMAIL);
    if (!$email) {
        http_response_code(422);
        echo json_encode(['message' => 'Please enter a valid email.']);
        return;
    }
    // Newsletter::getInstance()->add($email);
    echo json_encode(['message' => 'Thanks, you are subscribed.']);
}
```

## The common pattern: mutate, then reload

The simplest PHPue interaction loop needs almost no JavaScript: an `@AJAX` handler changes `$_SESSION` or the database, the client calls `location.reload()`, and the server renders the new state. For no-reload updates, echo JSON and patch the DOM in `<cscript>`, or use AlpineJS ([client JS](/docs?topic=client-js)).

## File uploads and other non-JSON requests

The dispatcher only reads JSON bodies for POST, so `FormData` / multipart uploads do not reach `@AJAX` (you get the HTML page back). Use a backend endpoint instead:

```php
<?php
// backend/endpoints/upload.php (runs on every request; only acts on its own URL)
if (isset($_GET['api'], $_GET['endpoint']) && $_GET['endpoint'] === 'avatarUpload') {
    header('Content-Type: application/json');
    if ($_SERVER['REQUEST_METHOD'] !== 'POST' || !isset($_FILES['avatar'])) {
        http_response_code(400);
        echo json_encode(['ok' => false]);
        exit;
    }
    // validate type and size, move_uploaded_file(...), store the result
    echo json_encode(['ok' => true]);
    exit;
}
```

Client: `fetch('?api&endpoint=avatarUpload', {method: 'POST', body: new FormData(form)})`.

## Security checklist

- Validate and authorise **inside every handler**; `$input` is untrusted user data.
- Add CSRF protection for state-changing handlers on logged-in sites (a token stored in `$_SESSION`, sent in the JSON body, compared with `hash_equals`).
- Escape anything you send back that the client will insert as HTML, or insert it with `textContent`.
- GET handlers can be cached by proxies for anonymous visitors: send `Cache-Control: no-store` for per-user data.
- On 0.0.2 the dispatcher calls **any** existing PHP function named in `action` (including built-ins) and ignores the declared method. Upgrade to 0.0.3.


---

<!-- Source: https://ai.phpue.co.uk/docs?topic=backend | Markdown: https://ai.phpue.co.uk/knowledge/backend.md -->

# backend/, scope, sessions and language

> Every `*.php` file under `backend/` is `require_once`d on every request, before routing and `@AJAX` dispatch. Put classes, singletons, database access, API clients and helper functions there. App, views and `@AJAX` handlers each run in their own scope, so `backend/` singletons (or `$_SESSION`, `define()`) are how they share data. Sessions are controlled by `PHPUE_SESSION` (`'auto'` or `'lazy'`).

## backend/ autoloading

- Files load recursively in sorted path order (0.0.3). If a folder contains `autoload.php`, **only that file** is loaded for the folder and PHPue does not scan deeper. Use it to fix load order (`extends` across files) or to keep data files out of the scan.
- Files run on every request, including AJAX calls and 404s. Keep them to definitions and idempotent bootstraps. **Never echo** from them (except dedicated endpoint files that `exit`).
- Composer: put `vendor/` inside `backend/` (its `autoload.php` stops the scan there). Do not add Composer at the project root.
- A file that `return`s an array (config, language pack) must not be loaded twice with `require_once`, because the second call returns `true`. Keep such files in a folder with an `autoload.php`, or load them with `require`.

## The singleton pattern (author's convention)

```php
<?php
// backend/Database.php
class Database {
    private static ?self $instance = null;
    private ?PDO $pdo = null;

    public static function getInstance(): self {
        return self::$instance ??= new self();
    }

    public function pdo(): PDO {
        return $this->pdo ??= new PDO('sqlite:' . getcwd() . '/data/app.sqlite', null, null, [
            PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
            PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
        ]);
    }

    public function latestPosts(int $limit = 10): array {
        $stmt = $this->pdo()->prepare('SELECT id, title, body FROM posts ORDER BY id DESC LIMIT :limit');
        $stmt->bindValue(':limit', $limit, PDO::PARAM_INT);
        $stmt->execute();
        return $stmt->fetchAll();
    }
}
```

Use it from any view, component, App or `@AJAX` handler: `$posts = Database::getInstance()->latestPosts(5);`. Keep secrets in a git-ignored file (for example `backend/env.php` with `putenv('DB_PASS=...')` or `define()`), and use prepared statements for every query.

## Scope: who sees what

| Code | Scope |
|---|---|
| `App.pvue` script + components placed in App | App scope |
| A view's script + components placed in that view | that view's scope |
| `@AJAX` functions | plain functions, called before the App/view scripts run |
| `backend/` files | their classes, functions and constants are global; loose variables are not (expose data through a class) |

Request order: backend files load, the session starts (per `PHPUE_SESSION`), `@AJAX` dispatch (exits if it matches), App script, `<head>`, App template, then the view's script and template at `<View/>`.

So an App variable is **undefined** in a view, and a handler cannot see page variables. Share data with:

- a backend singleton (best: `Config::getInstance()->get('siteName')`),
- `define('SITE_NAME', '...')` in the App script or backend,
- `$_SESSION` (per visitor),
- `$GLOBALS['x']` (request-wide, use sparingly).

## Sessions: `PHPUE_SESSION`

Set in `index.php`: `define('PHPUE_SESSION', 'lazy');`

| Mode | Behaviour | Use for |
|---|---|---|
| `'auto'` (default) | `session_start()` on every request, like 0.0.2 | apps where every visitor has state |
| `'lazy'` | only resumes a session the visitor already has; anonymous pages send no `Set-Cookie` and stay cacheable | public sites, docs, blogs, anything behind a cache or CDN |

With `'lazy'`:

- Reading `$_SESSION` needs nothing: it is simply empty for new visitors.
- Before **writing** during page rendering (or in a GET handler, or backend code), call `phpue_session(true)`.
- POST `@AJAX` handlers start a session automatically.
- Extensions and backend code should call `phpue_session()` / `phpue_session(true)` instead of `session_start()`.
- If the App script text contains `session_start()` (even in a comment), PHPue's session handling switches off entirely.

```php
// a view that remembers the last search (lazy sessions)
$query = trim($_GET['q'] ?? '');
if ($query !== '') {
    phpue_session(true);
    $_SESSION['lastQuery'] = $query;
}
$lastQuery = $_SESSION['lastQuery'] ?? '';
```

## Language: `<html lang>`

Priority per request: `phpue_set_lang('cy')` > the view header's `<meta name="lang" content="cy">` > `PHPUE_LANG` (`'en'` in `index.php`). `phpue_html_lang()` returns the resolved value.

Call `phpue_set_lang()` in the **App script** or a `backend/` bootstrap. A view runs after `<html lang>` is printed, so calling it there is too late.

## File paths

`__DIR__` inside `.pvue` code is `www/` in source mode but `www/.dist` or `www/.dist/pages` after a build, so paths built from it break in production. Use `getcwd()`, which is always the web root:

```php
$posts = json_decode(file_get_contents(getcwd() . '/data/posts.json'), true);
```

Inside `backend/*.php` files, `__DIR__` is that file's real folder and is safe to use for files next to it (the build copies `backend/` into `.dist/backend/`).

## Other runtime helpers (0.0.3)

- `phpue_session(bool $write = false)`: resume, or with `true` start, the session.
- `phpue_set_lang(string $lang)` / `phpue_html_lang()`.
- `phpue_iterable($x)`: returns `$x` if iterable, otherwise `[]` (what `p-for` uses).
- `phpue_navigation()`, `get_current_route()`, `phpue_current_meta()`: see [routing](/docs?topic=routing).


---

<!-- Source: https://ai.phpue.co.uk/docs?topic=client-js | Markdown: https://ai.phpue.co.uk/knowledge/client-js.md -->

# cscript, AlpineJS, x-ssr and HTMX

> PHPue renders everything on the server; the browser layer is optional. Use `<cscript>` for plain JavaScript (PHP values arrive through `{{ $var }}`, which is `json_encode`d). Add AlpineJS when a page needs client-side state, and the official **x-ssr** Alpine extension when Alpine must update a list that PHP already rendered. HTMX works for SPA-like navigation without leaving server rendering.

## PHP data in `<cscript>`

```html
<cscript>
    const count = {{ $count }};                 // 3
    const fruits = {{ $fruits }};               // ["Apple","Pear"]
    const user = {{ $user }};                   // {"name":"Ada"}
    const items = {{ $data['items'] }};         // any $ expression (0.0.3)
    const total = <?= json_encode(count($fruits)) ?>;   // function calls: json_encode yourself
</cscript>
```

- `{{ $expr }}` becomes `json_encode($expr, JSON_HEX_TAG|JSON_HEX_APOS|JSON_HEX_QUOT|JSON_HEX_AMP)`. **Never wrap it in quotes**: `"{{ $name }}"` gives `""Ada""`.
- Function calls are not converted inside cscript; use `<?= json_encode(...) ?>`.
- A cscript with a line starting `import`/`export` becomes `<script type="module">`; module functions are not global, so assign `window.fn = fn` for inline `onclick` handlers.
- It runs where it is printed (after its markup). Use `DOMContentLoaded` for elements further down.
- Vanilla style used by the author: global functions plus inline handlers (`<button onclick="addToCart(3)">`).

## AlpineJS

Load Alpine with `defer` from the App header (site-wide) or a view header (one route). Register components inside `alpine:init`, in a `<cscript>` or a non-deferred script, so they exist before Alpine starts.

```html
<!-- views/counter.pvue -->
<script>
    @AJAX('POST')
    function saveCount($input) {
        $_SESSION['count'] = max(0, (int) ($input['count'] ?? 0));
        header('Content-Type: application/json');
        echo json_encode(['ok' => true]);
    }

    $start = (int) ($_SESSION['count'] ?? 0);
</script>

<header>
    <script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.14.1/dist/cdn.min.js"></script>
</header>

<template>
    <div x-data="counter">
        <button @click="increment()">Clicked <span x-text="count">{{ $start }}</span> times</button>
    </div>
</template>

<cscript>
    document.addEventListener('alpine:init', () => {
        Alpine.data('counter', () => ({
            count: {{ $start }},
            async increment() {
                this.count++;
                await fetch('', {
                    method: 'POST',
                    headers: { 'Content-Type': 'application/json' },
                    body: JSON.stringify({ action: 'saveCount', count: this.count })
                });
            }
        }));
    });
</cscript>
```

Rules:

- All Alpine attributes pass through untouched: `x-data`, `x-show`, `x-text`, `x-model`, `:class`, `@click`, `<template x-for>`, `<template x-if>` (close every `<template>`).
- **Render the server value as fallback content** inside `x-text` elements (`<span x-text="count">{{ $start }}</span>`), so the page is correct before Alpine boots and for crawlers.
- Do not use mustache output for Alpine: `{{ count }}` stays literal and `{{ total() }}` is compiled as a PHP call. Use `x-text`.
- Alpine `@click` never conflicts with PHPue's `@require`/`@AJAX`, which only exist inside `<script>`.
- `x-model` on form fields is fine when the state lives in the browser. PHPue itself has no binding (`p-model` does not exist).
- An `x-for` list has no server-rendered rows, so crawlers and the first paint see nothing. For SEO-relevant lists, render with `p-for` and hand over to x-ssr.

## x-ssr: keep the server-rendered list, update it from Alpine

The official **x-ssr** extension (by Edward Patch, in [PHPue-Extensions](https://github.com/PHPue/PHPue-Extensions), branch `Client-Side-Extensions`) is a keyed list directive. It **adopts the server-rendered items as they are**, then adds, removes and reorders items when the Alpine array changes, without throwing away or flickering the SSR markup.

```html
<header>
    <script defer src="/assets/js/fworks/alpine.min.js"></script>
    <!-- not defer/async: it must register before Alpine starts -->
    <script src="/assets/js/phpue-ext-csr/alpine.ext.min.ssr.js"></script>
</header>

<template>
    <div x-data="taskList">
        <input x-model="filter" placeholder="Filter tasks">
        <ul x-ssr="visibleTasks" x-ssr-key="id" x-ssr-template="taskTemplate">
            <li p-for="$task in $tasks" data-id="{{ $task['id'] }}">{{ $task['title'] }}</li>
        </ul>
    </div>
</template>

<cscript>
    document.addEventListener('alpine:init', () => {
        Alpine.data('taskList', () => ({
            tasks: {{ $tasks }},
            filter: '',
            get visibleTasks() {
                return this.tasks.filter(t => t.title.toLowerCase().includes(this.filter.toLowerCase()));
            },
            taskTemplate: {
                html: `<li>\${item.title}</li>`,
                process(el, item, component) { /* wire events, nested data */ }
            }
        }));
    });
</cscript>
```

- `x-ssr="expr"` must evaluate to an array; `x-ssr-key` names the identity property (default `id`); `x-ssr-template` names the template on the component (default `csrTemplate`).
- Each SSR item needs `data-{key}` equal to `String(item[key])` in the Alpine array. Put `p-for` on the keyed element itself.
- SSR nodes are kept as they are (never re-rendered); client-rendered nodes are rebuilt on every change. To update an item's content, give it a key that includes a revision (`sku@3`).
- Template `html` uses `${item.prop}` placeholders (top-level properties only, HTML-escaped). Inside a JS template literal escape them as `\${item.prop}`. One root element. `process(el, item, component)` runs after each client-rendered node is created.
- Works on `<tbody>` / `<tr>` for tables, inside empty containers for pure client lists, and with `x-intersect` for infinite scroll (first page in PHP, more via `@AJAX('GET')`).
- Builds: `alpine.ext.dev.ssr.js` (console tracing), `alpine.ext.prod.ssr.js`, `alpine.ext.min.ssr.js`.
- Keep the PHP filter/pagination logic and the JS getters identical, and sync state to the URL (`history.pushState`) so a reload server-renders the same view.

## HTMX (optional)

PHPue works with HTMX for SPA-like navigation that stays server-rendered:

```html
<!-- App.pvue template -->
<div hx-boost="true" hx-target="#view" hx-select="#view" hx-swap="outerHTML show:window:top">
    <Navbar/>
    <div id="view"><View/></div>
</div>
```

- Boosted clicks still request the full page; HTMX swaps `#view` and updates the title and URL. Load all CSS/JS from the **App header** (view headers are not re-applied after a swap).
- HTMX posts form-encoded data, but `@AJAX` POST needs JSON: add a small `json-enc` extension (`htmx.defineExtension('json-enc', ...)` that sets `Content-Type: application/json` and returns `JSON.stringify(parameters)`), then `<button hx-post="/" hx-ext="json-enc" hx-vals="{{ $vals }}">` where `$vals = json_encode(['action' => 'addToCart', 'sku' => $sku])`. `hx-get="/?action=name"` needs nothing extra. The verb must match the `@AJAX` method.
- Handlers can send `header('HX-Trigger: ' . json_encode(['cart-updated' => $summary]))`.
- Register Alpine components globally (App-level JS) and pass server data as factory arguments (`x-data="cartPage({{ $linesJson }})"`); a view-local `Alpine.data()` is not defined yet when a swapped view initialises.

### Rendering one component as a partial

```php
<?php
// backend/PHPueFragment.php
class PHPueFragment {
    public static function render(string $__component, array $__vars = []): string {
        $rel = substr($__component, strlen('components/'), -5) . '.php';
        $__compiled = is_file('.dist/App.php') && is_file('.dist/components/' . $rel) ? '.dist/components/' . $rel
                    : (is_file('App.php') && is_file('components/' . $rel) ? 'components/' . $rel : null);
        $__php = $__compiled === null ? convert_pvue_file($__component) : null;
        extract($__vars, EXTR_SKIP);   // the variables an inline <Component/> would inherit
        ob_start();
        if ($__compiled !== null) include $__compiled; else eval('?>' . $__php);
        return ob_get_clean();
    }
}
```

`@AJAX('GET') function productCard($input) { echo PHPueFragment::render('components/ProductCard.pvue', ['product' => findProduct($input['sku'] ?? '')]); }`: one component, used inline and as a fragment.


---

<!-- Source: https://ai.phpue.co.uk/docs?topic=build-deploy | Markdown: https://ai.phpue.co.uk/knowledge/build-deploy.md -->

# Build, deploy, security and caching

> PHPue serves `.pvue` sources directly in development (compiling on each request) and a precompiled `.dist/` folder in production. Build with `php index.php build` from `www/`, then deploy `.dist/` together with `index.php`, `conversion.php`, `assets/`, `httpReqs/` and `.htaccess`. If `.dist/` exists, it is always used, so delete it while developing.

## Serving modes

`index.php` serves the first of these that exists:

| Priority | Present | Mode | Routes from |
|---|---|---|---|
| 1 | `.dist/App.php` | compiled (production) | `.dist/pages/*.php` |
| 2 | `App.php` in the web root | extracted compiled deploy | `pages/*.php` |
| 3 | `App.pvue` | source (development): compiles on every request | `views/*.pvue` |

**A stale `.dist/` (or stray `App.php`) in a dev checkout means your `.pvue` edits do nothing.** Delete it, or rebuild after every change.

## Development tools

- `cd www && php -S localhost:3000`, then open `http://localhost:3000`. Do not pass `index.php` as a router script.
- `?live`: hot reload (watches `App.pvue`, `views/` and `components/` recursively).
- `?compile=views/page.pvue` (add `&root=true` for `App.pvue`): shows the compiled PHP.
- In 0.0.3, `?compile=`, `?hot-reload` and the web `?build` only work in source mode. `define('PHPUE_DEV_TOOLS', true|false);` in `index.php` overrides this; never force it on in production.
- Docker: `php:8.2-fpm` + `nginx` with `./www` mounted at `/var/www/html` (the PHPue repository includes `docker-compose.yaml` and `nginx/default.conf`).

## Build

```bash
cd www
npm run build            # only if you use the Tailwind CLI: rebuild CSS first
php index.php build      # writes .dist/
```

```text
.dist/
├── App.php            compiled App.pvue (components inlined)
├── pages/<view>.php   every view
├── ajax/              @AJAX handlers: ajax-App.php, ajax-<view>.php, ajax-component-<Name>.php
├── components/        compiled copies (reference only; components are inlined)
├── backend/           copy of backend/
├── httpReqs/          copy of httpReqs/
└── assets/            copy of assets/
```

Rebuild after any change to `.pvue` files, `backend/` or `assets/` (they are copied).

## Deployment options

**1. Compiled `.dist/` (recommended).** Upload `.dist/`, `assets/`, `httpReqs/`, `index.php`, `conversion.php`, `.htaccess`. Block direct web access to `.dist/`. `.dist/` is always served through `index.php` + `conversion.php`; compiled files are never entry points on their own.

**2. Extracted.** Copy the **contents** of `.dist/` into the web root (`App.php`, `pages/`, `ajax/`, `components/`, `backend/`, `httpReqs/`, `assets/`) next to `index.php`, `conversion.php` and `.htaccess`. Block `App.php` and those folders from direct access.

**3. Source on the server.** Upload the `.pvue` sources and let the server compile per request. You must block `.pvue`, `views/`, `components/` and `backend/`, and remember that source mode enables the dev tools. Prefer options 1 or 2.

Any host with PHP 8.0+ works: shared hosting/cPanel, a VPS with nginx or Apache, Docker, FTP upload. No Node.js on the server.

## Apache `.htaccess`

```apache
RewriteEngine On

<FilesMatch "\.pvue$">
    Require all denied
</FilesMatch>
<FilesMatch "^App\.php$">
    Require all denied
</FilesMatch>

# Source + compiled internals
RewriteRule ^(\.dist|ajax|pages|backend|httpReqs|components|views)(/.*)?$ - [F,L]

# Legacy redirects go here, before the front controller
# RewriteRule ^old-page/?$ /new-page [R=301,L]

# Front controller
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php?page=$1 [QSA,L]
```

## nginx

```nginx
server {
    listen 80;
    root /var/www/html;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.pvue$ { deny all; return 404; }
    location ~ ^/(\.dist|ajax|pages|backend|httpReqs|components|views)(/|$) { deny all; return 404; }
    location = /App.php { deny all; return 404; }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_pass php:9000;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }

    location ~ /\.ht { deny all; }
}
```

## Security notes

- 0.0.3 only dispatches functions marked `@AJAX`, with their declared method. Still validate and authorise inside every handler.
- `{{ }}` in the App header and `<?= ?>` are unescaped: escape when you build those strings.
- `backend/` runs on every request (including AJAX and 404s): keep it side-effect-light, never echo.
- Keep secrets out of git (`backend/env.php` in `.gitignore`).
- Deploy compiled output and keep `.pvue` sources and dev tools off production.

## Caching and crawlers

With `PHPUE_SESSION = 'auto'` (the default) every response starts a session, which sends `Set-Cookie` and `Cache-Control: no-store`, so nginx, CDNs and proxies never cache a page. For public sites:

1. In `index.php`: `define('PHPUE_SESSION', 'lazy');`
2. Call `phpue_session(true)` before writing `$_SESSION` while rendering (POST `@AJAX` handlers already have a session).
3. Send your own cache headers for anonymous visitors, for example in the App script:

```php
if (session_status() !== PHP_SESSION_ACTIVE) {
    header('Cache-Control: public, max-age=300');
}
```

nginx `fastcgi_cache`: bypass and skip caching when the visitor has a session cookie (`fastcgi_cache_bypass $cookie_PHPSESSID; fastcgi_no_cache $cookie_PHPSESSID;`), and add `$http_hx_request` to the cache key if you use HTMX.

## SEO and GEO checklist

- One `<title>` and meta description per page: static in each view header, or dynamic from the App header via the [MetaControl extension](/docs?topic=extensions).
- Real content in the server-rendered HTML (render lists with `p-for`, not only Alpine `x-for`).
- Canonical URLs, a `sitemap.xml`, a `robots.txt` that allows the crawlers you want, and JSON-LD structured data.
- For AI agents, an `/llms.txt` index and markdown versions of key pages. This site serves them from a `backend/` file that answers those URLs before routing (see its source on [GitHub](https://github.com/PHPue/PHPue-AI)).
- Cacheable anonymous pages (lazy sessions) so crawlers and CDNs get fast responses.


---

<!-- Source: https://ai.phpue.co.uk/docs?topic=extensions | Markdown: https://ai.phpue.co.uk/knowledge/extensions.md -->

# Official extensions

> PHPue extensions are plain PHP classes in `backend/` (picked up by the autoloader) or JS files in `assets/`. The official ones live in [github.com/PHPue/PHPue-Extensions](https://github.com/PHPue/PHPue-Extensions), one branch per category. Use them instead of hand-rolling dynamic meta, a flat-file CMS or Alpine list hydration.

| Branch | Extension | Install into |
|---|---|---|
| `PHPue-Extensions` | **MetaControl**: dynamic titles, descriptions, Open Graph, canonicals | `www/backend/phpue-extensions/phpue-metacontrol.ext.php` |
| `PHPue-Extensions` | **Matrix CMS**: flat-file headless CMS with themes, sections and SEO fields | `www/backend/phpue-extensions/matrix-cms/` |
| `Client-Side-Extensions` | **x-ssr**: AlpineJS directive that keeps server-rendered lists | `www/assets/js/phpue-ext-csr/` |
| `Integrations-CMS-Bridges` | PHPue Elementor widget for WordPress | WordPress plugin |

Extension conventions: `namespace PHPueExt;`, a singleton `getInstance()`, a version guard such as `if (defined('PHPUE_VERSION') && version_compare(PHPUE_VERSION, '0.0.2', '>='))`, and session access through `function_exists('phpue_session') ? phpue_session(true) : session_start()` so they respect lazy sessions.

## MetaControl: per-page SEO from App.pvue

**Why:** view `<header>` blocks are static and the App script runs before the view, so per-request titles and meta must be decided early (in `backend/` or the App script) and printed by `App.pvue`'s header.

API (`\PHPueExt\MetaControl`, stored in the session):

| Method | Purpose |
|---|---|
| `getInstance()` | singleton (starts the session) |
| `setMetaVariable(string $key, mixed $value)` | store plain text or a full tag string |
| `getMetaVariable(string $key)` | read (`''` if unset) |
| `unsetMetaVariables()` | clear everything |
| `setRendered(bool)` / `getRendered()` | mark meta as produced, so the next page can clear it and avoid meta "bleeding" between pages |

Pattern: a backend **meta router** maps the first path segment to a small `*Meta` class that sets the variables, and App prints them:

```php
<?php
// backend/meta/BlogMeta.php
class BlogMeta {
    public static function apply(): void {
        $meta  = \PHPueExt\MetaControl::getInstance();
        $slug  = preg_replace('/[^a-z0-9-]/', '', $_GET['post'] ?? '');
        $title = $slug ? ucwords(str_replace('-', ' ', $slug)) . ' | Blog' : 'Blog';
        $meta->setMetaVariable('page-title', '<title>' . htmlspecialchars($title) . '</title>');
        $meta->setMetaVariable('page-description', '<meta name="description" content="' . htmlspecialchars($title) . '">');
        $meta->setRendered(true);
    }
}
```

```html
<!-- App.pvue -->
<script>
    if (get_current_route() === 'blog') BlogMeta::apply();
    $pageMeta  = \PHPueExt\MetaControl::getInstance();
    $pageTitle = $pageMeta->getMetaVariable('page-title');
    $pageDescription = $pageMeta->getMetaVariable('page-description');
</script>

<header>
    <meta charset="UTF-8">
    {{ $pageTitle }}
    {{ $pageDescription }}
</header>
```

- App header values are injected **raw**: escape inside the tag strings.
- Routes whose meta comes from MetaControl should have **no `<title>`** in their view header (the App one would win anyway).
- MetaControl uses the session, so pages using it are not cacheable anonymously. For a fully cacheable public site, compute the head tags from a sessionless backend class instead (this site does: see `PHPueKnowledge::headTags()` in its [source](https://github.com/PHPue/PHPue-AI)).

## Matrix CMS: flat-file content

`\PHPueExt\PHPueMatrix` stores pages as PHP files that return arrays (`pages/<route>/<slug>.php`) and renders them through theme closures (`themes/default.php`). No database; OpCache-friendly.

- Render: `PHPueMatrix::getPage($route, $slug)` returns body HTML.
- SEO: `getPageTitle`, `getPageDescription`, `getPageKeywords`, `getPageOgImage`, `getPageCanonical`, `getPageRobots`.
- CRUD: `createPage($route, $slug, $theme, $sections, $title, $status, $seo)`, `deletePage($route, $slug)`.
- Listing: `listPages($route)` returns `[slug, title, status, created]`; `listRoutes()`, `getTheme($name)`.
- Shortcodes in content: `[[year]]`, `[[namespace.key]]`, resolved by the theme.

```html
<!-- views/blog.pvue -->
<script>
    $slug = preg_replace('/[^a-z0-9-]/', '', $_GET['post'] ?? '');
    $pageHtml = $slug ? \PHPueExt\PHPueMatrix::getPage('blog', $slug) : '';
    $posts = array_filter(\PHPueExt\PHPueMatrix::listPages('blog'), fn($p) => $p['status'] === 'live');
</script>

<template>
    <?php if ($pageHtml): ?>
        <?= $pageHtml ?>
    <?php else: ?>
        <ul>
            <li p-for="$post in $posts"><a href="/blog?post={{ $post['slug'] }}">{{ $post['title'] }}</a></li>
        </ul>
    <?php endif; ?>
</template>
```

Caveats: **sanitise `$route` and `$slug`** before every call (they become file paths); **protect the admin view** (the example has no auth; add a login and CSRF); content lives inside `backend/`, so a fresh `.dist` deploy can overwrite pages created on production (back them up or move the pages folder); add an `autoload.php` in `matrix-cms/` so PHPue does not `require_once` every content file on each request.

## x-ssr (AlpineJS)

Server-rendered lists that Alpine can filter, sort, add to and remove from without re-rendering them. Works outside PHPue too. Full usage: [cscript, AlpineJS, x-ssr and HTMX](/docs?topic=client-js).

## Multilingual sites (pattern)

The author's LanguageSelector pattern for bilingual sites:

- A backend singleton reads an allow-listed `?lang=` (falling back to `Accept-Language`), stores it, and loads a language pack (`langs/English.php` returning `['nav_home' => 'Home', ...]`). Keep the packs in a folder with an `autoload.php` (they `return` arrays).
- Every consumer fetches the pack itself (App variables are not visible in views): `$t = LanguageSelector::getInstance()->getLanguagePack();`, then `{{ $t['nav_home'] }}`.
- Call `phpue_set_lang($lang)` in the App script so `<html lang>` follows the selection.
- Language switcher as crawlable links that change `?lang=` and keep other query parameters; emit `hreflang` alternates and a language-aware canonical for each page.
- Separate views per language for translated slugs (`views/blog.pvue` and `views/blogiau.pvue`).


---

<!-- Source: https://ai.phpue.co.uk/docs?topic=recipes | Markdown: https://ai.phpue.co.uk/knowledge/recipes.md -->

# Copy-ready recipes

> Complete PHPue 0.0.3 examples. Each was compiled with `convert_pvue_file()`, syntax-checked with `php -l`, and exercised with `php -S` and curl. File paths are relative to `www/`. Remember to add each view to `App.pvue` with `#require 'views/<name>.pvue';`.

## 1. Contact form with validation (no JavaScript)

Post/Redirect/Get: the form posts to the same page, the script validates, and on success redirects so a refresh does not resend.

```html
<!-- views/contact.pvue -->
<script>
    $errors = [];
    $name = trim((string) ($_POST['name'] ?? ''));
    $email = trim((string) ($_POST['email'] ?? ''));
    $message = trim((string) ($_POST['message'] ?? ''));
    $bSent = isset($_GET['sent']);

    if ($_SERVER['REQUEST_METHOD'] === 'POST') {
        if ($name === '') $errors['name'] = 'Please enter your name.';
        if (!filter_var($email, FILTER_VALIDATE_EMAIL)) $errors['email'] = 'Please enter a valid email.';
        if (mb_strlen($message) < 10) $errors['message'] = 'Please write at least 10 characters.';

        if (!$errors) {
            // Mailer::getInstance()->send($email, $name, $message);   (a backend/ class)
            header('Location: /contact?sent=1', true, 303);
            exit;
        }
    }
</script>

<header>
    <title>Contact</title>
    <meta name="description" content="Send us a message.">
</header>

<template>
    <h1>Contact</h1>
    <p p-if="$bSent" role="status">Thanks, your message was sent.</p>

    <form method="post" action="/contact" novalidate>
        <label for="name">Name</label>
        <input id="name" name="name" value="{{ $name }}" aria-invalid="{{ isset($errors['name']) ? 'true' : 'false' }}">
        <p p-if="isset($errors['name'])" class="error">{{ $errors['name'] ?? '' }}</p>

        <label for="email">Email</label>
        <input id="email" name="email" type="email" value="{{ $email }}">
        <p p-if="isset($errors['email'])" class="error">{{ $errors['email'] ?? '' }}</p>

        <label for="message">Message</label>
        <textarea id="message" name="message">{{ $message }}</textarea>
        <p p-if="isset($errors['message'])" class="error">{{ $errors['message'] ?? '' }}</p>

        <button type="submit">Send</button>
    </form>
</template>
```

## 2. Like button with @AJAX (no reload)

```html
<!-- views/post.pvue -->
<script>
    @AJAX('POST')
    function likePost($input) {
        header('Content-Type: application/json');
        $id = (int) ($input['id'] ?? 0);
        if ($id < 1) {
            http_response_code(422);
            echo json_encode(['ok' => false]);
            return;
        }
        $_SESSION['likes'][$id] = ($_SESSION['likes'][$id] ?? 0) + 1;
        echo json_encode(['ok' => true, 'likes' => $_SESSION['likes'][$id]]);
    }

    $postId = 1;
    $likes = $_SESSION['likes'][$postId] ?? 0;
</script>

<template>
    <article>
        <h1>Hello PHPue</h1>
        <button type="button" onclick="likePost({{ $postId }}, this)">
            Like (<span class="like-count">{{ $likes }}</span>)
        </button>
    </article>
</template>

<cscript>
    async function likePost(id, button) {
        button.disabled = true;
        try {
            const res = await fetch('', {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify({ action: 'likePost', id })
            });
            const data = await res.json();
            if (data.ok) button.querySelector('.like-count').textContent = data.likes;
        } finally {
            button.disabled = false;
        }
    }
</cscript>
```

## 3. Search and filter a list with GET parameters

Shareable URLs, works without JavaScript, and crawlers see the results.

```html
<!-- views/tools.pvue -->
<script>
    $allTools = [
        ['name' => 'PHPue', 'type' => 'framework'],
        ['name' => 'AlpineJS', 'type' => 'library'],
        ['name' => 'HTMX', 'type' => 'library'],
        ['name' => 'Tailwind CSS', 'type' => 'css'],
    ];
    $types = array_values(array_unique(array_column($allTools, 'type')));
    $q = trim((string) ($_GET['q'] ?? ''));
    $type = in_array($_GET['type'] ?? '', $types, true) ? $_GET['type'] : '';

    $tools = array_filter($allTools, fn($t) =>
        ($q === '' || stripos($t['name'], $q) !== false) && ($type === '' || $t['type'] === $type));
</script>

<template>
    <form method="get" action="/tools" role="search">
        <input name="q" value="{{ $q }}" placeholder="Search tools">
        <select name="type">
            <option value="">All types</option>
            <option p-for="$t in $types" value="{{ $t }}" <?= $t === $type ? 'selected' : '' ?>>{{ ucfirst($t) }}</option>
        </select>
        <button type="submit">Filter</button>
    </form>

    <p>{{ count($tools) }} result(s)</p>
    <ul>
        <li p-for="$tool in $tools">{{ $tool['name'] }} <small>({{ $tool['type'] }})</small></li>
    </ul>
    <p p-if="count($tools) === 0">Nothing matches. <a href="/tools">Clear filters</a></p>
</template>
```

Boolean attributes (`selected`, `checked`, `disabled`) count as set whenever they are present, even as `selected=""`, so add or omit the whole attribute with `<?= ... ?>` instead of filling its value with `{{ }}`.

## 4. Card grid: a component in a loop with defaults

```html
<!-- views/team.pvue -->
<script>
    @require PersonCard 'components/PersonCard.pvue';
    $people = [
        ['name' => 'Ada', 'role' => 'Engineer'],
        ['name' => 'Grace', 'role' => 'Admiral'],
    ];
</script>

<template>
    <section class="grid">
        <PersonCard p-for="$person in $people" />
    </section>
</template>
```

```html
<!-- components/PersonCard.pvue -->
<script>
    $person = $person ?? ['name' => 'Unknown', 'role' => ''];
    $personInitial = mb_substr($person['name'], 0, 1);
</script>

<template>
    <article class="card">
        <span class="avatar" aria-hidden="true">{{ $personInitial }}</span>
        <h2>{{ $person['name'] }}</h2>
        <p p-if="$person['role'] !== ''">{{ $person['role'] }}</p>
    </article>
</template>
```

## 5. Database page with a backend singleton (SQLite via PDO)

Needs PHP's `pdo_sqlite` extension (included in the official `php` Docker images). Swap the DSN for MySQL or PostgreSQL in production.

```php
<?php
// backend/Notes.php
class Notes {
    private static ?self $instance = null;
    private PDO $pdo;

    public static function getInstance(): self {
        return self::$instance ??= new self();
    }

    private function __construct() {
        $dir = getcwd() . '/data';
        if (!is_dir($dir)) mkdir($dir, 0775, true);
        $this->pdo = new PDO('sqlite:' . $dir . '/notes.sqlite', null, null, [
            PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
            PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
        ]);
        $this->pdo->exec('CREATE TABLE IF NOT EXISTS notes (id INTEGER PRIMARY KEY, body TEXT NOT NULL, created TEXT NOT NULL)');
    }

    public function latest(int $limit = 20): array {
        $stmt = $this->pdo->prepare('SELECT * FROM notes ORDER BY id DESC LIMIT :limit');
        $stmt->bindValue(':limit', $limit, PDO::PARAM_INT);
        $stmt->execute();
        return $stmt->fetchAll();
    }

    public function add(string $body): void {
        $stmt = $this->pdo->prepare('INSERT INTO notes (body, created) VALUES (:body, :created)');
        $stmt->execute([':body' => $body, ':created' => date('c')]);
    }
}
```

```html
<!-- views/notes.pvue -->
<script>
    @AJAX('POST')
    function addNote($input) {
        header('Content-Type: application/json');
        $body = trim((string) ($input['body'] ?? ''));
        if ($body === '' || mb_strlen($body) > 280) {
            http_response_code(422);
            echo json_encode(['ok' => false, 'error' => 'Write 1-280 characters.']);
            return;
        }
        Notes::getInstance()->add($body);
        echo json_encode(['ok' => true]);
    }

    $notes = Notes::getInstance()->latest();
</script>

<template>
    <form onsubmit="addNote(event)">
        <input name="body" maxlength="280" required>
        <button type="submit">Add note</button>
    </form>
    <ul>
        <li p-for="$note in $notes"><time>{{ substr($note['created'], 0, 10) }}</time> {{ $note['body'] }}</li>
    </ul>
</template>

<cscript>
    async function addNote(event) {
        event.preventDefault();
        const body = new FormData(event.target).get('body');
        const res = await fetch('', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ action: 'addNote', body })
        });
        if (res.ok) location.reload();          // the server renders the new list
        else alert((await res.json()).error);
    }
</cscript>
```

Keep the `data/` folder outside the web root, or block it in `.htaccess`/nginx.

## 6. Dynamic page titles from App.pvue (sessionless)

Views have static headers, so compute per-request meta in a backend class and print it from the App header.

```php
<?php
// backend/PageMeta.php
class PageMeta {
    public static function tags(): string {
        $route = get_current_route();
        $title = match ($route) {
            'index' => 'Home | My Site',
            'blog'  => isset($_GET['post'])
                ? ucwords(str_replace('-', ' ', preg_replace('/[^a-z0-9-]/', '', $_GET['post']))) . ' | Blog'
                : 'Blog | My Site',
            default => ucfirst($route) . ' | My Site',
        };
        $e = fn($v) => htmlspecialchars($v, ENT_QUOTES);
        return '<title>' . $e($title) . '</title>'
             . '<link rel="canonical" href="https://example.com' . $e(strtok($_SERVER['REQUEST_URI'], '#')) . '">';
    }
}
```

```html
<!-- App.pvue -->
<script>
    #require 'views/index.pvue';
    #require 'views/blog.pvue';
    $headTags = PageMeta::tags();
</script>

<header>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    {{ $headTags }}
</header>

<template>
    <View/>
</template>
```

Leave `<title>` out of the view headers when the App prints it.

## 7. Login gate with sessions

```html
<!-- views/admin.pvue -->
<script>
    @AJAX('POST')
    function adminLogin($input) {
        header('Content-Type: application/json');
        $hash = getenv('ADMIN_PASSWORD_HASH') ?: '';   // password_hash() output, kept out of git
        if ($hash !== '' && password_verify((string) ($input['password'] ?? ''), $hash)) {
            session_regenerate_id(true);
            $_SESSION['isAdmin'] = true;
            echo json_encode(['ok' => true]);
            return;
        }
        http_response_code(401);
        echo json_encode(['ok' => false]);
    }

    @AJAX('POST')
    function adminLogout($input) {
        $_SESSION = [];
        echo json_encode(['ok' => true]);
    }

    $bAdmin = !empty($_SESSION['isAdmin']);
</script>

<header>
    <meta name="robots" content="noindex">
</header>

<template>
    <form p-if="!$bAdmin" onsubmit="adminAction(event, 'adminLogin')">
        <input name="password" type="password" autocomplete="current-password" required>
        <button type="submit">Sign in</button>
    </form>

    <section p-if="$bAdmin">
        <h1>Admin</h1>
        <button type="button" onclick="adminAction(event, 'adminLogout')">Sign out</button>
    </section>
</template>

<cscript>
    async function adminAction(event, action) {
        event.preventDefault();
        const fields = event.target.tagName === 'FORM' ? Object.fromEntries(new FormData(event.target)) : {};
        const res = await fetch('', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ action, ...fields })
        });
        if (res.ok) location.reload(); else alert('Wrong password');
    }
</cscript>
```


---

<!-- Source: https://ai.phpue.co.uk/docs?topic=gotchas | Markdown: https://ai.phpue.co.uk/knowledge/gotchas.md -->

# Common mistakes and verified fixes

> Each row was compiled with PHPue 0.0.3's `convert_pvue_file()`. Many of these do not throw an error: the page silently renders the wrong thing. When something looks wrong, read the compiled PHP (`?compile=views/page.pvue` in dev, or `convert_pvue_file()` from the CLI).

## Template output

| You write | What happens | Fix |
|---|---|---|
| `{{ $user.name }}` | PHP concatenation: wrong output and warnings | `{{ $user['name'] }}` or `{{ $user->name }}` |
| `{{ $tags }}` (array) | `htmlspecialchars()` TypeError | `{{ implode(', ', $tags) }}` |
| `{{ !$x }}`, `{{ (int)$x }}`, `{{ 'text' }}` | printed literally | `{{ $x ? '' : 'no' }}`, `{{ intval($x) }}`, `<?= ... ?>` |
| `{{ total() }}` meant for Alpine | compiled as a PHP call: `Call to undefined function total()` | `x-text="total()"` |
| `class="x" {{ $on ? 'aria-current="page"' : '' }}` | quotes escaped: `aria-current=&quot;page&quot;` | `aria-current="{{ $on ? 'page' : 'false' }}"` or `<?= ... ?>` |
| `p-else`, `p-show`, `p-model` | not directives; left as dead attributes | negated `p-if`, raw PHP, `value="{{ $x }}"` |
| `p-if` element without its closing tag | only the opening tag is wrapped; content always renders | close the element |
| `p-for="item of $items"` | not converted (`data-phpue-invalid-p-for`) | `p-for="$item in $items"` |
| Literal `{{ $x }}` in documentation text | gets compiled | `&#123;&#123; $x &#125;&#125;` |

## Blocks and files

| You write | What happens | Fix |
|---|---|---|
| A closing script tag inside a PHP string or comment in `<script>` | the PHP block ends there; the rest is dropped or a parse error | `'</scr' . 'ipt>'` |
| `const s = '<template>'` in an inline `<script>` inside the template | counted as a nested template; the template swallows the rest of the file | `'<tem' + 'plate>'`, or move the JS to `<cscript>` |
| JavaScript in `<script>` (Vue habit) | PHP parse error: `<script>` is PHP | browser JS goes in `<cscript>` |
| `<html>`, `<head>`, `<body>` in a `.pvue` | duplicated document structure | PHPue prints them; use `<header>` for head tags |
| Editing `.pvue` while `.dist/` exists | no effect; the compiled copy is served | delete `.dist/` or rebuild |

## Components

| You write | What happens | Fix |
|---|---|---|
| `<Card title="x"/>`, `<Card>slot</Card>` | not replaced: the raw tag is printed, nothing renders | set `$cardTitle` before `<Card/>`; components inherit scope |
| `function helper() {}` in a component used twice or in a loop | `Cannot redeclare helper()` | move to `backend/` or use a closure |
| `const x = ...` at the top level of a reused component's `<cscript>` | JS `Identifier 'x' has already been declared` | IIFE, `var`, or move to the view/App cscript |
| `<Card/>` without `@require` | renders nothing useful | `@require Card 'components/Card.pvue';` |
| Component uses `$title`, parent also uses `$title` | the component overwrites the parent's variable | specific names (`$cardTitle`) |

## Routing, scope and headers

| You write | What happens | Fix |
|---|---|---|
| `#require Home 'views/index.pvue';` | ignored (PHP `#` comment) | `#require 'views/index.pvue';` |
| `views/blog/post.pvue`, URL `/blog/post` | 404 | flat views + query strings |
| `?page=2` for pagination | overwritten by the route slug | `?p=2` |
| App variable used in a view | undefined | backend singleton, `$_SESSION`, `define()` |
| `<title>{{ $postTitle }}</title>` in a view header | prints the literal text `$postTitle` | dynamic meta from the App header (MetaControl) |
| `{{ count($x) }}` or `{{ $a ?? '' }}` in the App header | not converted | build the string in the App script, print `{{ $titleTag }}` |
| `<?= $x ?>` in the App header | printed literally (it is a heredoc) | `{{ $x }}` |
| Inline `<script>$(function(){...})</script>` in the App header | `$` interpolated by the heredoc | move JS to a file or `<cscript>` |
| `phpue_set_lang('cy')` in a view | too late, `<html lang>` already printed | App script or `backend/` |
| `__DIR__ . '/data/x.json'` in a view | breaks after `php index.php build` | `getcwd() . '/data/x.json'` |
| Variables named `$routing`, `$current_route`, `$b404`, `$input`, `$action` | reset by the compiled preamble | other names |

## AJAX

| You write | What happens | Fix |
|---|---|---|
| `return ['ok' => true];` in a handler | empty response | `echo json_encode(['ok' => true]);` |
| `fetch('', {method: 'POST', body: formData})` | no action found: the full HTML page comes back (200) | send JSON, or a backend endpoint for uploads |
| Handler uses a variable set in the view script | undefined (handlers run first) | recompute in the handler or use a singleton |
| `@AJAX('POST')` called with GET (or the reverse) | 405 | match the method |
| Client calls a plain (non-`@AJAX`) function by `action` | falls through to the HTML page | mark it `@AJAX('POST')` |
| Two handlers with the same name in different views | fatal redeclare | unique names app-wide |

## cscript

| You write | What happens | Fix |
|---|---|---|
| `const name = "{{ $name }}";` | `""Ada""`: JS syntax error | `const name = {{ $name }};` |
| `const n = {{ count($items) }};` | not converted: broken JS | `const n = <?= json_encode(count($items)) ?>;` |

## Sessions and caching

| You write | What happens | Fix |
|---|---|---|
| Writing `$_SESSION` in a view with `PHPUE_SESSION = 'lazy'` | lost for first-time visitors (no session yet) | `phpue_session(true)` before the write |
| `session_start()` anywhere in the App script text (even a comment) | PHPue's session handling switches off | remove it; use `phpue_session()` |
| Expecting nginx/CDN caching with default settings | every response sets a cookie and `no-store` | `PHPUE_SESSION = 'lazy'` |
| A backend file that `return`s an array, loaded with `require_once` | second load returns `true`, not the array | folder with `autoload.php`, or `require` |


---

<!-- Source: https://ai.phpue.co.uk/docs?topic=upgrade | Markdown: https://ai.phpue.co.uk/knowledge/upgrade.md -->

# Upgrading from 0.0.2 to 0.0.3

> PHPue 0.0.3 is a bug-fix release. It replaces 0.0.2's line-based regular expressions with a block parser and tag-aware `p-if`/`p-for` conversion, so most 0.0.2 markup traps are gone. To upgrade, replace **both** `index.php` and `conversion.php` (they are one release), make sure the server runs PHP 8.0+, then check the behaviour changes below. Your `.pvue` files usually need no edits.

## How to upgrade

1. Check the current version: `grep -m1 PHPUE_VERSION www/index.php`.
2. Copy `index.php` and `conversion.php` from the 0.0.3 release of [PHPue](https://github.com/PHPue/PHPue) into `www/`. Re-apply any constants you changed (`PHPUE_LANG`).
3. Choose sessions: keep `PHPUE_SESSION = 'auto'` (0.0.2 behaviour) or switch to `'lazy'` for cacheable public pages, then add `phpue_session(true)` before session writes during page rendering.
4. Delete the old `.dist/` and rebuild: `php index.php build`.
5. Test every `@AJAX` call (see "Behaviour changes").

## Behaviour changes to check

| Area | 0.0.2 | 0.0.3 |
|---|---|---|
| AJAX dispatch | any existing PHP function named in `action` was callable (built-ins too); method not enforced | only `@AJAX` functions; wrong method gets 405 |
| AJAX in components | dropped from the build | built into `.dist/ajax/ajax-component-<Name>.php` |
| AJAX for views not `#require`d | missing in production | every view's handlers are built |
| Sessions | always started | `PHPUE_SESSION`: `'auto'` (default) or `'lazy'`, plus `phpue_session()` |
| `<html lang>` in `.dist` | frozen at build time | resolved per request; `phpue_set_lang()` added |
| Dev tools | `?compile=` and `?build` worked in every mode | only in source mode unless `PHPUE_DEV_TOOLS` is defined |
| Hot reload | watched one folder level | recursive |
| Build without `components/` | crashed | works |
| backend/ load order | filesystem order | sorted path order |
| PHP version | 7.4+ | 8.0+ |

If a client calls a plain function through `action`, it worked on 0.0.2 and returns the HTML page on 0.0.3: mark it `@AJAX('POST')` (or `'GET'`).

## What now works (no workaround needed on 0.0.3)

- `<p p-if="$x" class="a">Text {{ $y }}</p>` on one line, multi-line opening tags, `{{ }}` and `>` in other attributes of a `p-if` element, nested same-tag children, `p-if` on void elements.
- `p-for` over function calls (`range(1, 5)`), `PDOStatement`s and generators; nested same-tag children; `p-for` + `p-if` on one element.
- `{{ count($x) }}` and other function calls in `{{ }}`.
- `{{ $data['items'] }}` in `<cscript>`; `{{ $meta['title'] }}` and `{{ $obj->prop }}` in the App header.
- Nested `<template>` elements (Alpine `<template x-for>`).
- `<Card />` with a space, `@require` with double quotes, `p-if`/`p-for` on component tags.
- `@AJAX("POST")`, typed parameters, defaults with parentheses, return types.
- Block tag names inside comments and strings no longer hijack blocks; a bare `<header>` element in a template is kept; a bare `<script>` in a template is fine.

## Maintaining a 0.0.2 project (rules that still apply there)

If you cannot upgrade yet, follow these on 0.0.2 only:

- `p-if`: opening tag on **one line**, nothing after its `>` on that line, children on the next lines, closing tag on its own line. No `>` and no `{{ }}`/`<?= ?>` in that element's attributes. No one-line child of the same tag (`<div>x</div>` inside `<div p-if>`). No `p-if` on void elements.
- `p-for`: the source must be a variable or index (it is wrapped in `isset()`; a call is fatal and objects are skipped); the loop ends at the **first** closing tag of the same name, so never nest that tag; never combine `p-for` and `p-if` on one element.
- `{{ }}` only converts `$...` expressions: use `<?= count($x) ?>` for calls. In `<cscript>`, only simple variables convert: `<?= json_encode($a['b']) ?>`.
- Never use a nested `<template>` anywhere (the template block ends at the first `</template>`).
- Components: `@require` with single quotes only; `<Card/>` or `<Card></Card>` (no space).
- `@AJAX('POST')` with single quotes, `function name($input) {` with no return type and no `)` in defaults. Put handlers in views or App (not components), and `#require` every view.
- Never write a literal `<header>`, `<template>`, `<cscript>`, closing script tag or `<title>` in any comment or string. Give template `<header>` elements an attribute (`<header class="top">`).
- Keep a `components/` folder (the build crashes without it).
- Lazy sessions by hand: mention `session_start()` in the App script (which disables auto-start) and start the session only when the visitor already has a cookie.


---

<!-- Source: https://ai.phpue.co.uk/docs?topic=migration | Markdown: https://ai.phpue.co.uk/knowledge/migration.md -->

# Coming from React, Next.js, Vue, Blade or plain PHP

> PHPue keeps the parts of modern frameworks people like (single-file components, file-based routing, a tidy template syntax) and drops the parts that cost the most (Node.js toolchains, hydration, client state management). State lives on the server in PHP; the browser gets finished HTML. Use this page to translate concepts, not code line by line.

## Concept map

| Concept | React / Next.js | Vue / Nuxt | Laravel Blade | PHPue |
|---|---|---|---|---|
| Component file | `.jsx` / `.tsx` | `.vue` | `.blade.php` | `.pvue` (PHP + HTML + optional JS) |
| Server logic | `getServerSideProps`, server components | `asyncData`, server routes | controller | the `.pvue` `<script>` block (PHP) |
| Output | `{user.name}` | `{{ user.name }}` | `{{ $user->name }}` | `{{ $user['name'] }}` / `{{ $user->name }}` |
| Condition | `{cond && <p/>}` | `v-if` / `v-else` | `@if` / `@else` | `p-if` (+ negated `p-if` or `<?php else: ?>`) |
| Loop | `items.map(...)` | `v-for` | `@foreach` | `p-for="$item in $items"` |
| Child component | `<Card title="x"/>` | `<Card :title="x"/>` | `<x-card :title="$x"/>` | `<?php $cardTitle = 'x'; ?><Card/>` (inherited scope) |
| Slots / children | `props.children` | `<slot>` | `{{ $slot }}` | none: set variables, or split into components |
| Routing | `pages/` or `app/` folders, nested | `pages/`, nested | `routes/web.php` | `views/*.pvue`, flat; query strings for detail pages |
| Layout | `_app.tsx` / `layout.tsx` | `layouts/` | `@extends` | `App.pvue` with `<View/>` |
| Head / meta | `next/head`, `metadata` | `useHead` | `@section('title')` | view `<header>` (static) or App header (dynamic) |
| Client state | `useState`, Redux | `ref`, Pinia | Livewire, Alpine | PHP + `$_SESSION`; Alpine when you need it |
| Effects / fetching | `useEffect`, SWR | `onMounted`, `useFetch` | controller | fetch in PHP before rendering |
| API routes | `pages/api/*` | `server/api/*` | `routes/api.php` | `@AJAX('POST')` functions, or a `backend/` endpoint |
| Forms | controlled inputs | `v-model` | `old()`, `@csrf` | plain `name`/`value`, explicit POST or `@AJAX` |
| Build | webpack / Vite / Turbopack | Vite | Vite (assets) | none; optional `php index.php build` |
| Hosting | Node server, Vercel | Node server | PHP host | any PHP 8 host, shared hosting included |

## From React / Next.js

- Convert each page to `views/<route>.pvue`. `getServerSideProps` and `useEffect` data fetching become plain PHP in `<script>`.
- `useState` for UI-only state: keep it in the browser with a few lines of `<cscript>` or AlpineJS. For state that must survive reloads, store it in `$_SESSION` or the database through `@AJAX`.
- Props become variables set before `<Component/>`. Children/slots become separate components.
- Nested routes (`/blog/[slug]`) become `/blog?post=slug`.

```jsx
// React
export default function UserList({ users }) {
    return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
}
```

```html
<!-- PHPue: views/users.pvue -->
<script>
    $users = Database::getInstance()->users();
</script>

<template>
    <ul>
        <li p-for="$user in $users">{{ $user['name'] }}</li>
    </ul>
</template>
```

## From Vue / Nuxt

The syntax is deliberately familiar, but: `{{ }}` takes **PHP** expressions (`$user['name']`, not `user.name`); there is no reactivity (the template runs once on the server); no `v-else`, `v-show`, `v-model`, `:props` or `@emit`; `<script>` is PHP. Put interactive islands in AlpineJS, which feels close to Vue's Options API.

## From Laravel Blade

`@if`/`@foreach` become `p-if`/`p-for` (or the raw PHP equivalents you already know); `{!! $html !!}` becomes `<?= $html ?>`; `@include` becomes `<Component/>` with inherited variables; controllers collapse into the view's `<script>`; Eloquent can be replaced by PDO singletons in `backend/` (or a Composer package vendored inside `backend/`). Add your own CSRF token check for `@AJAX` writes.

## From plain PHP

You already know PHPue: it is your PHP with a component system. Move `include 'header.php'` into `App.pvue`, turn each page into a view, wrap repeated markup into components, and keep using `<?php ?>` wherever it is clearer.

## When PHPue fits (and when it does not)

Good fit:

- Content sites, docs, marketing sites, blogs, dashboards, admin panels, small SaaS and internal tools.
- Teams that know PHP, or anyone tired of JavaScript build tooling.
- Cheap or shared hosting; projects that must keep running for years without dependency churn.
- SEO- and GEO-sensitive sites: complete HTML on first response, no hydration.

Less suitable:

- Heavily real-time apps (use WebSockets alongside), offline-first apps, or UIs that are almost entirely client-side state (an editor or a game).
- Projects that need a large ecosystem of ready-made framework plugins: PHPue is young and its community is small.


---

<!-- Source: https://ai.phpue.co.uk/faq | Markdown: https://ai.phpue.co.uk/knowledge/faq.md -->

# PHPue FAQ

> Short, direct answers about PHPue 0.0.3. Each answer links to the full topic.

## What is PHPue?

PHPue is a server-side PHP framework that compiles Vue-like single-file components (`.pvue` files) into plain PHP. A `.pvue` file has a `<script>` block (PHP), a `<header>` block (head tags), a `<template>` block (HTML with `{{ }}`, `p-if` and `p-for`) and a `<cscript>` block (browser JavaScript). It needs no Node.js, bundler or build step. See [What PHPue is](/).

## Who created PHPue?

PHPue was created by Edward Patch. It is open source under the Apache 2.0 licence at [github.com/PHPue/PHPue](https://github.com/PHPue/PHPue), with the official site at [phpue.co.uk](https://phpue.co.uk).

## What is the latest version of PHPue?

The current release is PHPue 0.0.3, a bug-fix release that replaced 0.0.2's line-based regular expressions with a block parser and tag-aware directives, enforced `@AJAX` methods and added lazy sessions. See [Upgrading from 0.0.2](/docs?topic=upgrade).

## What do I need to run PHPue?

PHP 8.0 or newer and a web server that sends unknown URLs to `index.php` (PHP's built-in server, Apache with the included `.htaccess`, nginx with `try_files`, Docker, XAMPP or shared hosting). No Node.js, npm or Composer is required. See [Quick start](/docs?topic=quickstart).

## Is PHPue the same as Vue?

No. PHPue borrows Vue's single-file layout and directive style, but everything runs once on the server. There is no virtual DOM, reactivity, hydration, props, slots, emits or `v-model`. The `<script>` block is PHP. Client interactivity comes from plain JavaScript in `<cscript>`, `@AJAX` calls, or optionally AlpineJS. See [Migration](/docs?topic=migration).

## How do I print a variable in a PHPue template?

Use `{{ $variable }}`, which is HTML-escaped. Use array or object syntax for nested values, `{{ $user['name'] }}` or `{{ $user->name }}`, never `{{ $user.name }}` (the dot is PHP string concatenation). For trusted raw HTML use `<?= $html ?>`. See [Templates](/docs?topic=templates).

## Does PHPue have p-else or p-show?

No. PHPue's directives are `p-if` and `p-for`. For an else branch, add a second element with the negated condition (`p-if="!$loggedIn"`) or use raw PHP: `<?php if (...): ?> ... <?php else: ?> ... <?php endif; ?>`. There is no `p-model` either; forms use plain `name` and `value` attributes.

## How do I pass props to a PHPue component?

You don't need to: components are inlined at compile time and inherit every variable of the parent, like a PHP `include`. Set a variable before the tag (`<?php $cardTitle = 'Hello'; ?><Card/>`), or place the component inside a `p-for` loop and read the loop variable. Default inherited variables in the component (`$cardTitle = $cardTitle ?? '';`). See [Components](/docs?topic=components).

## How does routing work in PHPue?

Each file in `views/` is a route named after the file: `views/about.pvue` is `/about` and `views/index.pvue` is `/`. Routes are flat, so use query strings for detail pages (`/blog?post=my-post`). Register views in `App.pvue` with `#require 'views/about.pvue';`. See [Routing](/docs?topic=routing).

## How do I call PHP from JavaScript in PHPue?

Mark a PHP function with `@AJAX('POST')` (or `@AJAX('GET')`) in a `<script>` block, and call it with `fetch('', {method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({action: 'functionName', ...data})})`. The function receives `$input` and must `echo` its response, usually `json_encode(...)`. See [@AJAX](/docs?topic=ajax).

## How do I handle forms in PHPue?

Either submit a normal `<form method="post">` and handle `$_POST` in the view's `<script>`, or send the form as JSON to an `@AJAX` function. PHPue deliberately has no two-way binding: forms are submitted on purpose. File uploads go to a `backend/` endpoint because `@AJAX` only reads JSON. See [Recipes](/docs?topic=recipes).

## Can I use a database with PHPue?

Yes. Write a PDO (or any library) class in `backend/`, which PHPue loads on every request, and call it from views and `@AJAX` handlers, typically as a singleton: `Database::getInstance()->latestPosts()`. Always use prepared statements. See [backend/](/docs?topic=backend).

## Why can't my view see a variable from App.pvue?

App, each view and `@AJAX` handlers run in separate scopes. Share data through a `backend/` singleton, `define()`, `$_SESSION` or `$GLOBALS`. See [backend/, scope, sessions and language](/docs?topic=backend).

## Why don't my .pvue changes show up?

A `.dist/` folder exists, so PHPue serves the compiled copy. Delete `.dist/` while developing, or rebuild with `php index.php build`. Also check for a stray `App.php` in the web root.

## How do I deploy a PHPue app?

Run `php index.php build` in `www/`, then upload `.dist/`, `assets/`, `httpReqs/`, `index.php`, `conversion.php` and `.htaccess` to any PHP 8 host. `index.php` serves the precompiled pages. See [Build and deploy](/docs?topic=build-deploy).

## Can I use Tailwind CSS, AlpineJS or HTMX with PHPue?

Yes. Tailwind works through its CLI (scan `./**/*.pvue` and `./**/*.php`) or the CDN. AlpineJS works in templates as-is, and the official x-ssr extension lets Alpine update server-rendered lists. HTMX works for boosted navigation and partial updates; `@AJAX` POST needs a JSON-encoding extension. See [client JS](/docs?topic=client-js).

## Is PHPue good for SEO?

Yes. Pages are fully rendered HTML on the first response with no hydration. Use static `<title>` and meta in view headers, or dynamic meta from `App.pvue` (the MetaControl extension), and set `PHPUE_SESSION` to `'lazy'` so anonymous pages are cacheable. See [Official extensions](/docs?topic=extensions).

## Is PHPue production ready?

PHPue is young (0.0.x) and its community is small, but it is plain PHP underneath: when a directive does not fit, you write normal PHP, and compiled output is ordinary PHP files. It suits content sites, dashboards, admin panels and small apps. Pin the framework files per project and test after upgrading.

## How can AI assistants write correct PHPue code?

Point them at [https://ai.phpue.co.uk/llms-full.txt](/llms-full.txt) (everything in one file) or [/llms.txt](/llms.txt) (an index of markdown topics), and add the AGENTS.md from [Rules for AI coding agents](/docs?topic=ai-rules) to your project. Ask the agent to compile changed files with `convert_pvue_file()` and check them with `php -l`.