meritum/virtus

Meritum HTTP API application scaffold

dev-main 2026-06-18 03:49 UTC

Requires

• php: ^8.4
• meritum/http: ^1.0

Requires (Dev)

• phpunit/phpunit: ^11.0

MIT

README

Virtus is a composer create-project scaffold for building HTTP APIs with the Meritum ecosystem. It ships a pre-wired meritum/http kernel with a clean structure ready to build on.

Requirements

• PHP 8.4+
• Composer

Getting Started

composer create-project meritum/virtus my-app
cd my-app

Copy .env.example to .env and adjust as needed:

APP_ENV=local
APP_DEBUG=true

Dev Environment

Virtus ships with a devenv.nix for devenv — a Nix-based developer environment that provides PHP and Composer without requiring a system install. It also defines a local web server process.

Prerequisites

1. Install Nix (the package manager, not the OS)
2. Install devenv

Usage

Enter the development shell:

devenv shell

This activates PHP 8.4, Composer, and vendor/bin on your PATH. Your .env file is loaded automatically.

From inside the shell, install dependencies:

composer install

Start the local web server (PHP built-in server on port 8000):

devenv up

The API is then available at http://localhost:8000.

Customising the environment

Open devenv.nix to add PHP extensions or services:

php = pkgs.php84.withExtensions ({ enabled, all }: enabled ++ [
    all.pdo_pgsql
    all.pdo_mysql
]);

# services.postgres = {
#   enable = true;
#   listen_addresses = "127.0.0.1";
# };
# services.redis.enable = true;

Uncomment the services you need — they start alongside the web server when you run devenv up.

Adding a Handler

Create a PSR-15 handler in src/Handler/:

namespace App\Handler;

use Laminas\Diactoros\Response\JsonResponse;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;

final class HomeHandler implements RequestHandlerInterface
{
    public function handle(ServerRequestInterface $request): ResponseInterface
    {
        return new JsonResponse(['message' => 'Hello, world!']);
    }
}

Register the handler and its route in AppModule::register():

use Meritum\Http\HttpKernelInterface;

public function register(KernelInterface $kernel): void
{
    assert($kernel instanceof HttpKernelInterface);

    $kernel->define(Handler\HomeHandler::class, fn() => new Handler\HomeHandler());

    $kernel->addRoute('GET', '/', Handler\HomeHandler::class);
}

Structure

www/index.php             Entry point
src/
  ModuleRepository.php    Register application modules
  AppModule.php           Register handlers, routes, and application config
tests/
devenv.nix                Dev environment

Testing

composer test

Further Reading

• meritum/http — HTTP kernel, routing, middleware
• georgeff/kernel — DI, modules, service tagging