This policy issue seeks to ban the use of an $options array, or similar loosely-typed set of configuration, for example:

    public static function get_fullname(

        stdClass $user,

        context $context = null,

        array $options = [],

    ): string;

In the above of usage:

• the value of $options must be described in phpdocs alone
• it is therefore not readily available to IDEs unless docs are correctly configured, and that feature is supported by the IDE and tooling
• it does not allow for readily-available defaults, or type hinting, or type checking, etc.

Prior to PHP 8.0 (Moodle 3.11) there was no sensible way to provide large numbers of options in PHP, short of a specifically designed class container, as a result without a loosely typed array like $options, a method like format_text could end up with a signature akin to:

   function format_text(

        ?string $text,

        string $format = FORMAT_MOODLE,

        ?context $context = null,

        bool $trusted = false,

        ?bool $clean = null,

        bool $filter = true,

        bool $para = true,

        bool $newlines = true,

        bool $overflowdiv = false,

        bool $blanktarget = false,

        bool $allowid = false,

    ): string;

The problem with the above is that, prior to PHP 8.0, there was no good way to specify only the last parameter. If you wanted to override the $allowid paramter, you would have to provide values for all of the others. For example:

    format_text(

        $text,

        FORMAT_MOODLE,

        $context,

        false,

        null,

        true,

        true,

        true,

        false,

        false,

        true,

    );

There was no way to specify only the $allowid parameter, and leave the others as their default values.

This was generally a bad situation. The only workaround would be if the author had allowed for a null value and handled the default within the method.

With the creation of named parameters, and their support in all supported versions of Moodle, this has changed. The above method can now be written as:

    format_text(

        text: $text,

        format: FORMAT_MOODLE,

        contet: $context,

        allowid: true,

    );

Or, if you prefer:

    format_text(

        $text,

        FORMAT_MOODLE,

        $context,

        allowid: true,

    );

Therefore I think it is time to ban the use of the $options array, and similar loosely-typed sets of configuration. Instead requiring first-class parameters for each option on the function signature, and recommending the use of named arguments to allow for the specification of only the options that are required.

I would propose that we make this change for all new code going forward, and also when refactoring existing code where possible.