README

Lightweight PHP 8.4+ MVC framework for building simple web applications. Routing, controllers, middleware, views, and a small set of opt-in modules (migrations, authentication, background tasks) — with only PSR standard interfaces as runtime dependencies.

Requirements

• PHP 8.4 or later
• Composer 2.x

Getting started

Install

composer require aseguragonzalez/php-mvc

Create an app

vendor/bin/mvc create-app ./src/MyApp --name=MyApp --namespace=App\\MyApp

This generates the folder structure, a bootstrap file, and an mvc.config.json configuration file.

Enable optional modules

Each module is opt-in and can be activated through the CLI:

vendor/bin/mvc migrations:enable   # SQL migrations via timestamped scripts
vendor/bin/mvc auth:enable         # Authentication and authorization
vendor/bin/mvc bg-tasks:enable     # Background task processing

Once enabled, each module exposes additional CLI commands (e.g. migrations:create, migrations:run). See the CLI reference for the full list.

Documentation

Full documentation is available at aseguragonzalez.github.io/php-mvc.

Development

Dev container

All tooling (PHP, Composer, PHPStan, PHP-CS-Fixer, MkDocs) runs inside the dev container. Start it once from the project root:

devcontainer up --workspace-folder .

Then run any make target with:

devcontainer exec --workspace-folder . make <target>

Debugging: The Xdebug port is 9003. Configure your IDE or Xdebug client to connect to that port.

Make targets

All targets must be run inside the dev container — the required tools are not available on the host.

Documentation site

The documentation site uses MkDocs Material. Dependencies are installed automatically when the dev container is created.

devcontainer exec --workspace-folder . make docs-serve

Then open http://localhost:8001/php-mvc/ in your browser. The dev container forwards port 8001 automatically; if you use VS Code with the Dev Containers extension the browser opens on its own.

Built with

• PHPUnit ^12.5 — test suite
• PHPStan ^2.1 — static analysis at max level
• PHP-CS-Fixer ^3.95 — code style
• FakerPHP ^1.24 — test data generation
• vfsStream ^1.6 — virtual filesystem for tests

Contributing

Contributions are welcome. Please read CONTRIBUTING.md and CODE_OF_CONDUCT.md before opening a pull request.

Security

See SECURITY.md for the responsible disclosure process.

License

MIT License. Copyright (c) 2026 Alfonso Segura.