Skip to content

Reference — Moodle Adapter ​

Implementation reference for middag-io/moodle (middag-php-moodle), the OSS adapter that plugs Moodle into the framework's ports. This page is the entry point of the adapter: what it is, what it needs, where its public surface is listed, then the reference pages grouped by topic (the sidebar uses the same clustering). Pages marked downstream document mechanisms that live in proprietary packages built on the adapter, not in the adapter itself.

Status: in progress

This page states the 2.x line of the library family. Support starts at 2.0.0; earlier releases are pre-stable and unsupported. One part is still being written: the generated reference of the @api surface (see Public surface).

What it is and who it is for ​

  • A library, not a Moodle plugin. It implements the framework's ports with Moodle APIs: bootstrap, configuration, user context, translation, the database connection, the maintenance gate and the host event bridge (Adapter Port Catalog, Moodle column).
  • It ships no composition root. A Moodle plugin of the consumer (a local_* or mod_* plugin, for example) builds the container and boots the kernel.
  • It carries no product feature and imports no proprietary MIDDAG code (Boundary & Whitelist).
  • For developers of a Moodle plugin built on middag-io/framework, and for developers who maintain the adapter itself.

Requirements and install ​

ItemValue
Packagemiddag-io/moodle (middag-php-moodle), Apache-2.0
PHP^8.3: 8.3, 8.4 and 8.5, within the PHP versions the Moodle version supports; with the json extension
Symfony^7.4 || ^8.1 for every Symfony component it requires (contracts and polyfills keep their own ranges)
Sibling librariesmiddag-io/framework and middag-io/ui, on the family MAJOR (^2.0 on 2.x)
Moodle4.5 (PHP 8.3), 5.1, 5.2 and 5.3 (PHP 8.3 and 8.4); 5.0 as best effort, with no support promise
Database enginesPostgreSQL, MySQL and MariaDB, as supported by the Moodle version; SQL Server is not tested and Oracle is not tested yet
bash
composer require middag-io/moodle

The require pulls middag-io/framework and middag-io/ui. The adapter ships no container builder: the consumer plugin registers its own at boot with Runtime\ContainerFactory::setBuilder(), a closure that receives the Runtime\Kernel and the Http\Contract\RouterInterface router and returns the compiled Symfony ContainerBuilder. When the kernel asks for the container and no builder is registered, ContainerFactory throws a RuntimeException. Moodle 4.5 runs up to PHP 8.3, so a plugin that ships its vendor/ to a Moodle 4.5 site resolves it on PHP 8.3: a vendor/ resolved on PHP 8.4 or later installs Symfony 8.x, which PHP 8.3 cannot run.

The platform rules behind these values are in Platform and Versioning and compatibility. Moodle bundles some namespaces that the adapter's dependency tree also uses: see Shared-Namespace Dependencies.

Public surface ​

Support covers the types tagged @api only (Supported surface). Every type in src/ carries exactly one of @api or @internal; a type with neither is internal. API-STABILITY.md in the repository lists the public surface. All names below are relative to the Middag\Moodle\ namespace.

Area@api types
Domain modelDomain\* entities, DTOs and enums for courses, users, enrolments, groups, roles, contexts, grades, completion, calendar, messages, files, custom fields, events, backup and the platform, plus Domain\Task\Enum\TaskRunState; the domain Contract\ interfaces (the *ServiceInterface types, FileAreaHandlerInterface and BackupStepsProviderInterface). Domain\Platform\PluginDto and the Domain\Task\*Dto types (AdhocTaskDto, ScheduledTaskDto, RunningTaskDto, TaskSummaryDto), which @api services return. The concrete *Service classes are @internal
Settings and definitionsSettings\* (admin setting types and Settings\SettingsResolver) and Definition\* (the builders that statics generation turns into db/*.php, with their Contract/ interface)
Moodle API wrappersSupport\Moodle (the façade) and the public Support\* wrappers, one per Moodle API: course, user, enrolment, capability, context, cache, config, file, grade, task, lock, session, URL, output and the others in the API coverage; the bridges Support\DiBridgeSupport (DI bridge) and Support\RouterBridgeSupport (routing bridge)
Security and privacySecurity\Contract\* (authentication, authorization, capability), the Security\ValueObject\Capability and Security\ValueObject\Sesskey value objects, the Security\Enum\CapabilityRisk and Security\Enum\CapabilityType enums and the Security\Attribute\Sesskey attribute; Privacy\Contract\* and Privacy\PrivacyProvider
HTTP, output and servicesHttp\Contract\MoodleControllerInterface, Http\Contract\RouterInterface, Output\Contract\ViewAdapterInterface, Output\MoodleView, Output\MoodleRenderer, the Output\Table helpers and WebService\AbstractExternal
FormsForm\DraftFileValueMapper, which maps the uploadToken of a middag-io/ui FileValue to a Moodle draft area and back. The Form\Mform* field mapper and renderer are @internal
ExceptionsException\MoodleAdapterException, Exception\MoodleConfigurationException, Exception\MoodleTransportException and Exception\MoodleVersionException
Other host servicesMail\MoodleMailer, Filesystem\MoodledataFilesystem, Hook\AbstractExtendExtensions, Persistence\UpgradeHelper, Shared\Enum\TextFormat, Shared\Util\Debug and Shared\Util\Environment
Composition rootThe concretes a consumer names when it wires the kernel (next table)

The composition-root concretes are public because a consumer must name them when it builds the container, not because their shape is a contract. Type your own code against the framework contract each one implements.

Concrete (@api)Role at boot
Runtime\Kernel, Runtime\ContainerFactoryBoot the kernel and register the container builder
Runtime\MoodleHostContext, Runtime\MoodleComponentNameResolver, Runtime\Loader\FacadeLoader, Runtime\Loader\MoodleHookfileLoaderHost context, component-name resolution, the façade loader and hookfile discovery at boot
Config\ComponentContext, Settings\SettingsResolverPlugin component and settings resolution
Bus\MoodleUserContext, Bus\MoodleHostEventBridge, Bus\MoodleAdhocTransportUser context, host event bridge and the ad hoc task transport
Logging\MoodleLogger, Logging\MoodleActorResolver, Logging\MoodleOriginResolverLogging port
Translation\MoodleTranslatorTranslation port
Database\Schema\XmldbSchemaAdapter, Persistence\VersionTracker, Persistence\Query\SqlGeneratorSchema, version tracking and SQL generation
Http\Routing\PluginAwareUrlGeneratorNamed only to exclude it from autowiring; do not extend or type-hint it

What stays internal is the wiring a consumer never names: the concrete Security\Authentication, Security\Authorizer and Security\Capability (depend on the Security\Contract\* interfaces) and Security\Enum\PermissionType, the database connection adapter and SQL dialect, the config resolver, the maintenance gate, the bootstrap, Http\Routing\MoodleRouter (depend on Http\Contract\RouterInterface) and the convention helpers in Support (CrudConventionResolver and TaskDefinitionBuilder). The framework contracts the adapter implements are in the Adapter Port Catalog.

In progress: the generated reference of the @api surface, with signatures and docblocks, is not published yet (Documentation publication). The reference pages below describe the adapter's mechanisms.

Changelog, decisions and help ​

  • CHANGELOG.md records every release; Releases carry the tags.
  • release-please cuts every release from Conventional Commits; there are no manual tags. The adapter shares MAJOR.MINOR with the rest of the family: a family MINOR or MAJOR goes out in every library, and a PATCH carries fixes only (Lifecycle).
  • The decision records behind these pages live in middag-php-moodle/docs/decisions.
  • Questions and bugs: issues of middag-php-moodle. Security reports: SECURITY.md; do not open a public issue for a vulnerability.

Boundary & Coverage ​

DI & Events ​

Routing & Navigation ​

Config & Cache ​

External Services & Data Migration ​

Frontend & Codegen ​

Related framework pages: Adapter Port Catalog (the Moodle column, including the transaction mapping) and Module Layout Convention.

MIDDAG © 2015-2026