Laravel Pay Pocket Laravel Package

Technical Evaluation

toneflix/laravel-pay-pocket is a Laravel wallet/balance abstraction (publishable config + migrations, a service provider, and model traits for ledger-style account balances). Architecturally it fits Laravel applications that need an in-app wallet/ledger primitive without adopting a full payment orchestration platform — it is a library, not a service, so it inherits the host app's database, queue, and caching characteristics.

Release 4.0.0 is a hard-breaking release on three axes:

1. Vendor/package identity change — toneflix-code/laravel-pay-pocket → toneflix/laravel-pay-pocket.
2. Namespace change — ToneflixCode\LaravelPayPocket → Toneflix\LaravelPayPocket, which affects application imports, the published config, and any published migrations/models that reference the namespace, plus any polymorphic/morph-map or serialized class names persisted in the database or in queued job payloads.
3. Platform floor raise — PHP ^8.3|^8.4 and Illuminate ^12.0|^13.0. This drops Laravel 10/11 and PHP 8.1/8.2 consumers entirely; there is no compatibility shim or bridge release.

Integration feasibility is straightforward on a modern stack (composer remove / composer require, then a namespace sweep), but the blast radius is wider than the README's two-line upgrade implies: the vendor rename breaks Composer lockfiles, internal allowlists/private mirrors, SBOM and license-scanning entries, and any CI caching keyed on the old vendor name.

Technical risks worth flagging:

• Support cliff for 3.x. The notes give no statement on security/maintenance coverage for 3.0.1. If the team must stay on Laravel 11 for a quarter, there is no clear patched path.
• Laravel 13 adjacency. Shipping Laravel 13 support in the same release that renames the vendor means the only supported upgrade path also moves the project onto a very new framework major. Those two risks are coupled and cannot be staged independently.
• Governance/supply chain. A vendor move for a package that handles money movement warrants provenance verification: confirm the new Packagist entry, repository transfer/redirect, and maintainer identity before pinning. Treat it as a supply-chain review, not just a version bump.
• Ledger semantics unchanged. These are packaging and platform changes; no evidence of fixes to concurrency handling around balance mutation. Existing correctness risk in the wallet flow carries forward untouched.

Key questions for the maintainer:

• Is 3.x receiving security fixes, and for how long?
• Is the old Packagist name an alias/abandoned-with-redirect, or will it hard-fail?
• Are there database-level references to the old namespace (morph maps, stored model class strings, serialized job payloads) that require a data migration?
• What is the supported upgrade path for apps on Laravel 11 — is there a 3.1 with backported fixes?

Integration Approach

Stack fit. Suitable only for services already on Laravel 12 with PHP 8.3+, or services that can complete a framework upgrade first. Any service on Laravel 10/11 or PHP 8.1/8.2 is blocked and should not attempt this release.

Migration path. The realistic path is a coordinated, single-PR upgrade per service:

1. Upgrade PHP to 8.3+ and Laravel to 12 (or 13) first, on the old package version, and ship that independently — do not stack the framework major and the package major in one release.
2. Remove the old requirement, add toneflix/laravel-pay-pocket:^4.0.
3. Global namespace replacement across app/, config/, database/migrations/, tests/, and any seeders/factories.
4. Re-publish the config (vendor:publish) and diff against the existing published file — do not blindly overwrite; local customizations (table names, models, currency config) must be reconciled.
5. Clear and rebuild config/route/opcache caches; composer dump-autoload -o.

Compatibility. Watch specifically for:

• Persisted class names — if the package or host app uses morph maps or stores model class strings, the rename needs a data backfill, not just a code change.
• Queued jobs already enqueued at deploy time that reference old-namespace classes will fail to unserialize (__PHP_Incomplete_Class). Drain queues before cutover, or accept and replay failures.
• Published migrations already run — the rename must not alter migration file names or the migrations table entries.

Sequencing. Pin ^3.0 and freeze feature work on the wallet module while the framework upgrade lands. Then do the package bump in a dedicated release behind a feature flag if the wallet is on a critical path. Roll out to a staging environment with a production-shaped dataset (real transaction volume, not fixtures) before any canary. Where possible, use a blue/green deploy rather than rolling, since a rolling deploy will briefly run old and new namespaces against the same database.

Operational Impact

Maintenance. The vendor move is the durable cost: internal dependency inventories, SBOM entries, license scans, artifact allowlists, private mirror configs, and any security-alert routing keyed on toneflix-code/* must be updated. If the organization has a package approval process, the new vendor name is a new dependency and may need re-approval even though the code is unchanged.

Support. Single-maintainer, low-visibility package handling money-adjacent logic. The README and CI matrix were updated, which is a good signal, but there is no stated LTS or deprecation policy, and the 3.x support window is undocumented. Budget for the possibility of forking or vendoring if the project stalls.

Scaling. Unchanged by this release — the package still executes balance mutations inside the host application's transaction boundaries. Concurrency behavior under load (row locking, deadlock retries, idempotency of wallet operations) is a pre-existing concern and should be validated with a load test against realistic contention, not assumed from the version bump. If wallet writes are high-frequency, confirm index coverage on the ledger tables in the published migrations.

Failure modes to plan for.

• Post-deploy Class not found from stale opcache/config cache or un-swept namespace references.
• Silent config drift from overwriting a customized published config during re-publish.
• Failed queued jobs carrying old-namespace serialized payloads.
• Mixed-version window during rolling deploys producing inconsistent writes.
• Composer resolution failures in CI where the old vendor name is cached or pinned in a lockfile.

Ramp-up. Low conceptual learning curve — engineers need roughly half a day to a day per service for the namespace sweep, config reconciliation, and regression testing of deposit/withdraw/transfer/balance flows. The real cost is coordination: the framework upgrade must land first, which makes this a multi-week program for any organization with several Laravel services rather than a single sprint task. Recommend one engineer own the migration playbook across services so the config-diff and morph-map checks are done identically everywhere.