phpspa-js is the lightweight JavaScript runtime for phpSPA, a PHP framework that mimics Single Page Application behavior without the complexity of a frontend framework.
It handles client-side navigation, page transitions, script execution, component styling, and event hooks — all designed to work with dynamic content rendered from PHP.
You can include phpspa-js either via CDN or host it yourself.
<script src="https://cdn.jsdelivr.net/npm/phpspa-js"></script>Clone or download from the repo:
git clone https://github.com/dconco/phpspa-js.gitThen include it in your layout:
<script src="/path/to/phpspa-js/dist/phpspa.min.js"></script>Once included, phpspa-js automatically enhances <Link /> tags with data-type="phpspa-link-tag" and enables seamless navigation between registered components.
You don’t need to do anything fancy — just generate links using your backend that look like this:
<a href="/dashboard" data-type="phpspa-link-tag">Dashboard</a>Navigates to a new route dynamically. Internally fetches the component content, updates the targetID, <title>, styles, and scripts.
url: Can be a string orURLobject.mode:"push"(default) adds a new history entry,"replace"modifies the current one.
phpspa.navigate("/profile", "replace");Handles SPA-style backward or forward navigation using browser history.
phpspa.back(); // like window.history.back()
phpspa.forward(); // like window.history.forward()Use phpspa.on() to register event hooks:
phpspa.on("beforeload", ({ route }) => {
console.log("Navigating to", route);
});
phpspa.on("load", ({ route, success, error }) => {
if (success) {
console.log("Loaded:", route);
} else {
console.error("Failed to load", route, error);
}
});| Event Name | Description |
|---|---|
beforeload |
Fired before route is loaded |
load |
Fired after load is completed or failed |
Event callbacks receive an object:
{
route: string,
success?: boolean,
error?: Error
}Each component can include inline scripts using:
<script data-type="phpspa/script">
console.log("Component script ran");
</script>These are dynamically executed when the component is loaded via phpspa.navigate() or browser navigation. They won’t run on initial page load unless rendered by PHP.
Components can also define scoped styles:
<style data-type="phpspa/css">
.button { color: red; }
</style>These styles are:
- Appended to the
<head>dynamically - Automatically cleaned up when navigating to another route
phpspa-js supports native scroll restoration:
history.scrollRestoration = "auto";This ensures each component can handle scroll behavior without interference.
This script is tightly coupled with phpSPA (PHP), and it's designed to work with its component system.
- CDN build:
phpspa.min.js - Event system:
phpspa.on("load", ...) - History API used for SPA behavior
- Graceful fallback when JS is disabled
- GitHub: dconco/phpspa
- JS Engine: dconco/phpspa-js
- Website: https://phpspa.readthedocs.io
- License: MIT
MIT © Dave Conco