Pluslms Laravel Package

Getting Started

Because this is a small, low-traffic package (13 stars, no dependents), treat the README as a starting point and the src/ tree as the real documentation. Budget an hour to read it before wiring anything into a product.

1. Install into an existing Laravel app (don't scaffold a fresh app around it — you'll want your own auth, queues, and storage already in place):

   composer require plus-education/pluslms
   

2. Publish and inspect what it ships. Run the publish command with no arguments first to see the tags it registers:

   php artisan vendor:publish --provider="PlusEducation\\PlusLms\\PlusLmsServiceProvider"
   

   You typically get a config file, migrations, and possibly views/assets. Read the config file top to bottom — it's the cheapest way to learn the package's mental model (storage disks, route prefixes, middleware stack, model bindings).

3. Migrate on a throwaway database first.

   php artisan migrate --pretend
   php artisan migrate
   

   --pretend lets you spot table-name collisions or foreign keys pointing at users before they bite you.

4. Find the entry points. Open vendor/plus-education/pluslms/routes/ and src/Http/Controllers. Whatever routes are registered tell you the intended flow (course → module → lesson → enrolment is the usual LMS shape). php artisan route:list --path=<prefix> will confirm the prefix and middleware.

5. First use case: stand up a single course with two or three lessons, enrol yourself, and complete a lesson end-to-end through the UI. That one loop exercises models, policies, routing, and whatever progress-tracking the package implements. Don't start with content import or SCORM-style packages — get the boring happy path working first.

Implementation Patterns

Wrap, don't scatter. Create a thin application-level layer (app/Lms/) that your controllers and Blade views talk to. The package's models will leak into your code either way, but if every reference goes through one namespace you can swap or fork the dependency later without a codebase-wide find-and-replace. With zero dependents and low activity, an exit ramp is not paranoia.

Extend models rather than editing vendor code. Most LMS packages define Course, Lesson, Enrolment-style Eloquent models. Subclass them, override $fillable, $casts, and relationships, and rebind in a service provider:

// app/Providers/AppServiceProvider.php
$this->app->bind(
    \PlusEducation\PlusLms\Models\Course::class,
    \App\Lms\Course::class
);

Verify the package resolves models through the container (app(Course::class)) rather than new Course — if it hardcodes new, this pattern won't hold and you'll need to fork.

Policies over middleware. Multi-tenant or instructor/student separation should live in Laravel policies keyed to the package's models. Register them in AuthServiceProvider and call $this->authorize() in your own controllers. If the package ships its own middleware for course access, use it as a gate but keep your business rules in policies so they're testable.

Content seeding as a first-class workflow. Authoring courses by hand in the UI doesn't scale for demo environments or staging. Write a seeder or Artisan command that creates a course with N modules and lessons using the package's models directly (or its factories, if published). This becomes your test fixture, your staging data, and your onboarding demo in one.

Queue anything heavy. Course duplication, bulk enrolment, exports, and notification fan-out should go through jobs. Check whether the package dispatches events on enrolment/completion — if it does, hook listeners there instead of overriding controller methods:

Event::listen(LessonCompleted::class, SendCompletionEmail::class);

Override views, don't edit them. Publish views and edit the copies under resources/views/vendor/pluslms/. Keep a diff of your changes in a notes file so upgrades are reviewable.

Integration tips:

• Keep the package's routes behind its own prefix and a dedicated middleware group; don't let its public routes inherit your admin session config by accident.
• If you need an API, write your own controllers and reuse the package's models — do not expose its web routes as JSON.
• Point the package's storage disk at S3 (or whatever you use) via config rather than editing upload code.
• Add the package's migrations to your CI pipeline explicitly; a fresh migrate:fresh on every test run is the only reliable check that they still work.

Gotchas and Tips

Pin the version exactly. With 13 stars and no dependents, there is no ecosystem pressure to preserve BC. Use "plus-education/pluslms": "1.2.*" (or a commit hash) and upgrade deliberately. A ^ constraint here buys you nothing and can break a release.

Vendor it if you're serious. composer require + a git-tracked fork under a VCS repository entry is often the right call for a package like this. You get to fix bugs the maintainer won't, and you keep a patch history. Decide this before you write 3,000 lines against its API.

Migration collisions are the most likely first failure. Generic table names (courses, lessons, enrollments) collide constantly. Check ordering — if the package's migration references users before your users migration runs, you'll get a foreign-key error on fresh installs. Fix by adjusting the migration filename timestamp in your own published copy.

Route and model-binding conflicts. The package may register a catch-all or a {course} binding that clashes with yours. Run php artisan route:list after install and again after adding your own routes. If you see duplicate URI patterns, disable the package's route registration in config and define your own controllers on top of its models.

Config caching surprises. Publish the config, then test with php artisan config:cache. Packages that read env() at runtime (rather than in the config file) will silently fall back to defaults in production. Grep the source for env( — if it appears outside config/, that's a bug you need to work around.

Watch for hardcoded auth()->user() and the default guard. Small LMS packages often assume web guard and a User model at App\Models\User. If you use a custom guard or a different user model, expect to override the config's user-model key and test every authenticated route.

N+1 queries on course listings. Course → modules → lessons → progress is a four-level chain; listings will be slow out of the box. Wrap queries in your own repository methods with with() eager loads rather than relying on the package's index queries.

Testing. If the package doesn't ship factories, write your own in database/factories/ against its models. Do not test through its HTTP routes — they're brittle and outside your control. Test your wrapper layer and your policies.

Debugging: when a page 500s inside a vendor view, php artisan view:clear first, then check whether you have a stale published view shadowing a changed package view. Vendor views silently take precedence and are the most common "the upgrade did nothing" cause.

Extension points to look for, in order of value: container bindings for models → events dispatched on state changes → published config → published views. If a package offers none of the first two, you're effectively forking it, and you should price that in before committing.

Support reality check. MIT license, tiny user base, no dependents means: no Stack Overflow answers, no third-party tutorials, and bug reports may go unanswered. Plan for one developer on your team to own this dependency — reading the source, tracking upstream commits, and maintaining the fork. That's a reasonable cost for an LMS skeleton; it's not reasonable if the team expects to treat it like laravel/framework.