PHP Security Advisory: make sure your server runs the 21 October 2026 PHP security release. Read our guidance →
π Documentation · v0.0.3
PHPue is a PHP framework that brings the simplicity of Vue's component model to server-side rendering. Build modern web applications without the complexity of build tools or client-side hydration.
A PHP framework that uses Vue-like syntax for server-side rendering. Write components with familiar directives, but get pure HTML from the server. Zero JavaScript required for core functionality.
{{ }}, p-if and p-for runs once, on the server.
<?php if β¦ ?> and move on.
<cscript>, or AlpineJS.
0.0.3 is a bug-fix release for the compiler. Most 0.0.2 workarounds are no longer needed, and existing apps keep working:
replace index.php and conversion.php together.
Sections below marked 0.0.3 are new or changed.
p-if / p-for work on one line, across lines, on nested tags and togethercount($items) now workx-for / x-if templates compilePHPUE_SESSION = 'lazy' keeps public pages cacheablephpue_set_lang() sets <html lang> per request?build, ?compile= and ?hot-reload switch off in production
Swap in the new index.php and conversion.php, check you're on PHP 8.2+, then rebuild (php index.php build).
Any @AJAX call that used the wrong HTTP method now gets a 405, so test your forms. Full notes: release page.
Learn PHPue through step-by-step tutorials designed for developers of all skill levels. Our tutorials cover everything from basic setup to advanced features.
PHPue includes a complete tutorial system built with PHPue itself. Each tutorial provides hands-on examples and real-world scenarios.
All tutorials are built with PHPue and demonstrate real-world usage patterns.
Start building with PHPue in minutes. No complex setup, no build process, just pure PHP power.
# Clone the starter template
git clone https://github.com/PHPue/PHPue my-app
cd my-app
# Start the development server (recommended: Docker, PHP + NGINX)
docker compose up
# Open http://localhost:3000
# No Docker? PHP's built-in server works too
cd www && php -S localhost:3000
docker compose up gives you NGINX + PHP-FPM on port 3000. Hot reload and AJAX work together, just like production.
cd www && php -S localhost:3000 (any free port, e.g. 8080). Great for a first look, but it handles one request at a time, so hot reload (?live) can block your AJAX calls.
www/ into htdocs/. The included .htaccess routes every page through index.php.
views/index.pvue and start building.
PHPue Framework requires PHP 8.2+ and works with any web server. No additional extensions, Composer or npm needed.
index.php and conversion.php into your web root.index.php file PHPue follows a convention-based structure that makes organising your application intuitive and scalable.
about.pvue, docs.pvue). The file name is the route: about.pvue β /about
Navbar.pvue, Sidebar.pvue), in any folder depth
views/ (no nested paths). Use query strings for parameters: /post?id=42
PHPue offers two deployment strategies - choose the one that fits your workflow and security requirements.
Recommended for production - Compile locally and deploy only the optimised files.
For development or when you need instant builds on the server.
If you choose Option 2, you MUST add these security rules to prevent source code exposure.
# BLOCK access to all .pvue files (anywhere)
<FilesMatch "\.pvue$">
Require all denied
</FilesMatch>
# BLOCK access to source directories
RewriteRule ^(views|components|backend|httpReqs)(/.*)?$ - [F,L]
β Blocks all .pvue files and protects source directories
# BLOCK .pvue files
location ~ \.pvue$ {
deny all;
return 404;
}
# BLOCK source directories
location ~ /(views|components|backend|httpReqs)/ {
deny all;
return 404;
}
β Equivalent protection for NGINX servers
PHPue automatically switches off its developer tools once your app is compiled, so nobody can rebuild or inspect your live site from a browser.
This prevents accidental rebuilds that could break your live site. For intentional rebuilds, use the CLI command.
Need the tools on a compiled site (e.g. staging)? Add define('PHPUE_DEV_TOOLS', true); to index.php, never in production.
Build your app with docker compose up (or php -S localhost:3000)
Run php index.php build (or ?build=1) to compile to .dist/
Upload only .dist/, assets/, httpReqs/, index.php, and conversion.php
π‘ Pro Tip: Always build locally and deploy the compiled .dist/ directory for maximum security and performance. For zero-downtime switches and instant rollbacks, see Painless Deployment.
Import components and views using simple require statements.
@require ComponentName 'components/componentName.pvue';Import a component for use in your template, then write <ComponentName/>, <ComponentName /> or <ComponentName></ComponentName>. Single or double quotes both work. 0.0.3
#require 'views/viewName.pvue';Include a view template with its own logic. Register every view in App.pvue.
Here's how you might structure your main application file:
<script>
@require Navbar 'components/Navbar.pvue';
#require 'views/index.pvue';
#require 'views/about.pvue';
</script>
<header>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" href="assets/css/styles.css">
<script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>
<script src="assets/js/jquery-3.7.1.min.js"></script>
</header>
<template>
<Navbar></Navbar>
<View></View>
</template>Key Points:
backend/ classes, $_SESSION or define()
Components are inlined into their parent, so they see every variable the parent has - just like a PHP include.
Set a variable before the tag, and give it a default inside the component.
<!-- views/index.pvue -->
<?php $cardTitle = 'Pricing'; ?>
<Card/>
<!-- 0.0.3: render a component once per item -->
<ProductCard p-for="$product in $products" />
<!-- components/Card.pvue -->
<script>
$cardTitle = $cardTitle ?? 'Untitled';
</script>
π‘ Tip: Don't declare named PHP functions or classes inside a component (using it twice declares them twice). Put them in backend/.
App.pvue is the shell for every page. <View/> (only allowed in App) is replaced by the current route's view.
views/index.pvue β /views/ue-insights.pvue β /ue-insights?id=42phpue_navigation() returns every route with its title, handy for menus#require so production builds include its @AJAX handlers$_GET['page'] is reserved for the route: paginate with ?p=backend/, $_SESSION, define() or $GLOBALS
A view's <header> is static HTML: PHP and {{ }} are not evaluated there.
App.pvue's header is a PHP heredoc, so it can print variables, including array values in 0.0.3.0.0.3
<script>
$meta = ['title' => '<title>' . htmlspecialchars($pageTitle) . '</title>'];
</script>
<header>
{{ $meta['title'] }} <!-- printed raw: escape when you build it -->
</header>π‘ Per-page titles and social tags? Use the official MetaControl extension with a small meta router, as this site does.
PHPue components are structured using familiar blocks for different concerns.
<script>
// PHP logic here
$title = "Hello World";
$users = $db->query("SELECT * FROM users")->fetchAll();
</script>
<header>
<title>Hello World | My PHPue App</title>
<meta name="description" content="My PHPue app">
</header>
<template>
<!-- Your HTML template -->
<h1>{{ $title }}</h1>
<div p-for="$user in $users">
{{ $user['name'] }}
</div>
</template>
<cscript>
// Client-side JavaScript (optional)
console.log('Component mounted');
</cscript><header> is static: PHP and {{ }} don't run there (App.pvue's header can print variables)Use Vue-like directives for common tasks. All processing happens on the server.
<div p-if="$user->isAdmin">Admin Content</div>
Conditionally render elements based on PHP expressions. There is no p-else: use a second p-if with the opposite condition, or plain PHP.
<li p-for="$item in $items"></li>
Loop through arrays and objects to render lists. Use $key => $value in $items when you need the key.
<!-- Loop over a function call, then filter each item -->
<li p-for="$n in range(1, 5)" p-if="$n % 2">{{ $n }}</li>
<!-- Same-tag children, all on one line -->
<div p-for="$row in $rows"><div class="cell">{{ $row }}</div></div>
<!-- {{ }} in attributes, and void elements -->
<span p-if="$bNew" class="badge {{ $tone }}">New</span>
<input p-if="$bEdit" name="title" value="{{ $title }}">p-ifPDOStatement). Anything else renders nothingp-for + p-if on one element: loops first, then checks each item<p>{{ $user['name'] }} has {{ count($orders) }} orders</p>
<p>{{ $bVip ? 'VIP' : 'Member' }}</p><?= $html ?>$ or, since 0.0.3, a function call like count($orders)$user['name'], never $user.name{{ item.name }}) is left alone for AlpineJSPHPue respects user privacy by avoiding automatic form tracking. Instead of two-way data binding that monitors every keystroke, we encourage explicit form submissions with clear user intent.
<script>
@AJAX('POST')
function ajaxFormSubmit($input) {
$formData = $input['formData'] ?? [];
$email = trim($formData['email'] ?? '');
if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
echo json_encode(['success' => false, 'message' => 'Please enter a valid email.']);
return;
}
// Store in session to use later
$_SESSION['subForm_email'] = $email;
echo json_encode(['success' => true, 'message' => 'Thanks, you are subscribed!']);
}
$email = $_SESSION['subForm_email'] ?? '';
</script>
<template>
<form onsubmit="handleSubmit(event, 'ajaxFormSubmit')">
<input name="email" type="email" value="{{ $email }}">
<button type="submit">Submit</button>
<p id="formMessage"></p>
</form>
</template>
<cscript>
async function handleSubmit(event, methodName) {
event.preventDefault();
const formData = new FormData(event.target);
const response = await fetch(window.location.pathname, {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
action: methodName,
formData: Object.fromEntries(formData)
})
});
const result = await response.json();
document.getElementById('formMessage').textContent = result.message;
}
</cscript>
π‘ Note: We use explicit form submission instead of automatic tracking.
Users must intentionally click "Submit" - no passive data collection. That's why PHPue has no p-model, by design. Pre-fill fields with value="{{ $email }}". Want live previews while typing? Use AlpineJS x-model in the browser: nothing reaches the server until the user sends it.
Respect user privacy with explicit form handling patterns.
Instant browser refreshes when you edit your .pvue or PHP files. See changes in real-time without manual reloading.
cd www && php -S localhost:3000
Visit any page with ?live parameter:
localhost:3000/your-page?live
Edit any .pvue file and watch the browser refresh automatically! π₯
Using Docker? Hot reload works even better with full AJAX support!
π‘ Pro Tip: Use Docker Compose for the best development experience with full hot reload and AJAX support!
Create server-side AJAX handlers with simple annotations.
@AJAX('POST')
function saveUser($input) {
// Handle form submission ($input is the JSON body)
echo json_encode(['success' => true]);
}
// Browser: call it by name
fetch(window.location.pathname, {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({ action: 'saveUser', name: 'Ada' })
});@AJAX('GET')
function updateSession() {
if(isset($_GET['token'])) {
$_SESSION['userToken'] = $_GET['token'];
}
echo json_encode(['saved' => isset($_GET['token'])]);
}
// Browser: fetch('?action=updateSession&token=abc123')@AJAX('POST') or @AJAX('GET') right above a function in a view, App.pvue or a component
action field picks the function; POST data arrives as $input
json_encode): return values are discarded
@AJAX functions can be called. Other functions (and ?action=phpinfo) just load the page
backend/ or the session, not App variables
PHPue automatically handles 404 errors with support of customisable error pages. Create beautifully styled 404 pages that match your application's design.
Current Support: Only 404 pages are supported in this version.
Create a user-friendly 404 page that helps users navigate back to your application:
<?php
global $phpue_header;
$phpue_header = <<<HTML
<script src="https://cdn.tailwindcss.com"></script>
<title>404 - Page Not Found</title>
<meta name="description" content="The page you're looking for doesn't exist">
<meta name="keywords" content="404, page not found">
<meta name="author" content="Edward Patch">
HTML;
$GLOBALS['phpue_http404_header'] = $phpue_header;
?><!-- APP WRAPPER -->
<div class="min-h-screen bg-gradient-to-br from-gray-50 to-gray-100 flex items-center justify-center p-4">
<div class="max-w-md w-full text-center">
<div class="text-6xl mb-4">π</div>
<h1 class="text-2xl font-bold text-gray-900 mb-2">Page Not Found</h1>
<p class="text-gray-600 mb-6">
Sorry, we couldn't find the page you're looking for.
The page might have been moved or deleted.
</p>
<div class="space-y-3">
<a href="/" class="block w-full bg-emerald-600 hover:bg-emerald-700 text-white font-medium py-3 px-6 rounded-lg transition duration-200">
Return to Homepage
</a>
<button onclick="history.back()" class="w-full border border-gray-300 hover:bg-gray-50 text-gray-700 font-medium py-3 px-6 rounded-lg transition duration-200">
Go Back
</button>
</div>
</div>
</div>
<!-- END OF APP WRAPPER -->Sorry, we couldn't find the page you're looking for. The page might have been moved or deleted.
Extend PHPue with custom PHP classes and vendor libraries using the backend/ directory.
All classes are auto-loaded when the framework starts, making them available throughout your application.
PHPue fully supports Composer vendor directories and automatically detects autoload.php files.
Auto-loading: All PHP files in backend/ are automatically included when the framework initialises.
Vendor directories with autoload.php are fully supported. You can also create a custom autoload.php to control load order.
PHPue scans the backend/ directory on startup, in the same sorted order on every server 0.0.3
All .php files in the backend directory are automatically included.
If backend/vendor/autoload.php exists, PHPue automatically requires it, enabling full Composer vendor support (PSR-4, classmap, and files).
Create a custom autoload.php in any directory and add your require statements to control class load order.
PHPue will load classes in the specified order and skip the brute-force scan for that directory.
Your classes are now available throughout the application via singleton patterns or direct instantiation.
Create a singleton database manager that's available throughout your application:
<?php
class SimpleDB {
private static ?self $instance = null;
public static function getInstance(): self
{
if(self::$instance === null)
self::$instance = new self();
return self::$instance;
}
public function getMessage(): string
{
return "Hello from backend class!";
}
public function getUsers(): array
{
return [
['id' => 1, 'name' => 'John'],
['id' => 2, 'name' => 'Jane'],
];
}
}
?>
// In any .pvue file script section
<script>
$db = SimpleDB::getInstance();
$users = $db->getUsers();
</script>
PHPue fully supports Composer vendor directories and automatically detects autoload.php.
Simple libraries like Parsedown work out of the box. Complex dependencies may still require manual testing or a custom autoload.php.
β
Fully Supported: Composer vendor directories
π§ Needs Testing: Large multi-package ecosystems
# Download vendor library manually cd backend mkdir -p vendor wget https://github.com/erusev/parsedown/archive/1.7.4.zip unzip 1.7.4.zip -d vendor/ # Result: backend/vendor/parsedown-1.7.4/Parsedown.php
PHPue will automatically find and load Parsedown.php
or any autoload.php in backend/vendor/.
Class::getInstance() immediately
App.pvue, views/, or components/
autoload.php to control load order and prevent brute-force scanning
Complex libraries may still require testing, but following this sequence ensures best results.
By default PHPue starts a session on every request, just like 0.0.2. That's simple, but it adds a cookie and a no-store header to every page, so NGINX or a CDN can't cache it. 0.0.3 adds a lazy option.
// index.php: edit the define near the top
define('PHPUE_SESSION', 'lazy'); // 'auto' (default) or 'lazy'
// Need to write to the session? (login, cart, preferences)
phpue_session(true); // starts one if needed
$_SESSION['cart'][] = $sku;phpue_session(true). Public pages stay cacheable
session_start() yourself in App.pvue still turns PHPue's session handling off
The <html lang> attribute is worked out on every request (0.0.2 fixed it at build time). Pick a fixed language per page, or set it in code for a language switcher.
Put it in the view's <header>. Either form works:
<header>
<meta name="lang" content="fr">
<title>Ma Page en Français</title>
</header>
<header>
<!-- lang: es -->
</header>Write the meta exactly as name="lang" then content="β¦", with double quotes. <meta lang="fr"> is not recognised.
Call phpue_set_lang() in App.pvue's <script>, or in a backend/ file when it loads:
<!-- App.pvue -->
<script>
$lang = $_GET['lang'] ?? null;
if (in_array($lang, ['en', 'cy'], true)) {
$_SESSION['PHPue_Lang'] = $lang;
}
phpue_set_lang($_SESSION['PHPue_Lang'] ?? null);
</script>null means no override, so the view's meta and PHPUE_LANG still apply. PHPue_Lang is your own session key: PHPue doesn't set one.
The rest of the site stays English (PHPUE_LANG is 'en'). This one page sets <html lang="cy"> from its header, no PHP needed:
<header>
<meta name="lang" content="cy">
<title>Cysylltwch Γ’ Ni | PHPue</title>
</header>
<template>
<h1>Cysylltwch Γ’ ni</h1>
<p>Anfonwch neges atom a byddwn yn ateb cyn gynted Γ’ phosib.</p>
<form method="post">
<label>E-bost <input name="email" type="email"></label>
<button type="submit">Anfon</button>
</form>
</template>Result on /welsh-contact: <html lang="cy">. Every other page keeps <html lang="en">. Remember to #require 'views/welsh-contact.pvue'; in App.pvue.
phpue_set_lang() in a view's or component's <script> does nothing: <html lang> is printed before the view renders. Use the view's <header> instead.phpue_set_lang() sets the language. phpue_html_lang() only reads what will be printed.Order (first match wins):
PHP renders the page; the browser layer is optional. Use <cscript> for plain JavaScript, and AlpineJS when you want reactivity.
<cscript>
const fruits = {{ $fruits }}; // ["Banana","Apple"]
const theme = {{ $settings['theme'] }}; // "dark" (0.0.3: any $ expression)
document.querySelector('#count').textContent = fruits.length;
</cscript><cscript> becomes a script tag after your markup, so the page is ready when it runs
{{ $anything }} inside it is turned into JSON: arrays and objects arrive ready to use
<!-- App.pvue header -->
<script defer src="/assets/js/fworks/alpine.min.js"></script>
<script src="/assets/js/phpue-ext-csr/alpine.ext.min.ssr.js"></script>
<!-- any view -->
<div x-data="{ count: {{ $initial }} }">
<button @click="count++">Clicked <span x-text="count">{{ $initial }}</span></button>
</div>x-text elements too, so the page is right before Alpine starts
<template x-for> now compiles 0.0.3, but it builds the list in the browser
Everything you can set in index.php, and the helper functions available in any .pvue file.
<html lang> (default 'en')'auto' or 'lazy' 0.0.3<html lang> 0.0.3The most common surprises, and the fix for each.
.dist/ folder exists, so compiled files are served. Rebuild or delete it
#required in App.pvue. A 405 means the method is wrong
?live keeps the single PHP worker busy. Test without it, or use Docker
__DIR__ points into .dist/ once compiled. Use getcwd()
'</scr' . 'ipt>'
PHPUE_SESSION = 'lazy'