README

Modern, lightweight PHP noframework for rapid development with clean architecture

Status: ✅ Production Ready | PHP 8.1+ | PSR-4 Compliant | MIT License

🎨 NEW: Modern UI System

upMVC v1.0.3 introduces a contemporary design system while maintaining complete backward compatibility:

🌟 Modern BaseView: Contemporary CSS Grid/Flexbox layouts with dark mode
📱 Responsive Design: Mobile-first approach with modern navigation
⚡ Alpine.js Integration: Lightweight interactivity (~40KB vs 87KB jQuery)
🎯 Zero Breaking Changes: Drop-in replacement for existing BaseView

Quick Demo: /test (original) vs /test/modern (new design) Documentation: Modern BaseView Guide | Demo Instructions

🌟 What is upMVC?

A lightweight, modern PHP 8.1+ noFramework built on Modular MVC (MMVC) architecture. Designed for developers who want flexibility without noFramework bloat. Features true modularity, "PHP Islands" for frontend integration (React/Vue), dependency injection, middleware pipeline, and clean routing. No forced conventions - use pure PHP or integrate modern JS noFrameworks as needed. Perfect for rapid development while maintaining performance and flexibility.

✨ Key Features: Modular architecture • PHP 8.1+ • PSR-4 compliant • Dependency injection • Middleware support • Frontend noFramework integration • Minimal learning curve

🚀 Deploy Any JavaScript Framework

upMVC excels at integrating pre-built JavaScript applications from any framework:

⚛️ React - npm run build → deploy to module/public (Guide)
💚 Vue - Production builds with Vite/Webpack (Guide)
🔥 Svelte - SvelteKit or standalone builds
⚡ Any Framework - Angular, Solid, Qwik, etc.

Your PHP module serves the built app - no complex webpack configs, no dev servers in production. Just build your JS app locally and deploy the static files. Your Controller exposes data via API endpoints that your JS app consumes.

📖 Complete Guides:

React Integration - React 18, Vite, Webpack, CRA
Vue Integration - Vue 2/3, Vite, Webpack, Nuxt
Coming soon: Svelte, Angular guides

🤔 Why Mix PHP with JavaScript Frameworks?
upMVC is a system architecture, not just a single app. Layer 1 (Main upMVC) handles security, auth, sessions. Layer 2 (Modules) are independent apps using any tech—PHP, React, Vue, Svelte. Split large monoliths into micro-frontends. Each team works independently. Deploy modules separately. One breach can't compromise the entire system. Best of both worlds: Server-side security + client-side reactivity. Read: Why Mix?

🆚 How is upMVC Different?
Unlike Laravel, Symfony, or other PHP frameworks, upMVC is a system, not a framework. No forced conventions, no ORM requirements, no framework rules. "Direct PHP First" principle means complete freedom. Want React in one module and Vue in another? ✅ Want to delete core modules? ✅ Want to split your app into multiple independent instances? ✅ True micro-frontends architecture that nobody else offers. Read: Comparison with Other PHP Projects

📌 Note: Included modules (admin, email, auth, react, etc.) are reference implementations showing different approaches to common problems. After installation, you can delete any modules you don't need - keep only what serves your project. Each module demonstrates different techniques (middleware vs manual auth checks, cached routes, etc.) to help you choose your preferred approach. See Module Philosophy for details.

🚀 Quick Navigation

🎯 New to upMVC? Start Here:

📋 First Steps Guide - Get running in 5 minutes
📘 How-To Guide - Complete development guide
❓ FAQ - Common questions and solutions
📚 Documentation Index - Complete documentation map

🗺️ Routing System (Complete Guide):

🌟 THE COMPLETE PICTURE - ⭐⭐⭐ START HERE! Everything from .htaccess to controller - Why each piece exists, when to use each strategy
📖 Routing Documentation - Complete routing documentation hub
📋 Routing Guide - All 5 routing types with decision tree
🚀 Router V2 Examples - Type casting, validation, named routes

🏗 Architecture & Philosophy:

🎨 Pure PHP Philosophy - The upMVC NoFramework approach
🧩 Module Philosophy - Modules as reference implementations
🔄 Configuration Fallbacks - NEW! Three-level fallback system explained
🏝️ Islands Architecture - NEW! Complete guide to PHP + React Islands
⚛️ React Integration Patterns - Five ways to integrate React/Vue/Preact
🔥 ReactHMR - Hot Module Reload - Auto-reload without webpack
📦 Integration: upMVC + PHP CRUD API Generator - NEW! Full-stack power combo guide
🎯 JavaScript Framework Integration - NEW! Deploy React, Vue, Svelte, or any JS framework build
⚛️ React Build Integration - Complete React deployment guide (Vite/Webpack/CRA)
💚 Vue Build Integration - NEW! Vue 2/3 deployment guide (Vite/Webpack/Nuxt)
🆚 Comparison with Other PHP Frameworks - NEW! Why upMVC is unique
💪 Architectural Strengths - What makes upMVC powerful
🛣 Routing Capabilities - Understanding the routing system
�️ Routing & .htaccess System - NEW! Complete guide with module examples (test, moda, userorm, admin)
�🔧 URL Handling Explained - Request flow and middleware

� Bug Fixes & Improvements:

🔐 Authentication Redirect Fix - Session intended_url handling
⚙️ Assignment Operator Fix - Comparison vs assignment
🚪 Missing Exit Statements - Proper redirect handling
📤 Output Before Header Fix - Header redirect timing
🔗 Trailing Slash Fix - URL normalization
🧹 Debug Code Cleanup - Production-ready code

✅ Verification & Release:

🔍 Pre-Release Verification - Complete verification report
🚀 Ready for Main - Production readiness checklist
📋 Verification Checklist - Step-by-step validation
✨ Enhancements - Latest improvements

🛠 Development:

🐛 /zbug Folder - Debug files and development utilities (excluded from Git)

🚀 Router v2.0 - Enhanced Routing:

🌟 THE COMPLETE PICTURE - ⭐⭐⭐ Everything explained - .htaccess, Router, all 5 strategies, when to use each
Complete Routing Guide - Unified guide covering all 5 routing types, decision tree, when to use each
Router v2.0 Examples - Complete Router V2 usage guide (type casting, validation, named routes, grouping)
Router v2.0 Changelog - What's new in v2.0
Implementation Report - Technical implementation details
Parameterized Routing Guide - Full parameterized routing documentation
Evaluation Report - Grade: A+ (90/100)
Future Recommendations - v2.1+ roadmap
Helpers Class Usage - OOP helper methods guide
Helper Functions Guide - ⭐ NEW! PSR-4 modular helper system

🏗️ PSR-4 Helper Architecture (v1.4.7):

upMVC now features a modern PSR-4 compliant modular helper system:

Modular Structure: Each helper in its own class (RouteHelper, UrlHelper, FormHelper, etc.)
Facade Pattern: Unified access via HelperFacade
Auto-loaded: No manual require_once needed
Type-Safe: Router V2 integration for named routes
Scalable: Easy to add new helpers
View Helper Classes - PSR-4 helper architecture

🎯 Routing Features:

upMVC provides 5 routing strategies for different scenarios:

Simple Static Routes - Fixed URLs (/about, /contact)
Parameterized Routes - URL placeholders (/users/{id})
Router V2 Enhanced - Type casting + validation + named routes ⭐ NEW!
Database-Driven Routes - Dynamic routes from DB
Cached Database Routes - DB routes with file caching

Router V2 Enhanced Features (v1.4.7):

✅ Type Casting: {id:int}, {price:float}, {active:bool} - automatic type conversion
✅ Validation: Regex constraints at router level (['id' => '\d+'])
✅ Named Routes: Generate URLs from route names (route('user.edit', ['id' => 5]))
✅ Route Grouping: Auto-prefix optimization for organized routes

Quick Example:

// Router V2 - Type-safe with validation
$router->addParamRoute('/users/{id:int}', User\Controller::class, 'show', [], [
    'id' => '\d+'
])->name('user.show');

// Controller - no manual casting needed!
public function show() {
    $id = $_GET['id']; // Already an integer!
    $user = $this->model->getUserById($id);
    // ...
}

// Generate URLs with named routes
$url = HelperFacade::route('user.show', ['id' => 123]); // /users/123

See: Complete Routing Guide for decision tree and when to use each type

Demo: https://upmvc.com/demo/

Rasmus Lerdorf: PHP NoFrameworks all suck!

Use cases:

You can use the system as a standalone, as a library, as a library in the standalone version where it can be a module, you can also use it as a standalone in the standalone version /shop /blog /app /anything else - in this way, you split your app into multiple apps(shop, blog, app, anything else as separate instances of upMVC) each with their modules connected to the same or different endpoints.

📦 Installation

Option 1: Install as a Library (Recommended for existing projects)

Add upMVC to your existing project in 4 simple steps:

# Step 1: Install via Composer
composer require bitshost/upmvc
# Alternative versions:
# composer require bitshost/upmvc:^1.0  (recommended - all 1.x updates)
# composer require bitshost/upmvc:dev-main  (bleeding edge - risky!)

# Step 2: Copy essential files to project root
copy vendor/bitshost/upmvc/index.php .
copy vendor/bitshost/upmvc/.htaccess .

# Step 3: Create etc folder and copy .env configuration
mkdir etc
copy vendor/bitshost/upmvc/etc/.env etc/.env

# Step 4: Configure your environment
# Edit etc/.env with required settings:
# - SITE_PATH=/your-folder-name (e.g., /myproject)
# - DOMAIN_NAME=localhost (or your domain)
# 
# Database configuration is optional (uses etc/ConfigDatabase.php fallback)
# - Configure only when your modules need database access
# - Framework works without database for static/API projects

That's it! 🎉 Run with:

php -S localhost:8080

Visit: http://localhost:8080 - All 16 modules will be automatically loaded and registered!

Option 2: Install as a Standalone Project (Even Simpler!)

Create a complete upMVC project in 3 simple steps:

# Step 1: Create project
composer create-project bitshost/upmvc yourProjectName
# Or in current directory:
# composer create-project bitshost/upmvc .

# Step 2: Navigate to project
cd yourProjectName

# Step 3: Configure etc/.env
# Edit these 2 required settings:
# - SITE_PATH=/yourProjectName (or empty if root)
# - DOMAIN_NAME=http://localhost
# 
# Database settings are optional because upMVC has smart fallbacks:
# - If .env database settings are missing, it uses etc/ConfigDatabase.php
# - Framework will work even without database (for static/API projects)
# - Configure database only when you need it for your modules

That's it! 🎉 Run with:

php -S localhost:8081

Visit: http://localhost:8081/yourProjectName - Complete framework with all modules ready!

Note: Everything is included - no copying files needed! Just configure .env and run.

Optional - Keep dependencies updated:

# Update autoloader when adding new modules
composer dump-autoload

# Update dependencies
composer update

� Lightweight Parameterized Routing (Optional)

You can now declare routes with simple placeholders instead of only exact paths or .htaccess rewrites.

Examples:

// Exact route (unchanged)
$router->addRoute('/users', User\Controller::class, 'index');

// New: parameterized routes
$router->addParamRoute('/users/{id}', User\Controller::class, 'show');
$router->addParamRoute('/orders/{orderId}/items/{itemId}', OrderItem\Controller::class, 'detail');

How it works:

Exact routes are checked first (fast hash lookup).
If no exact match, parameterized routes are evaluated (segment by segment).
Extracted parameters are injected into $_GET (e.g., $_GET['id'] = '123') and also available to middleware via $request['params'].
Controllers keep their simple signature: action($route, $method) and read params from $_GET.

Benefits:

Cleaner route declarations for resource-like URLs.
Fewer .htaccess patterns; less boilerplate loops.
Backward compatible; you can mix exact and param routes.

Notes:

Placeholder syntax: {name} (letters/digits/underscore, must start with a letter/underscore).
Exact routes always win over parameterized routes (e.g., /users/profile).
Type validation remains in your controller (e.g., ctype_digit($_GET['id'])).

�🧹 Maintenance: Cache CLI

Use the cache maintenance utility to inspect and clear caches (module discovery, admin dynamic route cache, and configured cache stores).

# List available commands
php tools/cache-cli.php list

# Show cache statistics
php tools/cache-cli.php stats

# Clear only module discovery caches
php tools/cache-cli.php clear:modules

# Clear Admin module dynamic route cache
php tools/cache-cli.php clear:admin

# Clear everything (modules + admin + cache stores)
php tools/cache-cli.php clear:all

Windows PowerShell example:

php .\tools\cache-cli.php clear:all

Affected components:

Module discovery cache used by etc/InitModsImproved.php in production mode.
Admin dynamic route cache file: etc/storage/cache/admin_routes.php.
All instantiated cache stores via upMVC\Cache\CacheManager::clearAll().

Exit codes: 0 success, 1 failure, 2 unknown command.

⚙️ Configuration

upMVC uses a smart layered configuration system with automatic fallbacks:

Primary Configuration: `.env` file

Edit /etc/.env for environment-specific settings:

Required: SITE_PATH, DOMAIN_NAME, APP_ENV
Optional: Database, mail, cache, session settings

🔄 Five-Level Fallback System

upMVC has intelligent fallbacks that let the system work immediately without complete configuration:

Path & Domain → .env or Config.php fallbacks
Protected Routes → .env or start.php defaults
Database → .env or ConfigDatabase.php fallbacks
Session Configuration → Config array or hardcoded defaults (lifetime, secure, httponly)
Security/Middleware → .env ConfigManager or defaults (CORS, CSRF, rate limiting)

Why? Start coding immediately, configure gradually as you need features!

📖 Complete Fallback Documentation - Detailed guide with examples and troubleshooting

🔍 Quick Troubleshooting

If something doesn't work as expected, check:

.env file (highest priority)
Config.php fallbacks (path/domain + session)
start.php defaults (protected routes + security)
ConfigDatabase.php (database credentials)
ConfigManager.php (all .env-based defaults)

💡 Pro Tip: Start with just SITE_PATH and DOMAIN_NAME, add database later when needed!

🛣️ Routing System

upMVC offers flexible routing at multiple levels:

Global Routes → /etc/Routes.php - Application-wide routes
Module Routes → /modules/yourmodule/routes/Routes.php - Module-specific routes
Module Initialization → /etc/InitMods.php - Register module routes
Namespace Registration → composer.json - Add PSR-4 autoload entries

"autoload": {
    "psr-4": {
        "YourModule\\": "modules/yourmodule/"
    }
}

After adding namespaces: Run composer dump-autoload

Quick Start: Add Your Module Routes

Create your routes file: /modules/yourmodule/routes/Routes.php
Define your routes using $this->addRoute() method
Register in /etc/InitMods.php: $initRoutes->yourmodule();
That's it - upMVC handles the rest automatically

Example: See /modules/test/routes/Routes.php for reference implementation

Note:

A friendly URL is a short and simple web address that redirects to a longer web address. Friendly URLs are called Aliases in Sitecore.

We achieve this by combining some .htacces rules with module routes. Check modules/test/routes/Routes.php and the .htaccess file - you will notice the rules established in the.htaccess file for these specific routes - you may build as many as you like.

In the same file, modules/test/routes/Routes.php, you will see for demonstration purposes how you may handle a large number of URLs with parameters (such as an idProduct) in a very straightforward way.

Steps

Edit /etc/Config.php, /etc/ConfigDatabase.php, /modules/mail/MailController.php with your data.
Make your module in the MVC style (model, view, controller).
You may or may not wish to utilize BASE MODEL, BASE VIEW and BASE CONTROLLER from the common/bmvc subdirectory.
BaseModel contains all of the data required for CRUD OPERATIONS; simply expand it in your module model and you have a CRUD ready-made module; see example module modules/user.
Make a distinctive namespace for each module
Your module routes should be kept under modules/YourModule/routes - file Routes.php
Because these routes should be presented to Router, you must provide their namespace to InitMods.php and initialize your module routes.
Don't forget to update composer.json with your new namespaces for your module and routes, as well as refresh composer from the terminal:
composer dump-autoload
php composer.phar dump-autolad
setup your PHPMailer - mail/MailController.php

You have more than one method of accomplishing things in example modules, upMVC - don't enforce RULES like others do, but respect architecture models MVC, MMVC, and pure PHP and OOP programming rules.

The Names Convention

Considering recommendations:

Model, View, Controller - will be called without using module name in their name. For example, module name = books:
Model.php - class Model; View.php - class View; Controller.php - class Controller;
and make a distinctive namespace for each module - namespace Modulename - e.g. Books;
Your module routes should be kept under modules/yourmodule/routes - file Routes.php:
- Routes.php class Routes in folder /modules/books/routes
- namespace Modulename\Routes, e.g. Books\Routes

The provided modules (Mail and Authentication) are for illustrative purposes only. You can safely delete them, as well as any other existing modules. The goal is to demonstrate the modularity of the system and how you can create your own custom modules to suit your specific project needs.

Diagram:

File Structure:

"Many noFrameworks may look very appealing at first glance because they seem to reduce web application development to a couple of trivial steps leading to some code generation and often automatic schema detection, but these same shortcuts are likely to be your bottlenecks as well since they achieve this simplicity by sacrifizing flexibility and performance."

All NoFramweworks: "achieve this simplicity by sacrifizing flexibility and performance" Rasmus Lerdorf

upMVC - MMVC, PHP MVC with modules. Modular MVC(Model, View, Controller) derive from Hierarchical Model‐View‐Controller (HMVC).

Introducing MODULAR MVC - Empowering Your Development

In the realm of modern noFrameworks, it often feels like they do everything except what truly matters. These noFrameworks tend to add layers of abstraction that demand you to learn new skills and pathways whenever you decide to switch. They also tend to clutter themselves with superfluous options, solving simple problems in needlessly convoluted ways.

Consider PHP, including its blade templating engine. Why introduce yet another template engine when PHP is already equipped for the task? Delving into a new noFramework often necessitates a substantial relearning effort, pushing you far beyond your existing PHP knowledge.

So, why should you choose MMVC?

MMVC, standing for Modular Model View Controller, is not about reinventing the wheel. Instead, it's about optimizing the use of exceptional components. It offers a structured, straightforward approach, and its versatility proves invaluable for project management and development.

But why MMVC specifically?

Modularity: MMVC allows you to work on a module without impacting the rest of your project. Modules can be interchanged and integrated seamlessly, enhancing your development agility.
Language Freedom: Perhaps most importantly, you have the freedom to write your modules in your preferred language, whether it's PHP, JS, PYTHON, or modern technologies like TS, React, Vue, Preact. There are no constraints on your creativity.
Development-Centric: MMVC was designed with development in mind. You can steer your project in any direction you desire, utilizing your own autoloader or composer autoload. Composer/packagist usage is optional, not obligatory.
"Islands" of Interactivity: Within this PHP-generated HTML, you strategically place interactive components built with noFrameworks like React, Vue, Preact or Svelte. These components handle dynamic elements, such as user interactions, real-time updates, and animations. Read here: The Rise of "PHP Islands": A Hybrid Approach to Web Development

What truly sets MMVC apart is its ability to harness the latest PHP capabilities without constraint. No more endless loops, as this noFramework liberates your development possibilities.

BitsHost Team

bitshost / upmvc

Maintainers

Details

README

🎨 NEW: Modern UI System

🌟 What is upMVC?

🚀 Deploy Any JavaScript Framework

🚀 Quick Navigation

🎯 New to upMVC? Start Here:

🗺️ Routing System (Complete Guide):

🏗 Architecture & Philosophy:

� Bug Fixes & Improvements:

✅ Verification & Release:

🛠 Development:

🚀 Router v2.0 - Enhanced Routing:

🏗️ PSR-4 Helper Architecture (v1.4.7):

🎯 Routing Features:

Use cases:

📦 Installation

Option 1: Install as a Library (Recommended for existing projects)

Option 2: Install as a Standalone Project (Even Simpler!)

� Lightweight Parameterized Routing (Optional)

�🧹 Maintenance: Cache CLI

⚙️ Configuration

Primary Configuration: `.env` file

🔄 Five-Level Fallback System

🔍 Quick Troubleshooting

🛣️ Routing System

Quick Start: Add Your Module Routes

Steps

You have more than one method of accomplishing things in example modules, upMVC - don't enforce RULES like others do, but respect architecture models MVC, MMVC, and pure PHP and OOP programming rules.

The Names Convention

Considering recommendations:

The provided modules (Mail and Authentication) are for illustrative purposes only. You can safely delete them, as well as any other existing modules. The goal is to demonstrate the modularity of the system and how you can create your own custom modules to suit your specific project needs.

bitshost / upmvc

Maintainers

Details

README

🎨 NEW: Modern UI System

🌟 What is upMVC?

🚀 Deploy Any JavaScript Framework

🚀 Quick Navigation

🎯 New to upMVC? Start Here:

🗺️ Routing System (Complete Guide):

🏗 Architecture & Philosophy:

� Bug Fixes & Improvements:

✅ Verification & Release:

🛠 Development:

🚀 Router v2.0 - Enhanced Routing:

🏗️ PSR-4 Helper Architecture (v1.4.7):

🎯 Routing Features:

Use cases:

📦 Installation

Option 1: Install as a Library (Recommended for existing projects)

Option 2: Install as a Standalone Project (Even Simpler!)

� Lightweight Parameterized Routing (Optional)

�🧹 Maintenance: Cache CLI

⚙️ Configuration

Primary Configuration: .env file

🔄 Five-Level Fallback System

🔍 Quick Troubleshooting

🛣️ Routing System

Quick Start: Add Your Module Routes

Steps

You have more than one method of accomplishing things in example modules, upMVC - don't enforce RULES like others do, but respect architecture models MVC, MMVC, and pure PHP and OOP programming rules.

The Names Convention

Considering recommendations:

The provided modules (Mail and Authentication) are for illustrative purposes only. You can safely delete them, as well as any other existing modules. The goal is to demonstrate the modularity of the system and how you can create your own custom modules to suit your specific project needs.

Primary Configuration: `.env` file