Filagora Memberships Laravel Package

Getting Started

This is an early (v0.1.x) package, so treat the public API as unstable and pin the version in composer.json.

1. Install and publish:

   composer require filagora/memberships
   php artisan vendor:publish --tag=memberships-config
   php artisan vendor:publish --tag=memberships-migrations
   php artisan migrate
   

2. Read the service provider first — it shows what is bound, what is deferred, and how the forums integration is wired. Then look at config/memberships.php (plans/tiers, gating defaults) and the migrations (membership/subscription tables).
3. Bind the host's access checker contract in a service provider. This is the dependency the forums rule needs; if it is missing, anything that resolves the rule registry will fail.
4. First use case: gate forum content or announcements behind an active membership. Resolve the forums rule registry from a controller, middleware, or listener (not from register()), and let the package's membership targeting rule participate in announcement targeting.
5. Verify with a smoke test: create a user, attach a membership, hit a gated forum route, and confirm both allowed and denied paths.

Implementation Patterns

Gate checks in policies and middleware. Prefer a single membership-check abstraction (policy, gate, or middleware) over scattering hasActiveMembership() calls through controllers. Blade directives are convenient for hiding UI, but always enforce server-side in middleware/policies.

Lazy registry resolution. Since v0.1.1 the membership announcement targeting rule is registered the first time the forums rule registry is used, not during application boot. Follow the same discipline in your own code: resolve the registry inside a handler, not in a provider's register() or boot(). If you need it at boot, wrap it in a deferred provider or a closure so it only runs when actually consumed.

Custom or overriding rules. Filagora\Memberships\Forums\MembershipRule is non-final as of v0.1.1, so you can extend it to add host-specific targeting logic (e.g. plan-specific announcements) while reusing its membership matching. Keep the constructor signature compatible, since the parent depends on the host's access checker.

Rule precedence. The registry keeps a membership rule that was registered first. If you want your own implementation to win, register it before anything resolves the registry for the first time — ideally in a dedicated provider that runs early and does not itself trigger registry resolution.

Testing. Bind a fake access checker in TestCase::setUp() so tests never depend on real membership data. For feature tests of announcements, assert on the targeted audience rather than on the rule object. Add one test that boots the app without an access checker bound to lock in the v0.1.1 behaviour (the app should start; only resolving the registry should fail).

Console, queue, and static analysis. Any context that builds the container — queue workers, scheduled commands, PHPStan/Larastan bootstraps — should have the access checker bound if it might touch forum rules. The v0.1.1 fix means a bare bootstrap no longer crashes, but jobs that actually evaluate targeting still need the binding.

Versioning discipline. With 0.x, read the changelog on every minor bump. Keep integration points (your rule subclass, registry registration, access checker binding) isolated in one provider so upgrades are a single-file change.

Gotchas and Tips

• Don't reintroduce the boot-time failure. The original bug was resolving the rule registry during boot before the access checker was bound. If you call the registry from a provider, a package discovery pass, or a config-cache warm-up, you can hit the same "access checker not bound" error — particularly in static-analysis or CI bootstrap scripts.
• First-registered-wins semantics. The membership key is not overwritten by the package if you registered one first. That is useful for overrides but surprising when debugging: if your custom rule isn't taking effect, check when it was registered relative to the first registry use.
• Extending MembershipRule. Override only the targeting decision, call parent:: where appropriate, and avoid adding required constructor arguments — the registry instantiates rules, so a changed signature may break resolution.
• Config caching. After changing membership config, run php artisan config:clear. Lazy registration is not affected by config caching, but plan/tier definitions read at resolution time are.
• Debugging checklist for a missing targeting rule: confirm the forums package is installed, confirm the access checker is bound (app()->bound(...)), confirm nothing resolved the registry earlier and cached a registry without the rule, and confirm the announcement's targeting key matches membership.
• Migrations and data. Early packages change schema between patch releases; snapshot before upgrading and re-run migrate in staging first.
• Extension points to watch. The rule subclass and the registration ordering are the two supported customisation seams today. Anything else (table names, model classes) should be treated as internal until documented.
• Pin and monitor. "filagora/memberships": "0.1.*" with changelog review is safer than ^0.1 if you subclass MembershipRule, since the constructor contract is not yet guaranteed.