Courses Laravel Package

Technical Evaluation

Architecture fit EscolaLMS/Courses is a standard Laravel package (service provider, publishable config/migrations, contract-bound repositories) that models courses, chapters, lessons, topics, prerequisites, and assignments. It fits a modular Laravel monolith or a modularized API backend that already consumes escolalms/core contracts and events. 0.4.45 does not add surface area — it changes the behavior of an existing domain event listener (CourseAssigned) so that a deadline is recalculated when a course is assigned. Architecturally this is a write-path change inside the domain, not a new integration point.

Integration feasibility Low effort. The change is confined to the CourseAssigned listener; no new endpoints, config keys, or dependencies are advertised. Integration work is verification, not construction: confirm the listener is registered (auto-discovery vs. explicit EventServiceProvider), confirm whether it runs synchronously or via queue, and confirm the deadline derivation source (assignment timestamp, course term, or course-level setting).

Technical risk Medium, despite the patch-level bump. The package is 0.x, so semver guarantees are weak and a patch release can legitimately carry behavior changes — this one does. Specific risks:

• Idempotency: re-assignment or duplicate events may recalculate a deadline more than once, either extending or shortening an existing enrollment deadline.
• Retroactivity: existing assignments may have their deadlines silently rewritten, affecting learners mid-course.
• Timezones: deadline arithmetic on Carbon instances is a common source of off-by-hours drift when the app timezone and course timezone differ.
• Downstream coupling: notifications, reminder jobs, certificate issuance gating, and exam windows may all read the deadline column and will shift with it.
• Silent failure: if the listener is queued, a stalled worker leaves deadlines stale with no error surfaced.

Key questions

1. Does the listener fire on every CourseAssigned event, or only on first assignment? Is it guarded against duplicate/retried events?
2. Is the recalculation absolute (overwrite from source of truth) or additive (extend from now)? Can it ever move a deadline earlier?
3. What is the authoritative source for the deadline — course settings, term dates, or assignment timestamp — and is that documented?
4. Does 0.4.45 include any migration or backfill for existing enrollments, or does it only affect new assignments?
5. Are reminder/notification jobs rescheduled when a deadline changes, or do they fire against the old value?
6. Which sibling packages (exams, certificates, payments) pin escolalms/courses and would need to be re-validated?

Integration Approach

Stack fit Laravel 8–10 / PHP 8.x on MySQL or Postgres, exposed as a JSON:API backend. Assumes escolalms/core (contracts, base repositories), escolalms/auth, and optionally escolalms/payments and escolalms/certificates. Front end is decoupled; no changes expected there unless the deadline field's semantics change visibly.

Migration path

1. Pin escolalms/courses to 0.4.45 in composer.json (use an exact constraint while validating; the 0.x line moves fast).
2. Diff 0.4.44...0.4.45 upstream and read PR #329 directly — the release note is one line and is not sufficient for a change-impact review.
3. Run composer update escolalms/courses --with-dependencies; check for transitive bumps in escolalms/core.
4. Run php artisan migrate (verify whether any migration shipped), then config:clear, route:clear, event:clear, queue:restart.
5. Validate in staging with seeded enrollments before touching production.

Compatibility Verify the composer.json constraints for Laravel and PHP against the host application. Check that sibling EscolaLMS packages do not pin courses to 0.4.44 and create a resolution conflict. Confirm the CourseAssigned event payload and the deadline field on the assignment resource are unchanged — if the API contract shifts, clients reading deadline need coordinated release.

Sequencing Freeze → upstream diff review → local reproduction of the assign-course flow (single assignment, re-assignment, group/class assignment) → staging validation of deadline values and any resulting notification scheduling → production deploy in a low-traffic window → monitor assignment error rates and deadline distributions for 48 hours. Treat rollback as a version pin, but note that any deadline values already rewritten in the database will not be reverted by a code rollback — capture a snapshot of affected rows first.

Operational Impact

Maintenance Single-maintainer-driven community package with a fast 0.4.x cadence; expect frequent patch releases carrying behavior changes. Budget recurring time for upgrade review rather than assuming patches are inert. Maintain the ability to fork or hot-patch, and keep the dependency pinned rather than floating.

Support Upstream support is GitHub issues only; no commercial SLA unless procured through the vendor's commercial offering. Internal ownership must sit with an engineer comfortable reading package source — the release notes will not describe behavior in enough detail to operate from.

Scaling The listener cost per assignment is negligible. Watch bulk operations: class-, group-, or CSV-driven mass assignment will trigger N recalculations and, if the listener is queued, a burst of jobs. Ensure the deadline column is indexed since scheduled reminder queries will filter on it.

Failure modes

• Listener exception aborting the assignment transaction (if synchronous) or silently dropping the recalculation (if queued).
• Stale deadlines when queue workers are down — no alerting by default.
• Duplicate recalculation from retried jobs, producing inconsistent deadlines across learners assigned the same course.
• Timezone drift moving deadlines by hours relative to course/term start.
• Drift between stored deadlines and any derived value computed elsewhere in the app, producing two sources of truth.
• Reminder and expiration notifications firing against a deadline that has since changed.

Ramp-up Low. Roughly one engineer-day to internalize the course/assignment model and the deadline derivation rule, plus half a day to validate this specific change. Produce a short internal note documenting how deadlines are derived and when they recalculate — that artifact is the main defense against future regressions in this area.