User Level Bundle Laravel Package

Technical Evaluation

Architecture fit. tourze/user-level-bundle sits in the "user progression" domain — assigning levels, tiers, or ranks to a user record based on some accumulated metric. The package is small and domain-shallow by nature: the realistic footprint is one or two tables, a model/trait, and a service that resolves a user's current level. That is a good fit for Laravel only if the package is genuinely framework-native. The -bundle suffix is a caution flag: Tourze publishes a large family of Symfony bundles, and a name carried over from that lineage often indicates a Symfony-first core with a thin or absent Laravel service provider. The single most important thing to verify before adoption is whether composer.json declares illuminate/support/illuminate/database constraints or pulls symfony/* transitively. If it drags in Symfony DI/HttpKernel, architecture fit drops sharply.

Integration feasibility. Mechanically trivial if the above checks out: composer require, publish config and migrations, add a trait to the User model. Realistic estimate is well under a day for a working spike, excluding data backfill.

Technical risk. High, and concentrated in process rather than code. Three compounding factors:

1. The 0.0.2 → 0.1.0 release ships no usable release notes — the entry is a bare compare link. Under 0.x conventions this bump is at least as likely to be breaking as additive, and we have no way to tell. We cannot write an integration plan against an undocumented delta.
2. Pre-1.0 with an active minor cadence implies API churn for an indeterminate period.
3. Single-maintainer, low-visibility project. Bus factor of one, and documentation is likely Chinese-language only.

Key questions for the maintainer / spike:

• Does the package depend on any symfony/* package at runtime, and what are the exact php and illuminate/* constraints?
• Do migrations create new tables, or alter the existing users table?
• Is level state persisted (auditable, replayable) or computed on read?
• How are concurrent level changes handled — is there a transaction/lock around the threshold crossing?
• Does it assume auto-increment user IDs, or does it support UUID/ULID keys?
• Does it ship a Laravel service provider, facade, and config file, or only Symfony-style DI config that must be hand-wired?

Integration Approach

Stack fit. Gate on Laravel and PHP version constraints first — for a package at this maturity, a missing or stale illuminate/* constraint is a common cause of silent incompatibility. Confirm DB driver support covers our target (MySQL/Postgres) and not just SQLite-in-CI.

Migration path. Do not adopt on a caret range. Pin to the exact 0.1.0 tag, and re-pin deliberately on each release after reading the diff ourselves — the changelog will not do that work for us. Wrap all vendor calls behind a thin internal LevelResolver interface owned by our codebase. This is cheap now (a handful of methods) and is what makes a future swap to an in-house implementation a refactor rather than a rewrite. The vendor package should not appear in controllers, models, or domain services outside that adapter.

Compatibility. Confirm UUID support if our users table uses them; if not, this is a hard blocker and likely disqualifying. Confirm behaviour when a user has no level row (return null vs. a default sentinel) — this drives null-handling across the codebase.

Sequencing.

1. One-day spike on a branch: install, publish, migrate against a scratch DB, verify the provider registers and the trait works.
2. Decision gate on the spike findings against the key questions above.
3. If green: pin the version, land migrations, add the adapter interface.
4. Backfill existing users behind a feature flag; run the flag off in production until backfill is verified.
5. Only then expose level data in read paths (API responses, UI).

Operational Impact

Maintenance. Pre-1.0 churn plus undocumented releases means ongoing cost is review time, not runtime. Budget a recurring half-day per release cycle for diff review, and assume we are the ones responsible for knowing what changed. Contingency should be a willingness to vendor or fork — for a package this small, forking is a realistic and cheap outcome.

Support. Effectively nil. GitHub issues with no SLA, single maintainer, probable language barrier. We own all bugs. Factor this into whether the domain logic is worth externalising at all; a simple level-threshold table is a few hundred lines of code we could own outright, and that option should be explicitly priced against adoption.

Scaling. Depends entirely on the persisted-vs-computed question. Computed levels on read are the common design and the dangerous one: any list endpoint returning N users invites N+1 level lookups. If computed, require eager loading and an index on whatever column the calculation filters on before this reaches a list endpoint. If persisted and updated on write, watch for write amplification on high-frequency metric updates and for lock contention at threshold boundaries.

Failure modes.

• Concurrent threshold crossing: two simultaneous grants each read the pre-update value and the level lands incorrectly. Highest-severity failure, and silent — no exception, just wrong data. Verify locking.
• Migration collision: an alter to users conflicting with our own schema history.
• Missing backfill: existing users resolve to null level and downstream code treats null as "lowest" rather than "unknown," producing wrong entitlements.
• Silent no-op on unregistered levels: thresholds configured but no level row matching, returning null where a tier was expected.

Ramp-up. Low for any Laravel developer — the concept is familiar and the surface area small. One to two days including the spike, contingent on documentation language. The cost is not learning the package; it is the standing review obligation and the absence of anyone to escalate to.