phpspa-js

v1.1.9

Published

6 months ago

A lightweight, component-based PHP library for building Single Page Applications (SPAs) without relying on heavy frontend frameworks.

Downloads

0High
0Medium
0Low

daveconco

php spa phpspa js jsx javascript component-library

⚡ phpspa-js

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.

🚀 Installation

You can include phpspa-js either via CDN or host it yourself.

✅ CDN (Recommended)

<script src="https://cdn.jsdelivr.net/npm/phpspa-js"></script>

🔧 Manual (GitHub)

Clone or download from the repo:

git clone https://github.com/dconco/phpspa-js.git

Then include it in your layout:

<script src="/path/to/phpspa-js/dist/phpspa.min.js"></script>

🌐 Usage

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>

🧠 Core API

📥 `phpspa.navigate(url, mode = "push")`

Navigates to a new route dynamically. Internally fetches the component content, updates the targetID, <title>, styles, and scripts.

url: Can be a string or URL object.
mode: "push" (default) adds a new history entry, "replace" modifies the current one.

phpspa.navigate("/profile", "replace");

↩️ `phpspa.back()`, `phpspa.forward()`

Handles SPA-style backward or forward navigation using browser history.

phpspa.back();     // like window.history.back()
phpspa.forward();  // like window.history.forward()

📌 Event System

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);
    }
});

Available Events

| 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
}

🧩 Component Scripts

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.

🎨 Component Styles

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

🧼 Scroll Restoration

phpspa-js supports native scroll restoration:

history.scrollRestoration = "auto";

This ensures each component can handle scroll behavior without interference.

📦 Built for Integration

This script is tightly coupled with phpSPA (PHP), and it's designed to work with its component system.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme