Improve dependency injection guidance

[cameron1729]

Background

Existing DI documentation focuses heavily on accessing Moodle's DI container, which can blur the distinction between constructor injection and using the container as a service locator.

This distinction is becoming increasingly important as the core container sees wider adoption. Moodle needs clear guidance showing that classes should declare only their immediate dependencies, code to contracts, and remain unaware of the container. Container lookups should be restricted to composition roots or compatibility boundaries.

The Calendar API is a useful canonical example. It has used constructor injection since Moodle 3.3, before Moodle had a native DI container, and already contains a substantial graph of factories, mappers, policies, retrieval strategies, and output services. There is work in progress to migrate it to native DI - and the documentation here references that work.

Changes

This PR:

• Defines dependency injection separately from the DI container
• Recommends constructor injection as the normal approach
• Explains application boundaries and composition roots, including framework owned composition through routing
• Distinguishes runtime values from container-managed services
• Clarifies what autowiring can infer and when a container definition is required
• Explains why injecting the container creates a service locator
• Documents the related Moodle and Moodle Extra PHP CodeSniffer rules
• Uses the Calendar API as a substantial core example of composing a dependency graph from a small number of boundary lookups (NB: the examples used are based on ongoing work in MDL-89216)
• Updates the Clock API guidance to follow the same constructor-injection model.

Related work

• Calendar API migration to native DI container: MDL-89216
• Coding standard guidance: moodlehq/moodle-cs#228

Important

This PR documents Calendar APIs introduced by MDL-89216 and coding-standard rules introduced by moodlehq/moodle-cs#228. It must not be merged before those have landed.

Moodle main currently targets Moodle 5.3, scheduled for release on 5 October 2026. If MDL-89216 is integrated for Moodle 5.3, this PR should merge after its integration and before the 5.3 developer documentation is forked. If the issue moves to a later release, this PR should be held until the developer documentation targets the release which contains it.

[netlify]

✅ Deploy Preview for moodledevdocs ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	6aa705d
🔍 Latest deploy log	https://app.netlify.com/projects/moodledevdocs/deploys/6a5dc61acf9d340008dbbc35
😎 Deploy Preview	https://deploy-preview-1640--moodledevdocs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.