Skip to content

README.md

Latest commit

 

History

History
248 lines (176 loc) · 5.61 KB

README.md

File metadata and controls

248 lines (176 loc) · 5.61 KB

📦 phpSPA - Build Native PHP SPAs Without JavaScript Frameworks

📛 Name

phpSPA lets you build fast, interactive single-page apps using pure PHP — with dynamic routing, component architecture, and no full-page reloads. No JavaScript frameworks required.

License JS Version Documentation GitHub stars PHP Version Total Downloads

🎯 Goal

To empower PHP developers to create modern, dynamic web apps with the elegance of frontend SPA frameworks — but fully in PHP.

  • 🚫 No full-page reloads
  • ⚡ Instant component swapping
  • 🧱 Clean, function-based components
  • 🌍 Real SPA behavior via History API
  • 🧠 Now with State Management!

🧱 Core Features

  • 🔄 Dynamic content updates — feels like React
  • 🧩 Component-based PHP architecture
  • 🔗 URL routing (client + server synced)
  • 🧠 Built-in State Management
  • ⚙️ Lifecycle support for loaders, metadata, etc.
  • 🪶 Minimal JS: one small file
  • 🔁 Graceful fallback (no JS? Still works)

✨ Features

  • ✅ Fully PHP + HTML syntax
  • ✅ No template engines required
  • ✅ Dynamic GET & POST routing
  • ✅ Server-rendered SEO-ready output
  • ✅ Per-component and global loading indicators
  • ✅ Supports Composer or manual usage
  • ✅ State system: update UI reactively from JS

🧠 Concept

  • Layout → The base HTML (with __CONTENT__)
  • Component → A PHP function returning HTML
  • App → Registers and runs components based on routes
  • State → Simple mechanism to manage reactive variables across requests

🧩 State Management

You can create persistent state variables inside your components using:

$counter = createState("counter", 0);

Update state from the frontend:

phpspa.setState("counter", newValue);

This will automatically re-render the component on update.

📦 Installation

1. Via Composer (Recommended)

composer require dconco/phpspa

Include the autoloader:

require 'vendor/autoload.php';

2. Manual

Include the core files:

require 'path/to/phpspa/core/App.php';
require 'path/to/phpspa/core/Component.php';

🌐 JS Engine (CDN)

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

🚀 Getting Started (with Live Counter)

<?php
// layout.php
function layout() {
    return <<<HTML
    <html>
        <head>
            <title>My Live App</title>
        </head>
        <body>
            <div id="app">__CONTENT__</div>
            <script src="https://cdn.jsdelivr.net/npm/phpspa-js"></script>
        </body>
    </html>
    HTML;
}
<?php
// components.php
function HomePage() {
    $counter = createState("count", 0);

    return <<<HTML
        <h1>Counter: {$counter}</h1>
        <button onclick="phpspa.setState('count', {$counter} + 1)">Increase</button>
        <button onclick="phpspa.setState('count', 0)">Reset</button>
        <br><br>
        <Link to="/login" label="Go to Login" />
    HTML;
}

function LoginPage() {
    return <<<HTML
        <h2>Login</h2>
        <form method="post">
            <input name="username" placeholder="Username"><br>
            <input name="password" type="password" placeholder="Password"><br>
            <button type="submit">Login</button>
        </form>
    HTML;
}
<?php
// index.php
require 'layout.php';
require 'components.php';

$app = new App('layout');
$app->targetId('app');

$app->attach(
    (new Component('HomePage'))
        ->title('Home')
        ->method('GET')
        ->route('/')
);

$app->attach(
    (new Component('LoginPage'))
        ->title('Login')
        ->method('GET|POST')
        ->route('/login')
);

$app->run();

🛠 JS Events

phpspa.on("beforeload", ({ route }) => showLoader());
phpspa.on("load", ({ success }) => hideLoader());

📚 Full Documentation

Looking for a complete guide to phpSPA?

🔗 Read the full tutorial and advanced usage on Read the Docs:

👉 https://phpspa.readthedocs.io

The docs include:

  • 📦 Installation (Composer & Manual)
  • 🧩 Component system
  • 🔁 Routing & page transitions
  • 🧠 Global state management
  • ✨ Layouts, nesting, and loaders
  • 🛡️ CSRF protection
  • 🧪 Practical examples & best practices

Whether you're just getting started or building something advanced, the documentation will walk you through every step.

📘 Docs & Links

📘 License

MIT License © dconco

🧑‍💻 Maintained by

Dave Conco Simple, fast, and native PHP – just the way we like it.

🌟 Give Me a Star

If you find phpSPA useful, please consider giving it a star on GitHub! It helps others discover the project and keeps the momentum going 🚀

👉 Give us a ⭐ on GitHub

Your support means a lot! ❤️