Manages cohort memberships via CSV: add users to cohorts, remove them, or sync a user's cohort memberships to a desired state. UI-based (CSV upload) with dry-run, HTML report and CSV download; two CLI entry points are also provided.
Moodle core has no built-in way to remove users from cohorts via CSV or the
UI — this is an open tracker request,
MDL-61007, open since 2017.
Core's tool_uploaduser already covers add via cohort1,cohort2,...
columns, and the core_cohort_delete_cohort_members web service covers
remove programmatically, but neither has a UI, a dry-run, or a report.
This plugin fills that gap and, since a single CSV-driven workflow already
existed for removal, extends it to cover add and sync as well - one
CSV format, one report, one dry-run, for all three operations. It began as
local_cohortunenroller (remove-only) and was renamed and extended into
local_cohortmembership.
- Never auto-creates cohorts. An unknown cohort
idnumber/idis an error row in the report, never a new cohort. This is a deliberate deviation from Moodle core, which silently creates a new cohort for an unrecognisedcohortNvalue intool_uploaduser(MDL-41639) - a frequent source of duplicate-cohort chaos. - Dry-run is the default (the checkbox is pre-selected in the UI).
- All membership changes go exclusively through Moodle's
cohort_add_member()/cohort_remove_member()- never a direct database write. - A single bad CSV row never aborts the whole run; only file-level problems
(bad headers, mixing
syncwithadd/del) reject the file before any row is processed. - Every CSV row produces exactly one report line (
sync-driven removals that are not named by any row get an additional, clearly synthetic line). - User matching is by
usernameonly (notidnumber/email) - out of scope for v1.
Removing a user from a cohort is not limited to the cohort_members
table. If a course has an active Cohort sync enrolment method
(enrol_cohort) pointing at that cohort, removing the membership also
unenrols the user from that course - taking their grades, group
memberships, and other course-specific data with it.
Every removal row in the report (del or sync) is flagged if the cohort
is used by at least one active enrol_cohort instance. Take a database
backup before running a removal in live mode if you are not certain which
cohorts feed course enrolments.
One row per operation. Header row is required (lower case).
operation,username,cohortidnumber
add,hans.muster,kurs-inf-2026
del,hans.muster,kurs-inf-2023
Downloadable example: example-add-del.csv - also linked directly
from the upload form itself, the same way core's "Upload users" offers its example.csv.
- Exactly one of
cohortidnumber(text) orcohortid(numeric) must be present as a column. If both are present,cohortidwins and the report notes thatcohortidnumberwas ignored. operationis one ofadd,del,sync. If the column is omitted entirely, every row is treated asdel(backward compatible with the originallocal_cohortunenrollerCSV format).- A file must be either pure
sync, or pureadd/del- mixingsyncrows withadd/delrows in the same file is rejected before any row is processed.
sync works per user, across all of that user's rows in the file, not
row by row:
operation,username,cohortidnumber
sync,hans.muster,kurs-inf-2026
sync,hans.muster,basis-alle
sync,anna.beispiel,kurs-bwl-2026
Downloadable example (includes a third user, peter.roth, to show two
users' targets computed independently): example-sync.csv -
also linked directly from the upload form.
- The file universe is the union of every cohort named anywhere in the
file:
{kurs-inf-2026, basis-alle, kurs-bwl-2026}. - For
hans.muster, the target state is{kurs-inf-2026, basis-alle}. If he is also a member ofkurs-bwl-2026(in the universe, but not in his rows), that membership is removed. If he is a member of somesonstiges-2020cohort that never appears in the file, it is never touched - there is no "full replace" against a user's entire cohort list, only against the cohorts the file actually mentions. anna.beispiel's target is{kurs-bwl-2026}, computed independently ofhans.muster's rows.
This scope rule is what makes sync safe to run repeatedly without a
managed/ownership flag on cohorts.
Site administration → Plugins → Local plugins → Cohort Membership.
Upload a CSV, review the dry-run report, then re-run with dry-run unchecked
to apply. The report and the CSV download both show operation, status
and whether cohort-sync was affected per row; a summary line counts
removals with a cohort-sync warning.
Category managers without site-level rights can use the plugin for their own category: open the category, then More → Cohort Membership (next to core's "Cohorts"). The page works exactly like the site-level one, restricted to that category:
- Only cohorts in this category or one of its subcategories are visible. Any other cohort - system-level or in another category - is reported as "Cohort not found", so the report reveals nothing about cohorts elsewhere. An idnumber reused by a cohort in another category therefore does not make the cohort in this category ambiguous.
- A visible cohort is only changed where the user holds
moodle/cohort:assignin the cohort's own context (a prohibit on a subcategory is honoured, as in core); otherwise the row says "You may not assign members to this cohort". - For
sync, cohorts that are not found or not permitted never join the file universe, so a sync run from a category can never remove a membership outside it. - Hidden categories are only reachable for users who may see them.
- Users are matched site-wide, as in core's own "Assign" cohort page.
The menu entry appears for users holding both local/cohortmembership:manage
and moodle/cohort:assign in the category; by default that is the Manager
role assigned at category level.
Two scripts are provided:
-
cli/membership.php- the current entry point, supporting the fulladd/del/syncformat described above (with or without theoperationcolumn).php local/cohortmembership/cli/membership.php --csv=/path/in.csv \ [--report=/path/out.csv] [--dry-run] [--username-standardise] \ [--delimiter=comma|semicolon|tab]
-
cli/unenrol.php- the original,del-only script fromlocal_cohortunenroller, kept unchanged for backward compatibility with existing cron jobs/scripts. New integrations should usecli/membership.phpinstead.php local/cohortmembership/cli/unenrol.php --csv=/path/in.csv \ [--report=/path/out.csv] [--dry-run] [--username-standardise]
Both exit 0 on a clean run, a non-zero code on error rows or a
file-level validation failure, and require the account running PHP CLI to
already have server-level access (there is no login/capability check - the
same trust model Moodle's own admin/cli/*.php scripts use).
This plugin does not store any personal data of its own: the report only
ever lives in the current user's session, for the duration needed to
display it and offer the CSV download. It implements
\core_privacy\local\metadata\null_provider accordingly.
Requirements: Moodle 5.0-5.2 or 5.3 LTS, PHP 8.2-8.4 (see Compatibility).
- Get the code:
- download a release from GitHub Releases, or
git clone https://github.com/tkorner/moodle-local_cohortmembership.git
- Place it at
<moodle>/local/cohortmembership- the folder name must be exactlycohortmembership; Moodle derives the component name (local_cohortmembership) from it. - Site administration → Notifications, to trigger the install.
- By default, only the Manager archetype gets the
local/cohortmembership:managecapability (core'smoodle/cohort:assignis required in addition). To grant access to another role, assign both capabilities to it under Site administration → Users → Permissions → Define roles. Both are category-level capabilities, so a Manager assigned to a course category gets the category entry point (see From a course category). - Open: Site administration → Plugins → Local plugins → Cohort Membership, or from a course category: More → Cohort Membership.
Targets Moodle 5.0-5.2 and 5.3 LTS, PHP 8.2-8.4. Moodle 4.5 LTS was supported up to release 1.1.0; use that release on 4.5 sites. Verified by actually installing the plugin against a real checkout of each Moodle 5.x point release (not just reading changelogs) and running the full PHPUnit suite plus a live CLI smoke test against each:
| Moodle version | Result |
|---|---|
| 5.0.8+ | ✅ PHPUnit 34/34, CLI smoke test (real DB changes verified) |
| 5.1.5+ | ✅ PHPUnit 34/34 |
| 5.2.1+ | ✅ PHPUnit 34/34 (also the primary dev/live-verification target throughout development) |
| 5.3 LTS (Build 20261005) | ✅ PHPUnit 48/48, CLI smoke test (real DB changes verified) — no plugin code changes needed; cohort_add_member()/cohort_remove_member() are not deprecated in 5.3 |
Moodle 5.3 itself requires MariaDB >= 11.4 / PostgreSQL >= 17 and PHP >= 8.3; the plugin adds no requirements of its own beyond that.
Moodle 5.1 introduced a public/ web-root split (the actual codebase
moves one level down, e.g. public/local/...); this plugin has no
dependency on the installation's directory layout (no hardcoded
dirroot-relative paths outside the standard $CFG->dirroot-based
includes), so it is unaffected either way.
This plugin uses Moodle Plugin CI on GitHub Actions against PHP 8.2-8.4 and Moodle 5.0, 5.1, 5.2 and 5.3 LTS, on MariaDB and PostgreSQL: PHP lint, Moodle coding style (moodle-cs), PHPDoc checker, upgrade savepoints, Mustache lint, PHPUnit, and (best-effort) Behat.
Run the PHPUnit suite locally (inside a Moodle dev instance that has this
plugin installed under local/cohortmembership):
php admin/tool/phpunit/cli/init.php # once, to set up the test environment
vendor/bin/phpunit --filter local_cohortmembershipCheck coding style locally with moodle-cs:
phpcs --standard=moodle local/cohortmembershipSee SPEC-cohortmembership.md for the complete
behavioural specification, including every validation rule and the full
PHPUnit test case list.
Developed with the assistance of Claude Code.
See CLAUDE.md for the project context file used to guide it.
GPL v3 or later - see LICENSE.