PHPackages                             asyassin10/valhalla-framework - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Framework](/categories/framework)
4. /
5. asyassin10/valhalla-framework

ActiveLibrary[Framework](/categories/framework)

asyassin10/valhalla-framework
=============================

Microservices-only PHP framework for lightweight API services.

1.0.8(1mo ago)7263MITPHPPHP ^8.2

Since Apr 25Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/Asyassin10/valhalla-framework)[ Packagist](https://packagist.org/packages/asyassin10/valhalla-framework)[ RSS](/packages/asyassin10-valhalla-framework/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (1)Dependencies (4)Versions (10)Used By (0)

 [![Valhalla Logo](./assets/valhalla-logo.png)](./assets/valhalla-logo.png)

Valhalla
========

[](#valhalla)

Valhalla is a microservices-first PHP framework for building lightweight JSON APIs, internal service endpoints, CLI-driven workflows, local agent-style workers, optional ORM-backed applications, and container-ready services.

It is designed for teams that want a small, focused foundation instead of a full-stack monolith. Valhalla keeps the surface area intentionally compact: routing, middleware, authentication, service-to-service HTTP calls, scaffolding, agents, optional ORM drivers, and one-command container generation.

Why Valhalla
------------

[](#why-valhalla)

- API-first architecture with JSON responses as the default
- Lightweight core with minimal abstraction overhead
- `Route::` facade with automatic attribute route discovery
- Optional ORM support with pluggable Eloquent or Doctrine drivers
- Container scaffolding for Docker and Podman
- CLI scaffolding for projects, controllers, middleware, services, models, and migrations
- JWT and API token authentication support
- Service-to-service HTTP client with retries and circuit-breaker support
- Local TCP-based agent workflow for task-style background services
- Simple structure that is easy to read, extend, and test

Requirements
------------

[](#requirements)

- PHP 8.2+
- Composer

Install Valhalla Globally
-------------------------

[](#install-valhalla-globally)

Install the Valhalla CLI globally with Composer:

```
composer global require asyassin10/valhalla-framework
```

Make sure Composer's global `bin` directory is on your `PATH`.

For `zsh` on macOS:

```
echo 'export PATH="$PATH:$HOME/.composer/vendor/bin:$HOME/.config/composer/vendor/bin"' >> ~/.zshrc
source ~/.zshrc
```

Verify the installation:

```
valhalla
```

Create a New Project
--------------------

[](#create-a-new-project)

Create a new service from anywhere:

```
valhalla new project orders-service
cd orders-service
composer install
cp .env.example .env
php -S 127.0.0.1:8080 -t public
```

Then open:

```
http://127.0.0.1:8080/health

```

You can also scaffold and install dependencies in one step:

```
valhalla new project orders-service --install
```

Generated projects now include:

- `src/Controllers`, `src/Middleware`, `src/Services`
- `database/migrations`
- `config/database.php`
- route, auth, logging, agents, and service config files

ORM-specific directories are created only when you install an ORM driver:

- `valhalla orm:install eloquent` creates `src/Models`
- `valhalla orm:install doctrine` creates `src/Entities`

Local Development In This Repository
------------------------------------

[](#local-development-in-this-repository)

If you are working on the framework itself:

```
composer install
cp .env.example .env
php -S 127.0.0.1:8080 -t public
```

Run the CLI locally from the repository root:

```
php bin/valhalla
```

Or:

```
./bin/valhalla
```

CLI Commands
------------

[](#cli-commands)

Valhalla ships with a project, ORM, container, and operations CLI.

```
new project            Create a new Valhalla API project.
make:controller        Generate a controller class.
make:middleware        Generate a middleware class.
make:service           Generate a service helper class.
install                Install Composer dependencies.
auth:generate          Generate a JWT for a sample or provided user.
routes:list            List registered routes from routes/api.php.
orm:install            Install an ORM driver (eloquent or doctrine).
orm:remove             Remove ORM configuration from the project.
migrate                Run ORM migrations.
migrate:rollback       Rollback the last ORM migration.
migrate:diff           Generate a Doctrine migration diff.
make:model             Generate an ORM model or entity.
make:migration         Generate an ORM migration.
install:docker         Generate a docker container setup.
install:podman         Generate a podman container setup.
up                     Start the configured container stack.
down                   Stop the configured container stack.
build                  Build the configured container stack.
logs                   Tail logs from the configured container stack.
shell                  Open a shell in the app container.
queue:work             Run the Valhalla queue worker loop.
agent:install          Register a new local Valhalla agent.
agent:start            Start a registered local agent in the background.
agent:stop             Stop a background Valhalla agent.
agent:call             Call a running local agent with a task.
agent:list             List installed agents.
agent:serve            Internal command used to boot an agent server process.

```

### Common Examples

[](#common-examples)

Generate a controller:

```
valhalla make:controller OrdersController
```

Generate middleware:

```
valhalla make:middleware InternalAuth
```

Generate a service helper:

```
valhalla make:service BillingService
```

List registered routes:

```
valhalla routes:list
```

Generate a JWT for testing:

```
valhalla auth:generate 1 "Jane Doe"
```

Install Eloquent ORM support:

```
valhalla orm:install eloquent
valhalla make:model Order
valhalla make:migration create_orders_table
valhalla migrate
```

Install Doctrine ORM support:

```
valhalla orm:install doctrine
valhalla make:model Invoice
valhalla migrate:diff
valhalla migrate
```

Generate Docker files:

```
valhalla install:docker
valhalla build
valhalla up
valhalla logs
valhalla shell
```

Generate Podman files:

```
valhalla install:podman
valhalla build
valhalla up
```

Routing
-------

[](#routing)

Valhalla is built around simple, readable route definitions.

```
use App\Controllers\OrdersController;
use Valhalla\Framework\Core\Request;
use Valhalla\Framework\Core\Response;
use Valhalla\Framework\Facades\Route;

Route::get('/health', fn () => Response::json([
    'ok' => true,
    'service' => 'orders',
]));

Route::get('/users/{id}', fn (Request $request) => Response::json([
    'id' => $request->route('id'),
]));

Route::post('/orders', [OrdersController::class, 'store']);
```

The `Route` facade is the recommended style because it gives clean editor autocomplete and avoids `$router` variable warnings in IDEs.

### Route Groups

[](#route-groups)

```
use App\Middleware\AuthMiddleware;
use Valhalla\Framework\Facades\Route;

Route::group('/internal', [AuthMiddleware::class], function (): void {
    Route::get('/status', fn () => ['ok' => true]);
});
```

### Controller Arrays

[](#controller-arrays)

```
use App\Controllers\UsersController;
use Valhalla\Framework\Facades\Route;

Route::get('/users', [UsersController::class, 'index']);
Route::get('/users/{id}', [UsersController::class, 'show']);
Route::post('/users', [UsersController::class, 'store']);
```

### Attribute Routes

[](#attribute-routes)

Controllers in `src/Controllers` can declare routes with PHP 8 attributes, and Valhalla loads them automatically when the app calls `loadRoutes(...)`.

```
use Valhalla\Framework\Core\Request;
use Valhalla\Framework\Core\Response;
use Valhalla\Framework\Routing\Attributes\Get;
use Valhalla\Framework\Routing\Attributes\Post;

final class UserController
{
    #[Get('/users')]
    public function index(Request $request): Response
    {
        return Response::json(['users' => []]);
    }

    #[Post('/users')]
    public function store(Request $request): Response
    {
        return Response::json(['created' => true]);
    }
}
```

Default bootstrap stays simple:

```
$app->loadRoutes(dirname(__DIR__).'/routes/api.php');
```

If you need manual control, the low-level method still exists:

```
$app->loadAttributeRoutes(UserController::class);
```

Authentication
--------------

[](#authentication)

Valhalla supports:

- JWT bearer authentication
- Static API tokens for internal service communication

Generate a test token:

```
valhalla auth:generate 1 "Jane Doe"
```

Protect a route with middleware:

```
use Valhalla\Framework\Auth\Auth;
use Valhalla\Framework\Core\Response;
use Valhalla\Framework\Facades\Route;
use Valhalla\Framework\Middleware\AuthMiddleware;

Route::get('/secure', fn () => Response::json([
    'authenticated' => true,
    'user' => Auth::user(),
]), [AuthMiddleware::class]);
```

Pluggable ORM System
--------------------

[](#pluggable-orm-system)

Valhalla supports one optional ORM driver per project. Install either Eloquent or Doctrine, never both.

### ORM Config

[](#orm-config)

`config/orm.php` is the source of truth:

```
return [
    'driver' => 'eloquent',
];
```

or:

```
return [
    'driver' => 'doctrine',
];
```

If `config/orm.php` does not exist, ORM support is skipped silently during application boot.

### Eloquent Driver

[](#eloquent-driver)

Install it with:

```
valhalla orm:install eloquent
```

This command:

- runs `composer require illuminate/database`
- creates `src/Models/`
- creates `database/migrations/`
- writes `config/orm.php`
- ensures `config/database.php` exists

Generate a model:

```
valhalla make:model Order
```

This creates a model under `src/Models/` extending `Illuminate\Database\Eloquent\Model` with `protected array $guarded = [];`.

Generate a migration:

```
valhalla make:migration create_orders_table
```

Run migrations:

```
valhalla migrate
```

Rollback the last migration:

```
valhalla migrate:rollback
```

### Doctrine Driver

[](#doctrine-driver)

Install it with:

```
valhalla orm:install doctrine
```

This command:

- runs `composer require doctrine/orm doctrine/migrations`
- creates `src/Entities/`
- creates `database/migrations/`
- writes `config/orm.php`
- ensures `config/database.php` exists

Generate an entity:

```
valhalla make:model Invoice
```

Doctrine entities are generated in `src/Entities/` with mapping attributes and a `getId()` getter. After adding fields, generate a diff migration with:

```
valhalla migrate:diff
```

Apply migrations:

```
valhalla migrate
```

Rollback to the previous Doctrine migration:

```
valhalla migrate:rollback
```

Remove ORM config:

```
valhalla orm:remove
```

This removes `config/orm.php` and tells you to remove the Composer package manually.

### Database Config

[](#database-config)

Valhalla reads database credentials from `config/database.php` and `.env` values such as:

```
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=valhalla
DB_USERNAME=valhalla
DB_PASSWORD=secret

```

Docker And Podman Setup
-----------------------

[](#docker-and-podman-setup)

Valhalla can generate a complete container setup with a single command.

### Install Docker Files

[](#install-docker-files)

```
valhalla install:docker
```

### Install Podman Files

[](#install-podman-files)

```
valhalla install:podman
```

Both commands ask for:

- PHP version: `8.2` or `8.3`
- Database: `mysql`, `postgres`, or `none`
- Database name, username, and password when a database is enabled
- Cache: `redis` or `none`
- Queue worker: `yes` or `no`
- HTTP port to expose

Generated files are placed under `docker/`:

- `docker/Dockerfile`
- `docker/docker-compose.yml` or `docker/podman-compose.yml`
- `docker/nginx/nginx.conf`
- `docker/mysql/init.sql` when MySQL is selected
- `docker/.dockerignore`

Valhalla also writes `config/container.php`:

```
return [
    'runtime' => 'docker',
];
```

or:

```
return [
    'runtime' => 'podman',
];
```

### Container Runtime Commands

[](#container-runtime-commands)

Once a runtime is installed, use:

```
valhalla build
valhalla up
valhalla logs
valhalla shell
valhalla down
```

These commands automatically read `config/container.php` to choose Docker or Podman.

### Queue Worker Container

[](#queue-worker-container)

If you choose a queue worker during container setup, Valhalla creates a worker service that runs:

```
php bin/valhalla queue:work
```

Service-to-Service Calls
------------------------

[](#service-to-service-calls)

Valhalla includes a JSON-oriented HTTP client wrapper for internal services.

```
use Valhalla\Framework\Services\ServiceClient;

$client = new ServiceClient($app->config());

$result = $client->json(
    'billing',
    'POST',
    'https://billing.internal/payments',
    ['invoice_id' => 99]
);
```

The service client supports retry settings and circuit-breaker configuration through `config/services.php`.

Local Agents
------------

[](#local-agents)

Valhalla includes an MVP local agent system for task-based workers over newline-delimited JSON and TCP.

Install and start an agent:

```
valhalla agent:install summarizer 9501
valhalla agent:start summarizer
valhalla agent:list
```

Call an agent:

```
valhalla agent:call summarizer summarize
```

This is useful for internal automation, background jobs, or local task-oriented services.

Project Structure
-----------------

[](#project-structure)

```
bin/                     CLI entrypoint
config/                  Framework and application configuration
database/                Migration files for ORM-backed apps
docs/                    Documentation guides
docker/                  Generated Docker or Podman files
examples/basic-service/  Sample Valhalla service
public/                  HTTP entrypoint
routes/                  Route definitions
src/                     Framework source code and app classes
tests/                   PHPUnit tests

```

Documentation
-------------

[](#documentation)

Detailed guides are available in the `docs/` directory:

- [Installation](./docs/installation.md)
- [Routing](./docs/routing.md)
- [Authentication](./docs/auth.md)
- [Agents](./docs/agents.md)
- [CLI](./docs/cli.md)
- [Services](./docs/services.md)
- [Extending Valhalla](./docs/extending.md)
- [Testing](./docs/testing.md)

Example Service
---------------

[](#example-service)

A runnable example is included in:

```
examples/basic-service

```

This example shows the expected project structure and gives you a starting point for your own services.

Testing
-------

[](#testing)

Run the test suite from the repository root:

```
composer test
```

Roadmap Direction
-----------------

[](#roadmap-direction)

Valhalla is a strong fit for:

- internal APIs
- microservice backends
- service orchestration layers
- agent-like local workers
- ORM-backed services with optional Eloquent or Doctrine integration
- containerized API services with Docker or Podman

###  Health Score

45

—

FairBetter than 91% of packages

Maintenance92

Actively maintained with recent releases

Popularity15

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity52

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 63.6% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

9

Last Release

39d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/79702243?v=4)[Yassine Ait sidi brahim](/maintainers/Asyassin10)[@Asyassin10](https://github.com/Asyassin10)

---

Top Contributors

[![zack965](https://avatars.githubusercontent.com/u/67732045?v=4)](https://github.com/zack965 "zack965 (14 commits)")[![Asyassin10](https://avatars.githubusercontent.com/u/79702243?v=4)](https://github.com/Asyassin10 "Asyassin10 (8 commits)")

###  Code Quality

TestsPHPUnit

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/asyassin10-valhalla-framework/health.svg)

```
[![Health](https://phpackages.com/badges/asyassin10-valhalla-framework/health.svg)](https://phpackages.com/packages/asyassin10-valhalla-framework)
```

###  Alternatives

[laravel/framework

The Laravel Framework.

34.7k532.1M19.2k](/packages/laravel-framework)[tempest/framework

The PHP framework that gets out of your way.

2.2k31.1k11](/packages/tempest-framework)[craftcms/cms

Craft CMS

3.6k3.6M2.9k](/packages/craftcms-cms)[pimcore/pimcore

Content & Product Management Framework (CMS/PIM/E-Commerce)

3.8k3.8M444](/packages/pimcore-pimcore)[shopware/platform

The Shopware e-commerce core

3.4k1.5M3](/packages/shopware-platform)[neuron-core/neuron-ai

The PHP Agentic Framework.

1.9k496.1k32](/packages/neuron-core-neuron-ai)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)