aseguragonzalez/php-mvc

Lightweight PHP MVC Framework

v0.1.1 2026-05-28 22:41 UTC

Requires

• php: ^8.4
• psr/container: ^2.0
• psr/http-factory: ^1.1
• psr/http-message: ^2.0
• psr/http-server-handler: ^1.0
• psr/http-server-middleware: ^1.0
• psr/log: ^3.0

Requires (Dev)

• fakerphp/faker: ^1.24
• friendsofphp/php-cs-fixer: ^3.95
• mikey179/vfsstream: ^1.6
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^12.5

MIT

• Alfonso Segura

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.

Command	Description
make install	Install Composer dependencies
make test	Run the test suite
make cs	Check code style (dry-run)
make cs-fix	Auto-fix code style
make stan	Run static analysis (PHPStan max)
make check	Run cs + stan + test
make all	Run install + cs-fix + check
make docs-serve	Serve the documentation site on port 8001

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.