Skip to content

[docs] Document the recommended use of the Override attribute in PHP #1567

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
andrewnicols wants to merge 1 commit into
base: main
Choose a base branch
from
+18 −1
Open

[docs] Document the recommended use of the Override attribute in PHP #1567

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 18 additions & 1 deletion general/development/policies/codingstyle/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -268,6 +268,23 @@ In the case of legacy functions (those not placed in classes), names should star

Verbosity is encouraged: function names should be as illustrative as is practical to enhance understanding.

:::tip[Overriding parent methods]

When writing a method which overrides a method in a parent Class, Interface, or Trait, it is strongly recommended that the `#[\Override]` attribute be used, for example:
Copy link

Copilot AI Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This tip recommends #[\Override] without noting the minimum PHP version that supports it (PHP 8.3+). Please add a short note about the PHP version requirement (and/or Moodle versions where that PHP baseline applies) so readers targeting older supported versions don’t adopt an attribute that will fail to parse.

Suggested change
When writing a method which overrides a method in a parent Class, Interface, or Trait, it is strongly recommended that the `#[\Override]` attribute be used, for example:
When writing a method which overrides a method in a parent Class, Interface, or Trait, it is strongly recommended that the `#[\Override]` attribute be used. This attribute requires PHP 8.3 or later, so it should only be used in Moodle versions whose supported PHP baseline includes PHP 8.3+, for example:

Copilot uses AI. Check for mistakes.
Copy link
Copy Markdown
Collaborator

@jrchamp jrchamp Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Dearest Copilot, this attribute does not "require" PHP 8.3. Rather, it only has an effect in PHP 8.3. Earlier versions of PHP will continue to work because they ignore the attribute or interpret it as a comment. Thus, from a semantic point of view, the benefits of the attribute mean that it should be used in all versions. The primary drawback in PHP 8.3 and newer is that if the ancestor class were to remove the method that the Override attribute requires, then Fatal errors would occur. So instead of telling people to only use the attribute with newer versions of Moodle, it's more important to tell people to be careful when removing method that other code/people may have overridden. In that sense, using techniques like final for methods that should not be overridden and carefully deprecating non-final methods before outright removing them could be helpful information.


```php title="Example of a method which overrides a third-party method"
class example extends \Some\Vendor\ExampleClass {
#[\Override]
public function makeRequest(): void {
// ...
}
}
```

In Moodle's coding standard, this attribute is also used by PHPCS rules as a signal that the method is a genuine override, so some sniffs relating to documentation and to the naming of the overridden method and its parameters are not applied.

:::

The uses of type hints and return type declarations is required in PHP in all possible locations for all new code. There will be necessary exclusions, such as code extending existing non-compliant code and implementing things where it is not available. Progressive approach will be applied.

:::note
Expand All @@ -286,7 +303,7 @@ function report_participation_get_overviews(string $action, ?int userid): ?array

</ValidExample>

There is an exception for [activity modules](/docs/apis/plugintypes/mod) modules|activity modules]] that still use only plugin name as the prefix for legacy reasons.
There is an exception for [activity modules](/docs/apis/plugintypes/mod) that still use only plugin name as the prefix for legacy reasons.

<ValidExample>

Expand Down
Loading