README

A lightning-fast, zero-reload Single Page Application (SPA) engine for any PHP Framework (Laravel, CodeIgniter, Symfony, Slim, or even raw PHP).

Two Modes

This package empowers you with two distinct approaches:

1. HTML Mode (Zero Backend Required)

In this mode, the frontend JavaScript fetches the full HTML page, parses it in the browser using DOMParser, and swaps out the body. Pros: Requires ZERO PHP changes. Works with static sites or any backend.

2. JSON Mode (Bandwidth Optimized)

In this mode, the PHP backend intercepts the response buffer, parses the HTML, and sends only the required parts (Title, Body, Styles, Scripts, Meta) as a tiny JSON object. Pros: Faster network transfer.

Installation

composer require jarir-ahmed/universal-spa

Setup (JSON Mode)

Put this at the very top of your PHP application (e.g., public/index.php or as a middleware):

\JarirAhmed\UniversalSpa\SpaEngine::start();

Add data-spa-content to your main wrapper in your HTML layout:

<main data-spa-content>
    <!-- Your page content goes here -->
</main>

Add the data-spa attribute to any links you want to feel instant:

<a href="/about" data-spa>About Us</a>

Include the JS script and initialize it:

<script src="path/to/resources/js/jarir-spa.js"></script>
<script>
    new JarirSpa({
        mode: 'json' // or 'html'
    });
</script>

Configuration Options

All options are passed to the JarirSpa constructor:

<script>
    new JarirSpa({
        mode: 'json',                    // 'json' or 'html' (default: 'html')
        contentSelector: '[data-spa-content]', // CSS selector for content container
        progressBar: true,                // Show loading progress bar (default: true)
        transition: true,                 // Enable fade transitions (default: true)
        transitionDuration: 200,          // Transition duration in ms (default: 200)
        progressBarColor: 'linear-gradient(90deg, #4f46e5, #06b6d4)' // Progress bar color
    });
</script>

Features

Framework Agnostic — Works with Laravel, Symfony, CodeIgniter, Slim, CakePHP, raw PHP
Two Modes — HTML mode (zero backend changes) or JSON mode (bandwidth optimized)
Hover Prefetching — Links are prefetched on hover for instant loads
Loading Progress Bar — Slim animated bar at top during navigation (like YouTube/GitHub)
Smooth Page Transitions — Configurable fade-out/fade-in animations
Inline Script Execution — Scripts inside swapped content are properly re-executed
CSS Scoping — Old page styles are removed and new ones injected on navigation
Meta Tag Updates — Updates <meta> description and Open Graph tags on navigation
Browser History Support — Back/forward buttons work via pushState/popstate
Active Navigation — Auto-toggles active class on SPA links
Smart Link Filtering — Only intercepts data-spa links; external links work normally
Graceful Fallback — Falls back to full-page navigation on errors
Custom Events — Dispatches spa:navigated event for extensibility
Lightweight — ~10KB JS, ~3KB PHP. No external dependencies.

Layout vs Page Styles/Scripts

Mark your layout (persistent) styles and scripts so they're never removed on navigation:

<!-- Layout style — persists across navigations -->
<style data-spa-layout-style>
    body { font-family: sans-serif; }
    nav { background: #333; }
</style>

<!-- Page-specific style — swapped automatically on navigation -->
<style>
    .hero { background: blue; }
</style>

<!-- Layout script — runs once, never re-executed -->
<script data-spa-layout-script>
    new JarirSpa({ mode: 'json' });
</script>

Events

Listen for navigation events:

document.addEventListener('spa:navigated', (e) => {
    console.log('Navigated to:', e.detail.url);
    console.log('Page title:', e.detail.title);
    // Re-init your widgets, analytics, etc.
});

License

MIT

jarir-ahmed / universal-spa

Maintainers

Package info

Statistics

Security