Search by

middag-io / wordpress

michaelmeneses

MIDDAG WordPress adapter — persistence, REST, hooks, cron, Inertia frontend, and email for WordPress plugins

v1.16.0 2026-11-16 20:42 UTC

README

CI License: Apache 2.0 PHP

MIDDAG WordPress adapter — persistence, three routing surfaces (REST / admin / public rewrite), hooks, cron, Inertia frontend, and email implementations of the middag-io/framework contracts for WordPress.

Documentation: Reference — WordPress Adapter on docs.middag.dev.

What this package is

middag-io/wordpress is the WordPress host adapter for the MIDDAG framework. It provides the WordPress-side implementations of the framework's adapter contracts: $wpdb connection and SQL dialect, REST controllers, hooks, wp-cron, config and user context, translation, Inertia frontend glue, wp_mail email, and native post/user persistence.

It binds the framework to a WordPress site. A WordPress plugin provides the composition root that wires it in.

What it does not include

  • No product features or governed domain capabilities (item storage, query engine, audit and activity feeds, payments, CRM and similar).
  • No dependency on a MIDDAG package other than the OSS middag-io/framework and middag-io/ui. The AdapterPluginIsolationTest guard test (part of composer test) allows only the OSS MIDDAG namespaces in src/.
  • No bearer-token or JWT code: a consumer that accepts tokens injects its own RequestAuthenticatorInterface.
  • No bundled WordPress plugin. You wire the adapter into your own plugin.

Requirements

Item Supported
PHP ^8.3: 8.3, 8.4 and 8.5, with ext-json
Symfony ^7.4 || ^8.1 for every Symfony component it requires. PHP 8.3 resolves Symfony 7.4; PHP 8.4 and 8.5 can resolve 8.x
middag-io/framework ^1.20 on the 1.x line (it brings middag-io/ui)
WordPress 7.0 and 7.1 (the latest major and the previous one)

CI runs the test suite on PHP 8.3, 8.4 and 8.5 at the lowest platform, a highest job on PHP 8.4 and 8.5 that asserts the Symfony 8 major, PHPStan against the WordPress 7.0 and 7.1 stubs, and the integration suite against a real WordPress 7.0 and 7.1 (the newest patch release of each) on MySQL 8.4. The platform rules are on Platform.

Installation

composer require middag-io/wordpress

This pulls middag-io/framework automatically, which in turn pulls middag-io/ui — the framework's frontend toolkit that backs this adapter's Inertia frontend glue.

Host integration

A WordPress plugin owns the composition root that wires the adapter in. The adapter ships an abstract kernel that formalizes it: subclass Middag\WordPress\Runtime\Kernel, provide the singleton storage and the compiled container (see the class docblock for the two-method contract), and call YourKernel::init() on plugins_loaded. Boot wires HookRegistrar and CronRegistrar (init, priority 5) and RestRouteRegistrar (rest_api_init) whenever your container binds them — everything product-specific goes in your onBoot() override. The kernel holds no static state; the singleton lives on YOUR subclass, so two plugins built on the adapter never share a kernel in one request.

What the host must still do at boot:

  • Inject the component identity. Build new WpComponentContext($componentName, $assetVersion, $basePath) once and bind it in your own container as the framework HostComponentContextInterface, so the services that need it (the REST, admin and public routing registrars, CronRegistrar, InertiaAdapter, EmailSender) receive it by injection. Do not register it with the framework's HostContext::set(): that slot is one per PHP process, and with several plugins in one request the last plugin to boot would win.

  • Pass your own names. Every adapter default uses the neutral middaglib marker, which names no product. Bind the classes with your plugin's own values:

    Class Default Constructor argument
    WpConfigResolver MIDDAGLIB_ / middaglib_ $envPrefix, $optionPrefix
    WpHostEventBridge hook prefix middaglib/ $hookPrefix
    WpHookfileLoader filter middaglib_hookfiles, file middaglib_hooks.php $filterName, $hookfileName
    WpTranslator text domain middaglib $defaultDomain
    CacheSupportPsr16 wp_cache group middaglib_{area} $groupPrefix
    DiagnosticsRegistry filter middaglib_diagnostics $filterName
    DoctorCommandRegistrar WP-CLI root middaglib (wp middaglib doctor) $root

    $hookfileName comes after $logger, so set it with a named argument: new WpHookfileLoader(filterName: 'acme_hookfiles', hookfileName: 'acme_hooks.php').

REST routes declared with #[Auth] require login by default. Every capability an #[Auth] lists must pass user_can() for the user the injected RequestAuthenticatorInterface resolved (a token user included), with the instanceId as the object id of a meta capability. Grant your plugin's capabilities to the roles that need them, administrators included. The check fails closed: a resolved user with ID 0 gets 401, an instanceid option that is not a positive integer gets 403, and a throw while the requirements are resolved is logged and gets 403, not 500.

See WP-002, Configuration & Identity and Routing Surfaces for the details.

Logging needs no priming: the adapter's operational sites (cron dispatch, email send/render) resolve their PSR-3 logger per call through Middag\WordPress\Support\LogSupport::resolve($container) — an explicit Psr\Log\LoggerInterface binding wins, then the framework's channel LoggerFactory, then the error_log() fallback.

Boot diagnostics

Middag\WordPress\Diagnostics answers "did my package boot?" from the command line. Each package declares a PackageProbe (name, version, kernel class, optional entry class and extra checks) on a DiagnosticsRegistry from its main plugin file, before the kernel boots. The registry rides on a WordPress filter, so every plugin that shares the filter name meets in one report. DoctorCommandRegistrar adds wp <root> doctor, which prints a BootReport (autoloader resolved and from which file, kernel booted, version, the package's own checks). It exits 1 when a check fails or an expected package never registered (--expect=a,b) and 0 otherwise; --strict also fails on warnings and --format=json prints one JSON document.

$registry = new DiagnosticsRegistry('acme_diagnostics');
$registry->register(new PackageProbe('acme-shop', ACME_SHOP_VERSION, AcmeShopKernel::class));
(new DoctorCommandRegistrar(new DoctorCommand($registry, ['acme-shop']), 'acme'))->register();

A gate should pass the full package list with --expect (for example wp acme doctor --expect=acme-shop,acme-quotes). The constructor list only runs when the package that registered the command loaded, so it cannot catch that package's own absence. A package whose bootstrap chooses between autoloaders passes the chosen file as PackageProbe::$autoloaderPath, and the autoload check reports it.

The built-in checks prove boot, not render. A package can add a DiagnosticCheckInterface (or a CallbackCheck) with CheckScope::Render, for example "the admin page still emits its HTML shell and the core script bundles". Until one runs, the report states that it covers boot only.

Development

git clone https://github.com/middag-io/middag-php-wordpress
cd middag-php-wordpress
composer install

Run the quality gates and the test suite:

composer check   # PHP-CS-Fixer + Rector (dry-run) + PHPStan
composer test    # PHPUnit (includes the boundary and architecture guards)

The integration suite (tests/Integration) runs on a real WordPress and a real MySQL database; see tests/Integration/README.md.

composer.json pins config.platform.php to 8.3.0, so Composer resolves the lowest PHP of the range locally. composer.lock is gitignored, like a typical library. Git hooks are configured automatically via post-install-cmd; the commit-msg hook enforces Conventional Commits. See CONTRIBUTING.md for the contributor setup.

Releases

Releases are managed by release-please. The package is on 1.x, which is pre-stable and unsupported; from 2.0.0 it joins the middag-php-* version family. See API-STABILITY.md and Versioning and compatibility.

Help and status

License

Licensed under the Apache License 2.0. See NOTICE for attribution.