Webinar Laravel Package

Getting Started

The escolalms/webinar package is a module of the EscolaLMS stack, so treat it as one card in a house of cards rather than a standalone library: it expects escolalms/core (base models, contracts, admin scaffolding) and typically a course/consultation module to hang webinars off of. Install it after those are in place, not before.

Minimal path:

1. composer require escolalms/webinar
2. Publish and run migrations: php artisan vendor:publish --tag="webinar-migrations" then php artisan migrate. Publish config too (--tag="webinar-config") even if you change nothing — you want the file in VCS so config drift between environments is visible in diffs.
3. Confirm the service provider is auto-discovered (EscolaLms\Webinar\Providers\WebinarServiceProvider) and that its routes appear: php artisan route:list | grep -i webinar. If nothing shows up, you're almost certainly missing a dependency provider, not the webinar package itself.
4. Seed one webinar in tinker and hit the index endpoint. This is your first use case: listing webinars for a course/consultation page. Once you can list, create, and show one, the package is wired correctly and everything else is variations on the same theme.

Where to look first, in order: config/ (limits, relations, feature flags), src/Models/Webinar.php (fillable fields and relations define what the rest of your app can actually do), src/Http/Controllers/ (what the API genuinely exposes), database/migrations/ (authoritative schema — the README may lag).

Implementation Patterns

Thin controller in your app, package handles persistence. Don't call the package models directly from your Blade/Livewire components. Wrap the package behind your own service or repository so that when a minor release renames a field, you patch one file. EscolaLMS moves fast on 0.x; the seam costs you an hour now and saves a weekend later.

Register permissions before you ship. Permissions are enum-backed and registered through the core package. Do this in a seeder or an install command, not ad hoc — otherwise a fresh environment will return 403s that look like routing bugs. Run the permission seeder as part of your deploy pipeline.

Events over direct calls. The package emits model events on create/update/destroy (and usually has an accompanying event/listener scaffold). Subscribe to those for side effects — notifications, calendar sync, cache invalidation — rather than overriding controllers. That's the extension point that survives upgrades.

Sorting is now a first-class concern. Release 0.1.44 adds order by support to the query layer. The idiomatic integration is to build your admin index tables around the package's collection endpoint and pass a sort parameter through rather than sorting in PHP after the fact:

$webinars = Webinar::query()
    ->when($request->sort, fn ($q, $sort) => $q->orderBy($sort, $request->direction ?? 'asc'))
    ->paginate($request->per_page ?? 15);

Do not open a custom query builder for sorting — mirror whatever parameter name and column whitelist the package's own index action uses, otherwise the admin panel and your custom page will disagree about what's sortable, and someone will file a bug about "the table sorts differently on two screens." Verify the exact parameter name against the controller in your installed tag; it is not guaranteed to be stable across minor releases.

Compose, don't fork. If you need a field the package doesn't have, add a migration on a related model or a nullable column in your own table and a belongsTo-style join, or extend the model with a trait — never edit vendor/. Composer will happily overwrite your work at 3am.

Testing. Wrap integration tests in RefreshDatabase and call the package's factories. Testing against hand-built fixtures tends to break on schema additions; factories are maintained upstream.

it('sorts webinars by name', function () {
    Webinar::factory()->count(3)->create();
    $this->getJson('/api/webinars?sort=name&direction=asc')
        ->assertOk()
        ->assertJsonPath('data.0.name', fn ($n) => is_string($n));
});

Admin panel vs. API. EscolaLMS ships its own admin UI. Decide early whether you're embedding that or building your own; mixing both means two permission sets, two pagination conventions, and two sets of sort parameters — exactly the axis the 0.1.44 change touches.

Gotchas and Tips

• 0.x means no semver promises. Pin the exact version in composer.json ("escolalms/webinar": "0.1.44") for production and upgrade deliberately. Loose constraints on a 0.x package will eventually resolve to something with a renamed method.
• Sorting/ordering is not a whitelist by default in most of these modules. If the sort column is interpolated into orderBy without an allow-list, a caller can probe schema via ordering side channels and hit unindexed columns, producing slow queries on large tables. Sanitise against an explicit array of allowed columns at the boundary of your own controller before it reaches the package.
• Migrations arrive in numbered files; run them in order and never roll back in production to "reset" — re-running publishable migrations on a populated table is a common way to lose seeded webinar data. Test rollbacks locally only.
• Relation loading is the usual performance trap. Webinar listings rarely explode, but the with() you're missing is usually a relation added by a neighbouring module (course, author, consultation). Run DB::listen or Laravel Debugbar on the index endpoint early and fix N+1s there, when there are 20 rows, not 20,000.
• Config caching makes published config changes invisible. php artisan config:clear after editing config/webinar.php, and always re-publish after a minor upgrade to diff the new keys against your copy — new config keys appear silently and usually default to "feature off," which reads as a regression.
• Route registration failures are provider-ordering failures. If route:list is missing webinar routes, check the order of providers in bootstrap/providers.php and that core's provider runs first. The error surfaces as a 404, which sends people hunting for route files that are perfectly fine.
• Upgrade recipe for minor releases like this one: install into a branch, run migrations on a scratch DB, route:list diff, run the package's own test suite if vendored, then click through your top three screens (index, show, admin table). The 0.1.44 change touches queries, so a smoke test of any paginated or sorted listing is the highest-value check — a broken orderBy rarely throws, it silently returns unsorted data and users lose trust in the table rather than reporting a bug.
• Events fire inside the package's transaction boundaries (usually). Don't assume the related row is committed when your listener runs; if you must, use DB::afterCommit. This bites people sending confirmation notifications from a listener on create.