MVC
Architecture MVC Libraries
Documentation Portal
PHP MVC Foundation

Documentation built for shipping, not guessing.

architecture-MVC-libraries is a lightweight PHP MVC foundation for APIs and server-rendered applications. It combines explicit controller dispatch, lazy database access, centralized JSON responses, and a simple code generator into a maintainable starting point for real-world projects.

Start Here Read the Architecture Reference

What It Includes

Front controller, AltoRouter integration, core request and response services, authentication helpers, upload and mail utilities, plus a CLI scaffolder.

Design Priorities

Explicit flow, predictable routing, lightweight abstractions, and practical extensibility over heavy framework ceremony.

Best Fit

Use it for APIs, admin tools, prototypes that need structure, or small applications where a full framework would feel excessive.

Getting Started

Install dependencies, create your environment file, then run the built-in PHP server.

composer install
composer dump-autoload
cp .env.example .env
php -S localhost:8000 -t public

Required Environment Variables

  • DB_HOST, DB_NAME, DB_USER, DB_PASS
  • JWT_SECRET
  • CORS_ALLOWED_ORIGINS
  • APP_ENV and APP_DEBUG
  • SMTP variables when mail delivery is enabled

Project Structure

config/       Environment and application configuration
controllers/  Base controller and application controllers
core/         Request, response, auth, config, and bootstrapping services
models/       Data access classes and domain models
public/       HTTP entry point
router/       AltoRouter wrapper and controller dispatcher
routes/       Route declarations grouped by HTTP verb
tests/        Lightweight test runner and architecture checks
utils/        Reusable helpers: security, uploads, and mail
views/        PHP templates for server-rendered pages
automat       CLI generator for models and controllers

Request Lifecycle

1

Bootstrap

public/index.php loads Composer, environment variables, core services, the router, and the route files.

2

Route Match

Router\Router delegates matching to AltoRouter and resolves the request to either a closure or a controller target.

3

Controller Dispatch

The controller instance is built through Core\Core::makeController(), which injects shared request and response objects.

4

Application Logic

Controllers orchestrate input, call models, and return either rendered views or JSON responses using a consistent API.

Routing Style

Routes are grouped by HTTP verb and should prefer direct controller targets over inline closures.

Router\Router::get('/api', [Controllers\ApiController::class, 'index']);
Router\Router::post('/api/articles', [Controllers\ArticleController::class, 'apiStore']);
Router\Router::put('/api/articles/[i:id]', [Controllers\ArticleController::class, 'apiUpdate']);
Router\Router::delete('/api/articles/[i:id]', [Controllers\ArticleController::class, 'apiDestroy']);

Why This Pattern

  • Improves consistency across the codebase.
  • Makes routes easier to read and document.
  • Supports controller-focused tests more naturally.
  • Creates a cleaner path for future middleware or DI improvements.

Core Services

Core\Request

Encapsulates body reading, JSON decoding, headers, request method, URI, and uploaded files.

Core\Response

Standardizes JSON output, status handling, and response termination.

Core\AuthService

Validates bearer tokens, enforces HS256, checks signatures, and verifies time-based claims.

Core\AppConfig

Reads environment variables and exposes helpers for debug mode, environment, and allowed CORS origins.

Models\DataModel

Provides lazy PDO access so the application does not connect to the database during bootstrap.

Controllers\Controller

Offers base rendering, redirect, request, response, and JSON helper behavior for all controllers.

Security and Operations

  • Set a strong non-placeholder JWT_SECRET.
  • Restrict CORS_ALLOWED_ORIGINS in production.
  • Do not commit secrets to the repository.
  • Validate MIME types and sizes for uploads server-side.
  • Use APP_DEBUG=false outside development.

Testing

A lightweight test runner is included for fast architecture-level checks.

php tests/run.php

The current suite covers JSON request decoding, JWT behavior, and router-to-controller dispatch.

Code Generation with Automat

automat scaffolds models and controllers aligned with the current architecture.

php automat list
php automat create:model Article
php automat create:controller ArticleController

Generated Capabilities

  • CRUD model methods: findAll, findById, create, update, delete
  • HTML actions: index, show, create, store, edit, update, destroy
  • API actions: apiIndex, apiShow, apiStore, apiUpdate, apiDestroy
  • Suggested routes using the direct controller-target style

Reference Pages

Use the architecture reference for a deeper contributor-oriented description of runtime flow, service responsibilities, conventions, and future extension points.

Open Architecture Reference