Completion helpers

Reading and changing a student's progress.

Reading progress

pom_lms_get_course_completion( int $course_id ): int

Returns the current user's completion percentage for a course, from 0 to 100.

$percent = pom_lms_get_course_completion( $course_id );

Signed-out visitors always get 0 — progress belongs to accounts.

How the percentage is calculated

completed lessons ÷ every lesson attached to the course × 100

rounded to a whole number.

Two behaviors follow, and both surprise people:

• The denominator includes lessons with no section, which do not appear in the outline. A course with orphaned lessons can never reach 100%.
• The denominator is live. Adding a lesson lowers every student's percentage immediately; removing one raises it.

If you are building a progress display, do not cache the number across requests — it can change without the student doing anything.

Changing progress

pom_lms_check_lesson( int $course_id, int $lesson_id, bool $status = true )

Marks a lesson complete for the current user, or with false marks it incomplete. Returns the updated set of completed lessons for that course.

pom_lms_check_lesson( $course_id, $lesson_id );        // complete
pom_lms_check_lesson( $course_id, $lesson_id, false ); // not complete

Signed-out visitors are ignored — the call does nothing.

Pass the right course

Progress is stored per course. Passing a course the lesson does not belong to records a completion that no percentage will ever count.

Resolve the lesson's attached course rather than assuming it.

When the plugin calls it itself

Depending on the site-wide completion mode, either opening a lesson marks it complete, or the student ticks it in the outline.

If your integration also marks lessons complete, be aware that in automatic mode the plugin has probably already done it. Marking a lesson complete twice is harmless — the set is deduplicated — but a feature that marks lessons complete in manual mode defeats the point of the setting.

Check the mode before building anything that completes lessons on the student's behalf.

Check access before completing

Marking a lesson complete for a student who cannot open it produces progress they did not earn, in a course they cannot see.

if ( pom_lms_user_can_access_lesson( $lesson_id, $course_id ) ) {
    pom_lms_check_lesson( $course_id, $lesson_id );
}

What completion does not do

• It does not unlock anything. There is no sequential gating in POM LMS.
• It does not fire an event. There is no hook for "lesson completed" or "course completed"; if you need one, call your own code alongside pom_lms_check_lesson().
• It does not expire or reset.
• It does not affect access in either direction.

What is not recorded

No timestamps, no attempt counts, no time spent, no per-lesson history. The record is the set of completed lessons and nothing more.

A feature needing "when did they finish?" needs its own storage.

Reporting

There is no built-in report and no supported way to read another user's progress. pom_lms_get_course_completion() answers for the current user.

An integration that needs cohort reporting should record its own events as students progress, in the student's own request, rather than trying to read progress out of band.