Suspension Security Check Extension Laravel Package

Getting Started

This is a PyroCMS 3 addon, not a standalone Laravel package. It extends the anomaly/users-module and registers a security check that runs during the Users module login flow to reject suspended/blocked accounts. Treat it as a module extension, not a library you use in arbitrary controllers.

Minimal steps:

1. Install the addon into your PyroCMS project (either composer require anomaly/suspension_security_check-extension or drop it in addons/anomaly/suspension_security_check-extension), then run composer dump-autoload.
2. Install/enable it — php artisan addon:install anomaly.suspension_security_check-extension (or via Admin → Addons → Extensions). Composer installing it is not enough; PyroCMS extensions are opt-in and must be enabled before they register anything.
3. Clear caches — php artisan cache:clear (and addon:dump if your version supports it) so the addon manifest is rebuilt.

First use case to verify it works:

• Log in as admin, open Users, suspend/block a test user.
• Log out, attempt to log in as that suspended user.
• You should be bounced back with a security-check failure message and no authenticated session — not a redirect to the dashboard.

Where to look first:

• src/*ExtensionServiceProvider.php — proves how it registers (usually pushing a SecurityCheck into the Users module's security-check collection).
• The extension class itself (the SecurityCheck implementation) — this is the actual gate; it's typically small and worth reading in full.
• The anomaly/users-module User\Security\* directory — to understand the SecurityCheck contract, the SecurityCheckResult, execution order, and the default message/redirect behavior.

Implementation Patterns

How it hooks in. The extension does not intercept login itself; it registers a security check that the Users module's login form/controller iterates before authenticating. So the leverage point is the built-in login flow, plus any custom flow where you invoke the check yourself. Typical registration looks like the provider binding a SuspensionSecurityCheck into the module's check collection; verify the exact method on the provider, since that determines whether the check is always-on or config-gated.

Day-to-day usage pattern. Use this as the single authoritative gate for suspended accounts across web login. Then, wherever you also authenticate users — API token endpoints, social login, custom login controllers — resolve and run the same check manually before issuing a session/token. Do not assume the extension covers those paths; by default it only hooks the Users module login.

Testing pattern (the most valuable day-to-day use). Add a feature test around the login route:

// suspended user is rejected
$user = factory(UserModel::class)->create(['suspended' => true]);
$this->post('/login', ['email' => $user->email, 'password' => 'secret'])
     ->assertSessionHasErrors(); // or assert redirect back with message
$this->assertGuest();

// active user still logs in (regression guard)

This is the pattern to repeat every time you upgrade the Users module — the check's behavior is your contract.

Composing with your own checks. If you add custom security checks (email-domain allowlist, IP gating, 2FA state), be deliberate about order. Put suspension first so blocked accounts get the "blocked" message rather than a downstream failure, and so a compromised/blocked user can't probe other checks.

Custom messaging / logging. The check class is small; extending it (or overriding the binding) is the intended extension point to change the message, log the attempt, or trigger an event (e.g., alert on repeated blocked logins). This is usually more practical than forking the addon.

Admin UX pairing. Wire it to whatever suspension mechanism you use. If you rely on the Users module's own suspend action, the check should read the same field; if you have a custom blocked/suspended_until column, confirm the check reads that attribute, or subclass it.

Gotchas and Tips

• Composer ≠ enabled. The single most common failure: someone installs the package and expects suspension to be enforced, but the extension was never enabled. Always verify via addon:list (or Admin → Extensions) and re-run after deploys.
• Manifest cache. PyroCMS caches addon metadata; after install/move/rename, run cache:clear (and addon:dump) or the check silently won't register.
• Custom auth bypasses it. API tokens, Sanctum/Passport, social login, remember-me re-auth, and programmatic Auth::login() all skip the Users module login flow. Enforce the check explicitly at those boundaries.
• Check ordering and messages. If an earlier check (activation, email verification) fails first, the user sees that message, not "suspended." If you need consistent messaging, reorder or consolidate the checks. Also watch for account-enumeration leakage — a "you are blocked" message confirms the account exists.
• Scope is narrow. This handles suspension/blocked state only — not deactivation, unverified email, or password expiry. Don't expect it to cover those.
• Field mismatch is the quiet bug. A suspended user still logging in almost always means the check reads a different attribute than the admin action writes (e.g., suspended vs a status enum). Add a temporary Log::info() inside the check to confirm it runs and what value it sees.
• Abandoned dependency risk. 1 star, 0 dependents, NOASSERTION license — treat it as sample code, not infrastructure. The actual logic is a handful of lines; inlining the check into your own small extension is often safer and more maintainable than depending on an unmaintained addon. If you do keep it, pin the version and review the class before every PyroCMS upgrade.
• Extension points. Override via container binding or subclass the check; prefer this over editing vendor files so upgrades don't clobber your changes.