User Kit Bundle Laravel Package

Getting Started

First, the compatibility reality check. nowo-tech/user-kit-bundle is a Symfony bundle (PHP >=8.2, Symfony 7/8 per the project rules). It is not installable into a Laravel app: there is no service provider, no Blade views, no Eloquent models, no config/user-kit.php publish tag. As a Laravel developer you have two honest options:

1. Bridge — run it inside a Symfony service in the same organisation and call it over HTTP/queue. Only worth it if you already operate Symfony.
2. Harvest the concepts — read the source as a reference implementation and re-implement the three behaviours (enable/disable, last activity, presence) natively in Laravel. This is what most Laravel teams will actually do.

Where to look first (in the repo, in this order):

Minimal first use case — "green dot for online users + block disabled accounts":

1. composer require nowo-tech/user-kit-bundle (pin the exact version; see Gotchas).
2. Register the bundle in config/bundles.php.
3. Apply the bundle's trait/interface to your User entity and run the migration the bundle ships (or copy its columns).
4. Set the presence window in the bundle config (typically under a user_kit: root key) and confirm the name from the DI extension, not from blog posts.
5. Render "online" from the bundle's Twig helper or your own query against lastActivityAt.

If step 4 or 5 is undocumented in the README, treat the DI extension and the service definitions as the documentation — that is normal for a 0-star bundle and the only reliable source.

Implementation Patterns

Pattern 1 — Trait on the user entity. The bundle almost certainly expects a specific interface + trait pair on your user class. Keep that wiring in the entity only; put business rules in a service, not in the entity, so the same logic ports to Laravel later.

Pattern 2 — Throttled activity touch. Last-activity writes on every request will dominate your write load. Wrap the update in a "write at most once per N minutes" guard:

// conceptually: only persist if the stored value is stale
if ($user->getLastActivityAt() < $now->modify('-2 minutes')) {
    $user->setLastActivityAt($now);   // let the unit-of-work flush it
}

In Laravel the equivalent is a TouchLastActivity middleware with the same guard, using last_activity_at and a cached "already touched this session/minute" flag so you skip the UPDATE entirely.

Pattern 3 — Presence as a derived query, never a stored boolean. "Online" should be last_activity_at >= now() - window. Store only the timestamp; compute presence at read time. A stored is_online column requires a cron to clear it and is always wrong for a few minutes.

Pattern 4 — Enforcement in the authentication path, not the controller. In Symfony that is a user checker on the firewall; in Laravel it is a guard check or a middleware on the authenticated group. Enforcing in one controller means every new route is a hole.

Pattern 5 — Admin toggle as a form type action. The bundle's enable/disable methods are the seam; expose them through your own admin controller and fire a domain event (UserDisabled) for audit logging. Do not let the admin UI write the column directly.

Pattern 6 — Scheduled pruning/counting. Run a daily job to null-out ancient activity timestamps and a cached "users online now" counter (5-minute TTL) so a dashboard does not run COUNT(*) on every page view.

Laravel portability note: every one of these maps cleanly — middleware for the touch and the enabled check, a scheduled command for pruning, a cached count, and a last_activity_at indexed column. Keep that mapping in mind while reading the Symfony code; it is a weekend of work, not a rewrite.

Gotchas and Tips

• Zero stars, zero dependents. Treat the source as untrusted input: read the DI extension and every service that touches the user entity before shipping. Pin "nowo-tech/user-kit-bundle": "x.y.z" exactly — ^ on an unvetted bundle is how you get a surprise major.
• Verify the tag actually exists. The recorded last release is 2026-10-13. Confirm that tag resolves in Packagist/composer show and matches what composer.json constraints allow before assuming the version you want is installable.
• The README is the weakest link. With no docs site and no dependents, the DI extension is the config reference. Diff the extension against the README and trust the code.
• Entity changes are the risky upgrade surface. If the bundle ships a migration or a mapped superclass, a minor upgrade can add a non-nullable column and break deploys. Review UPGRADING/CHANGELOG and diff the mapping files on every bump.
• Do not call flush() inside the request listener. Touching the entity and letting Doctrine's unit of work flush at the end of the request is one query; a manual flush inside a kernel listener on every request is how you double your DB round-trips.
• Timezone and clock. Always store UTC and inject a clock service in tests; a new \DateTimeImmutable() buried in a service makes presence tests flaky at window boundaries.
• Index last_activity_at. Presence queries are WHERE last_activity_at > ? and will table-scan without it.
• Presence window drift. Front-end polling intervals and the backend window must agree. If the JS polls every 60s and the window is 60s, users flicker offline; use 2–3× the poll interval.
• Enabled vs soft-deleted vs role. Three ways to say "cannot log in" will eventually contradict each other. Pick the enabled flag as the single source of truth and make soft-delete purely an admin/retention concern.
• Extension points, if you stay on Symfony: decorate the bundle's services rather than editing vendor code; override templates via the standard templates/bundles/UserKitBundle/ path; keep config overrides in config/packages/user_kit.yaml.
• Generated assets are off-limits. If the bundle ships a built JS/CSS tree under src/Resources/public/build, never patch it — rebuild from src/Resources/assets or override in your app.
• Add one focused test the day you integrate: a fake clock, a disabled user, and an assertion that authentication is rejected — that single test catches most regressions on upgrades of a bundle nobody else is testing for you.