Moodle Cohort Memberships Never Expire. Here's How We Make Them Lapse After a Year

Root cause

Why Moodle cohort memberships never expire

A cohort membership is a row in mdl_cohort_members. The row records who, which cohort, and when — the timeadded column — and then nothing in core ever reads that timestamp again for expiry purposes. Memberships are permanent until something removes them by hand.

The enrolment side is where people expect the fix to live, and it deliberately isn't there. Cohort sync enrolment (enrol_cohort) has no per-user end date and does not implement process_expirations(). That's a design decision, tracked in MDL-53236: a cohort is a static list of people, not a time-boxed enrolment, so the sync plugin syncs the list and refuses to reason about time. Setting an enrolment duration on the sync method accomplishes nothing.

We think that's a defensible call for core. But it means "everyone in cohort X gets one year of access" — the single most common compliance-training shape we see — has no supported implementation at all. Memberships pile up forever, and access never lapses.

The fix

A batched CLI script that removes expired memberships safely

The core design decision: delete the mdl_cohort_members row and touch nothing else. Don't unenrol anyone yourself. Moodle's own scheduled enrol_cohort_sync task notices the orphaned enrolments on its next pass and applies each course's configured external-unenrol action. You get exactly the behaviour a manual cohort removal would produce, because mechanically it is a manual cohort removal — just scripted.

The script runs from cron as a Moodle CLI script. The guardrails are not optional decoration; every one of them exists because of something that went wrong or nearly did:

• Batch cap (--max-rows): bounds the blast radius per run — we use 50 a day.
• Cohort exclusions: skip listed cohort IDs (sampler cohorts, staff groups).
• Role guard: never touch a user holding an elevated role anywhere on the site — manager, course creator, teacher, and so on.
• Email guard: never touch accounts on your internal staff domain. Belt and suspenders on top of the role guard.
• Siteadmin guard: never touch anyone in $CFG->siteadmins.
• Pause file: if a designated file exists, the run is skipped entirely. An emergency stop that doesn't require editing crontab.
• Lock: a \core\lock so the job can't overlap itself or a panicked manual run.
• Transactional delete, logged: every removed row is logged with id, user, cohort, and join date.

The heart of it is the eligibility query. Parameterised, it looks like this:

$where = [
    'cm.timeadded < :cutoff',
    'cm.cohortid ' . $notinsql,                    // excluded cohorts
    // only cohorts that actually drive a student-role cohort enrolment:
    "EXISTS (SELECT 1 FROM {enrol} e
              WHERE e.enrol='cohort' AND e.customint1=cm.cohortid AND e.roleid=5)",
    // never remove elevated-role users:
    "NOT EXISTS (SELECT 1 FROM {role_assignments} ra
                  WHERE ra.userid=cm.userid AND ra.roleid IN (1,2,3,4,...))",
    // never remove internal/staff emails:
    "NOT EXISTS (SELECT 1 FROM {user} u
                  WHERE u.id=cm.userid AND (u.email LIKE '%@your-staff-domain.example'))",
];
// + exclude $CFG->siteadmins by id

Two notes on that. roleid=5 is the stock student role and customint1 is where enrol_cohort stores the cohort id — both standard, but verify on your site. And don't hardcode the elevated-role id list like the placeholder suggests: resolve the ids from mdl_role by shortname, because sites with custom roles will differ.

The delete itself, batched and transactional:

$targets = $DB->get_records_sql(
    "SELECT cm.id ... WHERE $where ORDER BY cm.timeadded ASC",
    $params, 0, $maxrows);

$tx = $DB->start_delegated_transaction();
$DB->delete_records_list('cohort_members', 'id', array_keys($targets));
$tx->allow_commit();
// do NOT sync inline; Moodle's scheduled enrol_cohort_sync picks up orphans.

Ordering by timeadded ASC means the most-overdue people leave first, which is what a compliance auditor would expect.

Field notes

Gotchas, and the incident that shaped the guards

Remove vs suspend. The script removes the membership; what happens to each course enrolment is then decided by that enrolment instance's external-unenrol-action setting — fully unenrol, or suspend and keep roles. Suspend is the audit-friendly option, since grades and completion records stay in place. Decide this per course before switching the script on, because it's the difference between "access paused" and "grades moved to history."

Re-adds reset the clock. Re-adding a user writes a fresh timeadded, so they get another full year. For annual training that's correct behaviour — re-enrolment is a new cycle — but document it, or someone will file it as a bug.

Cron downtime is harmless. Eligibility is "older than N days," not "expires today," so a missed run just means a slightly bigger pool next time — and the batch cap prevents a thundering-herd unenrolment after an outage. No state is lost.

One cohort, many courses. A single cohort can drive enrolments in dozens of courses. Removing the one membership row cascades cleanly to all of them via the sync task, which is precisely why deleting the row is better than scripting unenrolments course by course.

Quick answers

Questions people ask about this