middag-io / wordpress
MIDDAG WordPress adapter — persistence, REST, hooks, cron, Inertia frontend, and email for WordPress plugins
Requires
- php: ^8.3
- ext-json: *
- middag-io/framework: ^1.20.4
- nyholm/psr7: ^1.8
- psr/container: ^2.0
- psr/log: ^3.0
- symfony/dependency-injection: ^7.4 || ^8.1
- symfony/http-foundation: ^7.4 || ^8.1
- symfony/psr-http-message-bridge: ^7.4 || ^8.1
- symfony/routing: ^7.4 || ^8.1
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.0
- php-stubs/wordpress-stubs: ^7.0
- phpstan/phpstan: ^2.0
- phpunit/phpunit: ^11.0
- rector/rector: 2.8.4
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-17 18:02:29 UTC
README
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/frameworkandmiddag-io/ui. TheAdapterPluginIsolationTestguard test (part ofcomposer test) allows only the OSS MIDDAG namespaces insrc/. - 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 frameworkHostComponentContextInterface, 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'sHostContext::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
middaglibmarker, which names no product. Bind the classes with your plugin's own values:Class Default Constructor argument WpConfigResolverMIDDAGLIB_/middaglib_$envPrefix,$optionPrefixWpHostEventBridgehook prefix middaglib/$hookPrefixWpHookfileLoaderfilter middaglib_hookfiles, filemiddaglib_hooks.php$filterName,$hookfileNameWpTranslatortext domain middaglib$defaultDomainCacheSupportPsr16wp_cachegroupmiddaglib_{area}$groupPrefixDiagnosticsRegistryfilter middaglib_diagnostics$filterNameDoctorCommandRegistrarWP-CLI root middaglib(wp middaglib doctor)$root$hookfileNamecomes 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
- Status: the
1.xline is pre-stable and unsupported; support starts at2.0.0. See Versioning and compatibility. - Documentation: Reference — WordPress Adapter on docs.middag.dev.
- Questions and bugs: GitHub issues.
- Security reports: see
SECURITY.md. Do not open a public issue. - Changes:
CHANGELOG.md.
License
Licensed under the Apache License 2.0. See NOTICE for
attribution.