Search by

middag-io / framework

michaelmeneses

MIDDAG PHP Framework — DDD kernel, container, Inertia adapter, router, form engine, and domain abstractions

v1.20.4 2026-11-16 19:21 UTC

README

middag-io/framework

Symfony-grade DDD architecture that runs inside a Moodle or WordPress plugin, or standalone.

Documentation · Where it runs · Professional services · GitHub

CI License: Apache 2.0 PHP PHPStan

Packagist Version Packagist Downloads

About

middag-io/framework is a platform-agnostic PHP framework for building business domains that do not depend on their host. You write controllers, forms, queries and services against contracts, then run the exact same code inside a Moodle plugin, a WordPress plugin, or as a standalone app by swapping a thin adapter.

Your domain should not know, or care, where it runs.

Status: 1.x, pre-stable and unsupported; 2.0.0 is the first supported release and the cut to it is clean. From 2.0.0 the framework is part of the middag-php-* version family: a minor never breaks, and every library of the family is required with the same ^2.N (see API-STABILITY.md). License: Apache-2.0.

Why middag-io/framework?

Plugin code couples business logic straight to the host: $DB, $CFG and mform on Moodle, $wpdb on WordPress. That coupling is exactly what makes a plugin impossible to test without booting a full host, impossible to reuse on another platform, and fragile on every upgrade. This framework breaks the coupling, and gives you back four things:

  • Testable — exercise your domain against an in-memory database, with no host running. The suite proves it.
  • Portable — write the domain once; host it on Moodle, WordPress, or nothing at all, by changing one adapter.
  • Maintainable — the domain outlives platform upgrades and migrations, because it never depended on the platform.
  • Familiar — one coherent API over Symfony, PSR, Monolog and Inertia, not a new dialect to learn.

Built on giants

We did not reinvent the wheel. Under the hood it is Symfony (dependency injection, HTTP kernel, routing, Messenger, Validator), plain PSR contracts, Monolog and Inertia, wrapped in a single host-agnostic API. Less of our code to carry bugs, battle-tested foundations underneath.

Installation

Requires PHP ^8.3 (8.3, 8.4 and 8.5) and the intl, json, mbstring and pdo extensions; curl is recommended for the HTTP client. Every Symfony component it depends on is required as ^7.4 || ^8.1: PHP 8.3 resolves Symfony 7.4, PHP 8.4 and 8.5 can resolve 8.x. Runs standalone or behind a host adapter.

composer require middag-io/framework

Quick start

A controller that loads your domain and renders an Inertia page: attribute routing, a domain service injected by the container, and not a single host API in sight.

use Middag\Framework\Http\Controller\AbstractController;
use Middag\Framework\Http\Inertia\InertiaAdapter;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

final class CourseController extends AbstractController
{
    #[Route('/courses', name: 'courses')]
    public function index(CourseCatalog $catalog): Response
    {
        // CourseCatalog is your own domain service, injected by the container.
        // No $DB, no $CFG, no host — just your code, described in PHP.
        return InertiaAdapter::render('Courses/Index', [
            'courses' => $catalog->published(),
        ]);
    }
}

CourseCatalog is your service and index() stays plain PHP, so the exact same controller runs standalone, inside Moodle, or inside WordPress, by swapping the adapter.

And the proof of decoupling: the query layer runs with no host at all, over a plain PDO connection.

use Middag\Framework\Database\PdoConnectionAdapter;
use Middag\Framework\Persistence\Query\QueryBuilder;

$conn = new PdoConnectionAdapter(new PDO('sqlite::memory:')); // or a mysql:/pgsql: DSN

// The QueryBuilder is immutable. ::on() binds a connection, so the terminals execute.
$courses = QueryBuilder::on($conn, 'courses')
    ->where('published', true)   // equality shortcut
    ->orderBy('title')
    ->get();                     // array<int, array<string, mixed>>

What's inside

Generic plumbing, organised by concern (each concern owns its own Contract/):

Concern What it does
Kernel Symfony DI container booted from a BootstrapInterface, service auto-discovery, AbstractModule, AbstractFacade, and a per-instance WordPress-style HookManager.
Http A PSR-15 HTTP kernel built by HttpKernelFactory, StandaloneKernel, attribute routing (#[Route]), declarative auth (#[Auth] with rich CapabilityRequirement support), per-route middleware (#[Middleware]), AbstractController / AbstractApiController, and AbstractFormRequest.
Inertia Full Inertia v3 protocol: lazy (optional), deferred (defer), merge (merge / deepMerge), partial reloads and asset versioning.
Form AbstractForm over the FormValidatorInterface contract, a set of field types (text, select, date, file, and more), and an Inertia renderer.
Persistence An immutable QueryBuilder, an active-record Model, AbstractRepository / AbstractMapper, and Page pagination.
Database ConnectionAdapterInterface with a default PdoConnectionAdapter, a SQL dialect layer, and a schema builder with migrations.
Bus A command bus over Symfony Messenger (sync, plus async by transport routing), an InMemoryTransport, a Doctrine transport, and a CommandWorker that discards an undecodable message instead of dying on it.
Logging A Monolog-backed LoggerFactory per channel, with a RotatingStreamHandler.
Mail A MailerInterface port with Mail / Address / Attachment value objects (inline cid: embeds included). The OSS default NullMailer discards; adapters map a Mail onto email_to_user() / wp_mail().
Observability An ErrorReporterInterface port (NullErrorReporter default, SentryErrorReporter behind a composer suggest) plus a ProfileCollectorInterface sink that gives bus, hook and query events a single profiling timeline.
Shared / Exception DTOs, enums and utilities, plus a typed exception hierarchy mapped to HTTP status codes.

Full API reference, guides and examples live in the hub: https://docs.middag.dev/framework/explanation/overview.

Where it runs

Target How
Standalone Implement Middag\Framework\Kernel\Contract\BootstrapInterface, build the container with ContainerFactory::build(), build the HTTP kernel with HttpKernelFactory, and serve through StandaloneKernel.
Moodle The OSS middag-io/moodle adapter (MoodleBootstrap plus the bridge contracts).
WordPress The OSS middag-io/wordpress adapter (in build-out).

An adapter is a thin layer that implements the bridge contracts (BootstrapInterface, ConfigResolverInterface, ConnectionAdapterInterface, HostEventBridgeInterface, UserContextResolverInterface, TranslatorInterface, FormRendererInterface). The framework ships a default OSS implementation of each, so it runs standalone with no adapter at all.

Open source and MIDDAG

The framework, the Moodle and WordPress adapters, and middag-io/ui are open source under Apache-2.0: the generic plumbing, free, forever.

The governed domain infrastructure that is genuinely hard to get right — reliable event delivery, async jobs with retry and audit, an EAV query engine and multi-tenancy — is MIDDAG's proprietary product. It is built on top of this OSS and is opt-in, for when a domain outgrows the basics. The framework never imports the proprietary layer; the dependency only ever points downward.

Professional services

Adopting the framework, building a custom adapter, or migrating a legacy plugin to a testable domain? MIDDAG offers consulting and custom development. Reach us at email@middag.io or visit middag.io for more.

Development

composer test    # PHPUnit
composer check   # PHPStan (level 6) + PHP-CS-Fixer + Rector, all dry-run
composer fix     # auto-fix style and Rector (composer fix:all re-settles formatting afterwards)
composer lint         # parse every file on the local PHP (php -l), no Docker
composer lint:php83   # the same lint on a real PHP 8.3 (Docker); fails without Docker

CI runs the static checks, composer lint among them, on PHP 8.3, the floor, and the tests on 8.3, 8.4 and 8.5 with the platform pinned to 8.3.0. A highest job removes the pin, resolves the highest versions on 8.4 and 8.5 and fails unless Symfony resolved to 8.x.

Git hooks are wired automatically on install; the commit-msg hook enforces Conventional Commits, and releases are cut by release-please.

Help and status

Contributing

See CONTRIBUTING.md for the workflow, coding standards and quality pipeline. Please also read the CODE_OF_CONDUCT.md. Found a security issue? Follow SECURITY.md.

Building on the framework? API-STABILITY.md defines the @api public surface (what is covered and what is not), the version family from 2.0.0 (shared MAJOR.MINOR, fix-only patches, the same ^2.N for every library, the family window check on every PR) and links to Versioning and compatibility.

License

Licensed under the Apache License, Version 2.0. See LICENSE. Copyright 2026 MIDDAG.