Valhalla is a lightweight, opinionated PHP framework built for service-to-service communication, CLI scaffolding, JWT and API token auth, and local agent-style workers. No monolith. No boilerplate. Just the parts you need.
$composer global require asyassin10/valhalla-framework
$valhalla new project orders-service# scaffold a new service$cd orders-service$composer install# install dependencies$php -S 127.0.0.1:8080 -t public# start the dev server{
"ok": true,
"service": "orders",
"uptime_ms": 1284
}Valhalla focuses on the parts of a framework that matter for APIs, internal systems and small operational tools — and removes everything else.
Designed for small, focused services that do one thing well — not bloated monoliths.
Every route returns structured JSON by default. No view layer, no template engine to fight.
A minimal kernel with no hidden dependencies. Boots in milliseconds and stays out of your way.
Generate projects, controllers, middleware and services from a single binary you already trust.
First-class auth primitives with middleware-driven enforcement and zero-config defaults.
Talk to other Valhalla services with a typed client, retries, timeouts and tracing-ready headers.
Spin up long-running, MCP-style local agents for background tasks, scoring and summarization.
An opinionated layout that maps cleanly to how engineers actually think about services.
Valhalla ships as a single Composer package. Install it once globally, drop the binary on your PATH, and you're done.
Pull Valhalla into your global Composer bin so the CLI is available system-wide.
On macOS zsh, append the Composer bin directories so the valhalla command resolves.
Run the CLI without arguments to confirm Valhalla is wired up correctly.
Scaffold a fresh microservice and start building.
Already installed? Skip ahead to the CLI workflow or code examples.
$composer global require asyassin10/valhalla-framework# install Valhalla globallyComposer will pull the framework into your global vendor directory and link the valhalla binary.
The valhalla CLI scaffolds projects, generates components, runs migrations, builds containers, signs tokens and orchestrates local agents.
Bootstrap a service and pull in dependencies. Fresh projects ship without an ORM — install one when you need it.
$valhalla new project orders-service$valhalla installGenerate the boring parts so you can focus on business logic.
$valhalla make:controller OrdersController$valhalla make:middleware InternalAuth$valhalla make:service BillingServiceIssue tokens and audit your route table without leaving the terminal.
$valhalla routes:list$valhalla auth:generate 1 "Jane Doe"Install one driver — Eloquent or Doctrine — then run migrations and generate models.
$valhalla orm:install eloquent$valhalla orm:remove$valhalla make:model Order$valhalla make:migration create_orders_table$valhalla migrate$valhalla migrate:rollback$valhalla migrate:diffGenerate a Docker or Podman setup for your service in one command.
$valhalla install:docker$valhalla install:podman$valhalla build$valhalla up$valhalla logs$valhalla shell$valhalla downInstall, run and call long-running local TCP workers, MCP-style.
$valhalla agent:install summarizer 9501$valhalla agent:start summarizer$valhalla agent:call summarizer summarize$valhalla agent:stop summarizer$valhalla agent:list$valhalla agent:serveDay-2 commands for queues and operational work.
$valhalla queue:workRoute:: facade is the recommended style.Valhalla supports closure routes, controller routes, route groups, route parameters, and PHP 8 attribute routes — all in plain, readable PHP.
<?php
use Valhalla\Framework\Facades\Route;
use Valhalla\Framework\Core\Request;
use Valhalla\Framework\Core\Response;
use App\Controllers\OrdersController;
// Closure routes
Route::get('/health', fn () => Response::json([
'ok' => true,
'service' => 'orders',
]));
Route::get('/users/{id}', fn (Request $request) => Response::json([
'id' => $request->route('id'),
]));
// Controller routes
Route::post('/orders', [OrdersController::class, 'store']);
Route::get('/orders/{id}', [OrdersController::class, 'show']);A small surface area, intentionally chosen. The pieces that matter for service-oriented PHP — and clean APIs for everything else.
Closure-style or controller-bound routes, route groups with shared middleware, parameter constraints, and route-level naming for inspection.
Sign tokens from the CLI, validate them through middleware, and protect entire route groups with a single line. Works for both end-user and service auth.
A small HTTP client purpose-built for internal calls — base URLs, bearer tokens, retries, timeouts and structured JSON responses with one fluent API.
Install a local agent, expose actions, then call them from any service. Great for scoring, summarization, image analysis and other on-box tasks.
Valhalla ships with a pluggable ORM system. Install exactly one driver — Eloquent or Doctrine — and only that driver's directories appear in your project.
Active Record · illuminate/database
Install Eloquent for fluent, model-first development with classic up/down migrations.
$valhalla orm:install eloquent# wire up Eloquent$valhalla make:model Order$valhalla make:migration create_orders_table$valhalla migrate$valhalla migrate:rollback# undo the last batchData Mapper · doctrine/orm
Install Doctrine for entity-driven design with diff-based migrations generated from your metadata.
$valhalla orm:install doctrine# wire up Doctrine$valhalla make:model Invoice$valhalla migrate:diff# generate from entity metadata$valhalla migrate$valhalla migrate:rollbackGenerate a production-shaped container setup for your service in one command. Pick PHP version, database, Redis, queue workers and exposed port — Valhalla writes the rest.
$valhalla install:docker# scaffold a Docker stack$valhalla install:podman# or scaffold a Podman stack$valhalla build# build images$valhalla up# start the stack$valhalla logs# tail service logs$valhalla shell# open a shell in the app container$valhalla down# stop and clean updocker/DockerfileMulti-stage PHP imagedocker/docker-compose.ymlOr podman-compose.yml for Podmandocker/nginx/nginx.confProduction-ready vhostdocker/mysql/init.sqlGenerated when MySQL is selecteddocker/.dockerignoreSensible defaultsconfig/container.phpContainer settings exposed to the appThe generator targets either docker compose or podman compose, so the same project boots on either runtime without changes to your code.
Controllers, middleware and services live under src/. Routes, config and migrations get their own top-level homes. New engineers can read a Valhalla service in minutes — not hours.
src/Models appears only for Eloquent installs. src/Entities appears only for Doctrine installs. Fresh projects ship with neither.
orders-service/├─ src/ # domain & framework code│ ├─ Controllers/│ │ ├─ OrdersController.php│ │ └─ HealthController.php│ ├─ Middleware/│ │ ├─ InternalAuth.php│ │ └─ RequestId.php│ └─ Services/│ └─ BillingService.php├─ routes/│ └─ api.php├─ config/│ ├─ auth.php│ ├─ services.php│ ├─ logging.php│ ├─ agents.php│ └─ database.php├─ database/ # schema & migrations│ └─ migrations/├─ public/ # web entrypoint│ └─ index.php├─ composer.json└─ .env.exampleEach section is short, focused and shows real code. No 40-page tutorials, no detours.
Install the CLI, scaffold your first service and serve traffic in minutes.
The Route:: facade, attribute routes, groups, parameters and route inspection.
Issue JWTs from the CLI and protect routes with a single middleware.
Speak to internal services with retries, timeouts and bearer tokens.
Install, start and call long-running on-box PHP workers from any service.
Pluggable Eloquent or Doctrine — install one driver and run migrations.
Generate a Docker or Podman setup with PHP, MySQL/Postgres, Redis and queues.
Run focused tests against your services with a minimal harness.
Every first-party command, grouped by what they actually do for you.