Filter subplugins

Filters are used to select the Moodle users that are eligible to enter or transition between workflow steps. Each filter contributes a SQL WHERE clause fragment that is combined with all other active filters via a logical AND to produce the final user selection query. An additional PHP-based post-filtering stage is available for use cases that cannot be expressed in SQL.

Filters are implemented as small subplugins and can therefore be easily extended by your own institution-specific filters.

Example filter subplugin implementations

You can find many examples of filter subplugins directly within filter/.

Overview

Overview reduced for clarity

For clarity, the following overview diagram is reduced to the most important classes and members. Therefore, some details like methods, parameters, or members are omitted. Please refer to the plugin source code for a complete reference.

classDiagram
    direction TB

    %% Main classes
    class step_subplugin {
        <<abstract>>
        #id: int
        #step: step

        +get_instance_id()$ int
        +get_step() step
        +get_instance_title() string
        +get_instance_details() string
        +is_valid() bool
    }

    class userdeletefilter {
        <<abstract>>

        +get_instance_by_id(instanceid: int)$ self
        +create_instance(step: step, pluginname: string, settings: array)$ self
        +delete() void
        +get_plugin_type()$ subplugin_type
        +get_icon_class()$ string
    }

    class userdeletefilter_myfoo {
        +get_plugin_name()$ string
        +instance_setting_descriptors()$ array
        +user_records_filter_clause() userfilter_clause
        +user_records_postfilter(userids: int[]) int[]
    }

    %% Supporting classes
    class subplugin_instance_settings {
        <<trait>>

        +get_all_instance_settings() array
        +get_instance_setting(key: string) mixed
        +set_instance_setting(key: string, value: mixed) void
        +load_default_instance_settings(overrides: array) void
        +validate_instance_settings_data(data: array) array
    }

    class userfilter_clause {
        +sql: string
        +params: array
    }

    %% Relationships
    userdeletefilter_myfoo --|> userdeletefilter
    userdeletefilter_myfoo --> userfilter_clause
    userdeletefilter --|> step_subplugin
    step_subplugin ..> subplugin_instance_settings

    %% Style
    style step fill:#dedede,stroke:#666666
    style workflow fill:#dedede,stroke:#666666
    style userfilter_clause fill:#dedede,stroke:#666666
    style subplugin_instance_settings fill:#dedede,stroke:#666666
    style step_subplugin fill:#dedede,stroke:#666666
    style userdeletefilter fill:#dedede,stroke:#666666

Hold "Shift" to enable pan & zoom

PHPDocs are the ground source of truth

Please refer to the PHPDocs in the source code as the ground source of truth for detailed information regarding the implementation of these methods and their expected behavior.

Implementation

All filter subplugins must use the userdeletefilter frankenstyle plugin type and extend the abstract \tool_userautodelete\userdeletefilter base class.

Filtering is possible in two stages that are described in detail below:

SQL-based filtering (preferred)
PHP-based post-filtering

At a minimum, any filter subplugin must implement the following methods:

Of course you can also override other methods like get_instance_details(): string or get_icon_class(): string to further customize the behavior of your filter subplugin and how it displays within the UI.

SQL-based filtering

Every filter must implement user_records_filter_clause() to select target users from the Moodle database. The user_records_filter_clause() method must return a userfilter_clause object that contains a SQL WHERE clause fragment and the associated named parameters. All references to user table columns must use the u table alias (e.g., u.lastaccess). All active filter clauses are joined with a SQL AND operator at the time of evaluation.

SQL parameter names are automatically prefixed

You do not have to prefix your SQL parameter names in any way, as the core plugin will automatically prefix them uniquely for you at the time of evaluation.

Post-filtering

For use cases that cannot be expressed as SQL, such as remote API lookups, multi-system aggregations, or any logic that depends on data outside the Moodle database, filters can optionally implement a second, PHP-based stage by overriding user_records_postfilter().

This method is called after user_records_filter_clause() has already narrowed the candidate set. It receives all surviving user IDs in a single batch, so implementations can perform efficient bulk lookups instead of one call per user. Return the subset of $userids that passes this filter.

By default, the user_records_postfilter() method returns the input unchanged so that the filter has no effect unless explicitly implemented.

Prefer SQL filtering when possible

The SQL stage runs as a single database query and scales well. Reserve user_records_postfilter() for logic that genuinely cannot be expressed in SQL, since every PHP-based check adds overhead proportional to the number of candidate users.