Skip to content

About

No description, website, or topics provided.

Resources

Stars

2 stars

Watchers

2 watching

Forks

Repository files navigation

Cohort Membership logo

Moodle plugin CI

Cohort Membership (Moodle local plugin)

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.

Why this plugin exists

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.

Design principles / guardrails

  • Never auto-creates cohorts. An unknown cohort idnumber/id is 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 unrecognised cohortN value in tool_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 sync with add/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 username only (not idnumber/email) - out of scope for v1.

⚠️ Cohort-sync warning

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.

CSV format

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) or cohortid (numeric) must be present as a column. If both are present, cohortid wins and the report notes that cohortidnumber was ignored.
  • operation is one of add, del, sync. If the column is omitted entirely, every row is treated as del (backward compatible with the original local_cohortunenroller CSV format).
  • A file must be either pure sync, or pure add/del - mixing sync rows with add/del rows in the same file is rejected before any row is processed.

sync: bring a user's memberships to an exact state

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 of kurs-bwl-2026 (in the universe, but not in his rows), that membership is removed. If he is a member of some sonstiges-2020 cohort 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 of hans.muster's rows.

This scope rule is what makes sync safe to run repeatedly without a managed/ownership flag on cohorts.

Using the UI

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.

From a course category

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:assign in 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.

CLI

Two scripts are provided:

  • cli/membership.php - the current entry point, supporting the full add/del/sync format described above (with or without the operation column).

    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 from local_cohortunenroller, kept unchanged for backward compatibility with existing cron jobs/scripts. New integrations should use cli/membership.php instead.

    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).

Privacy

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.

Install

Requirements: Moodle 5.0-5.2 or 5.3 LTS, PHP 8.2-8.4 (see Compatibility).

  1. Get the code:
    • download a release from GitHub Releases, or
    • git clone https://github.com/tkorner/moodle-local_cohortmembership.git
  2. Place it at <moodle>/local/cohortmembership - the folder name must be exactly cohortmembership; Moodle derives the component name (local_cohortmembership) from it.
  3. Site administration → Notifications, to trigger the install.
  4. By default, only the Manager archetype gets the local/cohortmembership:manage capability (core's moodle/cohort:assign is 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).
  5. Open: Site administration → Plugins → Local plugins → Cohort Membership, or from a course category: More → Cohort Membership.

Compatibility

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.

Tests & CI

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_cohortmembership

Check coding style locally with moodle-cs:

phpcs --standard=moodle local/cohortmembership

Full specification

See SPEC-cohortmembership.md for the complete behavioural specification, including every validation rule and the full PHPUnit test case list.

Development

Developed with the assistance of Claude Code. See CLAUDE.md for the project context file used to guide it.

License

GPL v3 or later - see LICENSE.

About

No description, website, or topics provided.

Resources

Stars

2 stars

Watchers

2 watching

Forks

Releases

Packages

Used by

Contributors

Languages