lw-lms-backend-extend
Extends LW LMS 2.0.0 from PHP without bypassing its access, progress, quiz, drip, download, privacy, or WooCommerce contracts. Use when code calls `AccessChecker`, `AccessRepository`, `ProgressReposit
SKILL.mdlw-plugins/lw-lms-backend-extend/SKILL.md
GitHubLW LMS backend extension contract
Extend LW LMS through its repositories and hooks. Keep learner REST, quizzes, drip scheduling, and bulk CLI work in the sibling skills named below.
LW LMS remains a headless plugin under active development. Pin the tested version and review its changelog before deployment.
Version 2.0 changes that affect extensions
AccessChecker::has_course_access()has a third$record_enrollmentargument. Course listings passfalse, so merely listing free courses no longer creates enrollment rows.AccessRepository::grant()now deduplicates null-source-ID grants per source.revoke()revokes every active stored row for the user/course; userevoke_by_source()when ownership matters.- WooCommerce grants on
processingandcompleted; it revokes on fully refunded,cancelled, orfailedaccess and handles partial line refunds. manage_lmsgrants access to overview, enrollments, and quiz results. Settings still requiremanage_options.- The old
lw_lms_settings_tabsfilter andSettingsPage::get_settings_group()extension contract were removed by the React admin. Add a separate companion settings screen. - Download URLs are signed, expire after one hour by default, and are re-authorized when used.
- Privacy export/erase and deleted-user cleanup cover enrollments, progress, completion snapshots, quiz attempts, and drip clock user meta.
Hook contract
Actions
| Hook | Accepted args | Meaning |
|---|---|---|
lw_lms_after_grant |
5 | $user_id, $course_id, $source, $source_id, $expires_at; successful insert or update |
lw_lms_after_revoke |
3 | $user_id, $course_id, $source; once for each row revoked |
lw_lms_lesson_completed |
2 | $lesson_id, $user_id; transition to completed |
lw_lms_course_completed |
2 | $course_id, $user_id; first completion snapshot |
lw_lms_attachment_downloaded |
2 | $attachment_id, $user_id; authorized download |
lw_lms_quiz_submitted |
4 | $lesson_id, $user_id, $percentage, $passed; every stored attempt |
lw_lms_quiz_passed |
3 | $lesson_id, $user_id, $percentage; every passing attempt |
Filters
| Hook | Accepted args | Rule |
|---|---|---|
lw_lms_pre_grant |
6 | Return false to abort the write before hooks |
lw_lms_has_course_access |
3 | Final logged-in paid-course decision; open/free/anonymous paths can return earlier |
lw_lms_has_lesson_access |
3 | Lesson decision; preview short-circuit can return earlier |
lw_lms_admin_access_capability |
1 | Capability used by optional Staff Access; default manage_lms |
lw_lms_rest_course_list_item |
3 | Add new top-level list-item fields only |
lw_lms_rest_course |
4 | Add new top-level course fields only |
lw_lms_rest_lesson |
3 | Add new top-level lesson fields only |
lw_lms_lesson_locks |
3 | Filter the lock map keyed by lesson ID |
lw_lms_download_link_ttl |
1 | Signed-download lifetime in seconds; default 3600 |
lw_lms_video_html |
2 | Filter ready-to-render video HTML and lesson ID |
lw_lms_quiz_attempt_cooldown |
3 | Seconds between attempts; default 15, zero disables |
lw_lms_quiz_daily_attempt_limit |
3 | Attempts per rolling 24 hours; default 20, zero disables |
lw_lms_privacy_erase_active_enrollments |
2 | Whether erasure may remove active enrollment rows |
REST payload filters cannot override or remove core keys. PayloadExtension::merge() keeps the original value and accepts only added top-level keys.
Access decisions
Call AccessChecker for the complete entitlement decision:
use LightweightPlugins\LMS\Access\AccessChecker;
$can_open = AccessChecker::has_course_access( $course_id, $user_id );
// Read-only catalog calculation: do not lazily enroll a free-course viewer.
$catalog_access = AccessChecker::has_course_access( $course_id, $user_id, false );
Use AccessRepository for durable grants:
use LightweightPlugins\LMS\Access\AccessRepository;
AccessRepository::grant(
$user_id,
$course_id,
'my_membership',
$external_membership_id,
$expires_at_utc
);
AccessRepository::revoke_by_source(
$user_id,
$course_id,
'my_membership',
$external_membership_id
);
Use a stable non-null source ID for independently owned external grants. The table unique key remains (user_id, course_id, source_id) and does not include source.
Staff Access is a runtime bypass controlled by auto_enroll_admins; it does not create rows. Live subscription, membership, and legacy purchase checks also create no rows and fire no grant/revoke hooks.
Progress writes
Write through ProgressRepository, never through SQL:
use LightweightPlugins\LMS\Progress\ProgressRepository;
ProgressRepository::upsert( $user_id, $course_id, $lesson_id, 'completed' );
ProgressRepository::mark_course_completed( $user_id, $course_id );
Validate that the lesson belongs to the course before programmatic writes. The REST and Abilities paths do this; the low-level repository trusts its caller. A completion write fires lesson completion, clears the request-local drip lock cache, and may create the one-time course snapshot.
ProgressRepository::delete() does not remove the completion snapshot. Decide explicitly whether an administrative reset should also call ProgressSnapshotRepository::delete().
Protected downloads
Do not build /download/{id} URLs manually. Use the REST payload's signed download_url. At download time LW LMS checks signature, expiry, current user, current course/lesson ownership, post visibility, and current access. Revoking access invalidates an otherwise unexpired link.
If changing the TTL, keep it bounded:
add_filter( 'lw_lms_download_link_ttl', static fn ( int $seconds ): int => 15 * MINUTE_IN_SECONDS );
Critical rules
- Register the exact accepted-argument counts shown above.
- Preserve an existing paid grant in additive access filters:
return $has_access || my_check();. - Keep access filters fast, deterministic, and side-effect-free; one response can ask more than once.
- Use
revoke_by_source()for one integration. Broadrevoke()now revokes all active stored rows. - Store expiry timestamps in UTC.
granted_atand progress timestamps are site-local in the current schema. - Add payload fields; do not attempt to replace
access,quiz,sections,progress, or other core keys. - Return a valid lock map from
lw_lms_lesson_locks; a non-array becomes an empty map and opens every lesson. - Do not reintroduce the removed settings-tab API.
Cross-references
- Use
lw-lms-rest-frontendfor learner-facing REST consumers. - Use
lw-lms-quiz-integrationfor quiz schema, scoring, throttling, and result administration. - Use
lw-lms-drip-progressionfor course clocks, linear sequence, schedules, and lock errors. - Use
lw-lms-wp-cli-operationsfor operational commands. - Use
lw-lms-abilitiesfor Site Manager and WordPress Abilities API calls. - Use
lw-lms-learndash-migrationfor the one-time LearnDash importer.
References
- Official repository: https://github.com/lwplugins/lw-lms
- Verified source paths:
includes/Access/AccessChecker.phpincludes/Access/AccessRepository.phpincludes/Access/AccessGranter.phpincludes/Progress/ProgressRepository.phpincludes/Api/DownloadLink.phpincludes/Api/DownloadAccess.phpincludes/Api/Transformers/PayloadExtension.phpincludes/Privacy/PrivacyHooks.phpincludes/Admin/SettingsPage.php