Users Profile Balance Laravel Package

Technical Evaluation

Architecture fit

• Framework mismatch — primary finding. The package is a Symfony bundle, not a Laravel package. The README's install path (php bin/console baks:assets:install, doctrine:migrations:diff, "symfony-cmd" script type) is Symfony Console + Doctrine. Prior assessments in this thread describing it as "Laravel-native" are incorrect and should not be circulated to engineering. In a Laravel codebase this is not a drop-in; it would require an adapter layer, a bridge (Doctrine in Laravel), or a fork-and-port of MIT source. That is a build project, not an install.
• Where it does fit: Symfony 6/7 + Doctrine ORM + PHP 8.4, with a balance model that is profile-scoped (one wallet per user profile) rather than ledger/transaction-scoped. It assumes the host app owns users, auth, and money movement; the package owns a numeric balance attached to a profile.
• Scope honesty: despite downstream write-ups referencing loyalty tiers, multi-currency, expiry, fraud checks, and payment gateways, the README documents only "profile balance" plus install steps. Everything else is speculative. Treat the actual unit of delivery as "a balance counter with persistence and a service API."
• Extensibility assumptions: event-driven hooks are plausible (Symfony EventDispatcher) but unverified; no published event names, contracts, or config schema. Discovery cost lands on our engineers.

Integration feasibility

• Technically installable in ~a day on a conforming Symfony stack: composer require, register bundle, run baks:assets:install, generate and review a Doctrine migration, migrate.
• No published configuration reference, no API surface docs, no CHANGELOG beyond version-restating release notes (v7.4.6 contains the text "v7.4.6"). Integration effort is therefore dominated by reverse-engineering vendor/baks-dev/users-profile-balance/src, not by writing glue code.
• Composer script injection (auto-scripts, post-install-cmd, post-update-cmd) must be reconciled with our existing pipeline; baks:cache:clear in a post-install hook is a build-time side effect we should not accept blindly in CI.

Technical risk

Key questions (owner: TPM, answered before any commitment)

1. Are we actually a Symfony shop for the target service? If Laravel — is a port acceptable, or do we stop here?
2. Is balance mutation atomic and idempotent? Does it use transactions, row locks, or optimistic versioning? What happens on concurrent debits?
3. Can a balance go negative? Is there a floor, an overdraft policy, or a validation hook?
4. Is there an immutable transaction/audit history, or only a mutable current-value column? Can we reconstruct "why is this user at 50"?
5. Are multiple balance types per profile supported (points vs. credits), or is the model monolithic?
6. Is there an expiry, hold/reserve, or reversal primitive — or must we build all three?
7. Multi-tenancy: any tenant scoping, or must we wrap it?
8. What is the authorization model? Does the package enforce that a caller may only mutate its own profile's balance, or is that entirely on us?
9. What is the test coverage behind the documented --group=users-profile-balance phpunit run, and does it cover concurrency and boundary values?
10. What is the maintainer's support posture and release cadence, and what is our fork/patch policy if upstream stalls?
11. Upgrade policy: is 7.x semver-honest, and is there an UPGRADE.md?

Integration Approach

Stack fit — decision gate first

Run a single gate before any engineering time is booked: confirm the target service's framework. The two outcomes are asymmetric and should be presented that way.

• Symfony 6/7 + Doctrine + PHP 8.4 → conditional go. Package is architecturally appropriate; risk is process maturity, not fit.
• Laravel → default no, unless a named owner commits to either (a) an adapter with Doctrine bridging, or (b) a fork-and-port into Eloquent. Estimate that as a 1–2 sprint build with ongoing ownership, at which point the "buy vs. build" argument in the earlier pitch collapses — we would be building, just with a head start.

Migration path (assumes Symfony go)

1. Schema audit and dry run. Inventory existing balance/credit columns and any user_id + value tables. Run doctrine:migrations:diff and inspect the generated SQL before applying. Never let the package author our migration unattended.
2. Backfill design. Map current balance storage into the package's table; define the source of truth during transition and a reconciliation query that must return zero drift nightly.
3. Shadow mode. Dual-write (legacy + package) in staging and one internal environment; compare reads on every request path that consults balance. Zero mismatches for a defined window before any user-visible cutover.
4. Pilot. Single feature, single user segment, feature-flagged, with legacy column retained as the rollback path.
5. Cutover and decommission. Remove dual-write only after one full billing/credit cycle with clean reconciliation.

Compatibility work

• Verify PHP 8.4 availability across local, CI, staging, production container base image, and any serverless runtime — this is the most likely hard blocker and is cheap to confirm early.
• Align doctrine/migrations versions; a major-version skew will silently change migration generation behaviour.
• Merge auto-scripts into our existing Composer script block rather than replacing it; explicitly decide whether baks:cache:clear belongs in post-install-cmd for CI images.
• Pin the exact version in composer.lock; add a Renovate/Dependabot rule requiring manual review of every 7.4.x bump with a vendor-source diff.

Sequencing (TPM-owned plan)

Operational Impact

Maintenance

• Realistic ongoing cost: ~4–8 engineer-hours per month for a healthy integration (upgrades, vendored patches, reconciliation job), plus a one-time fork if upstream stalls. Budget the fork as the base case, not the exception, given zero dependents and no changelog discipline.
• Strongly recommend vendoring or maintaining a private mirror so an upstream deletion or force-push cannot break our build.
• Assign a named code owner for the balance domain. This package does not come with one implicitly.

Support

• Community-only. No SLAs, no security advisory process observed, no commercial backing. Escalation path is our own fork.
• Add it to the supply-chain watchlist (advisory feeds, GitHub security alerts on the fork). A balance-mutating dependency in a monetization path is a higher-tier dependency than its star count suggests.
• Document a 30-minute internal onboarding note covering install, migration, and the service API we actually use — this substitutes for the missing docs and prevents knowledge concentration.

Scaling

• Operations are database-bound with no published benchmarks. Expect: index on (profile_id, balance_type); transactions with row-level locking or optimistic versioning around every mutation; and a hot-row contention plan for high-traffic profiles (queue-and-serialize debits, or an append-only journal with a materialized balance).
• Caching the balance read is tempting and dangerous — define invalidation on every write path or do not cache.
• Assume single-tenant until proven otherwise; multi-tenant deployments need a wrapper with tenant scoping in every query, and that wrapper is ours to test.

Failure modes

Ramp-up

• Symfony engineer: ~1 day to productive use, mostly source reading. Laravel-only engineer: ~3–5 days, and only if an adapter already exists.
• Mitigation for the documentation gap: the spike must produce the artifact — a short internal README plus a concurrency test — so the second engineer costs hours, not days.
• Stakeholder framing to retire: the earlier "$50K saved, 70% cost reduction, launch in weeks" narrative does not survive contact with a 0-star, single-maintainer, Symfony-only, undocumented package on a Laravel stack. The defensible claim is narrower: "on a Symfony 8.4 service, this removes roughly 3–5 days of balance-CRUD work and shifts the risk from build time to dependency ownership." Recommend presenting that version, with the Phase 1–2 gate as the decision the business is actually being asked to fund.