Credit Bundle Laravel Package

Technical Evaluation

What 1.0.1 actually tells us. The release notes for tourze/credit-bundle 1.0.1 contain only a compare link (1.0.0...1.0.1) with no changelog body. In TPM terms this is a zero-signal patch release: semver implies bug-fix-only, but we cannot confirm whether it contains behavioural corrections to balance calculations, transaction handling, or container wiring. Treat 1.0.1 as probably low-risk but unverified, and do not adopt it on the assumption that "patch = safe" without diffing the compare view ourselves.

Architecture fit. The tourze/*-bundle family is a Symfony/Doctrine-oriented ecosystem (bundle = DI extension + Doctrine entities + services). If credit-bundle follows that pattern, it fits a Symfony application natively and fits Laravel only through adaptation. Before any design work, confirm which of these it actually is:

• a framework-agnostic domain library (entities/value objects + a ledger service) — good fit, thin adapter only; or
• a Symfony bundle (CompilerPass, services.yaml, Doctrine mappings) — usable in Laravel but requires us to own the wiring, mapping, and persistence layer.

The domain itself (credit/points accounts, balances, debit/credit transactions) is a good architectural fit for most product stacks: it is a bounded context that can sit behind a repository interface and be swapped later.

Integration feasibility. Composer-installable, so mechanical integration is easy; semantic integration is the work. Expect to spend effort on: container/service-provider bridging, ORM mapping (Doctrine annotations/attributes → Eloquent or a separate Doctrine connection), transaction boundaries, and configuration translation. Feasible for a small, well-isolated module; not feasible as a drop-in for a core billing path without an adapter layer.

Technical risk.

• Maturity: 1.0.x with rapid patch cadence and no published changelog = pre-stabilisation behaviour. Expect API churn across minors.
• Bus factor: single-maintainer package; no commercial support path evident.
• Correctness risk is financial: credit balances are money-adjacent. Precision (integer minor units vs float), idempotency of credit/debit operations, and concurrency (row locking / optimistic versioning) are the three things to audit in source, not in docs.
• Auditability: confirm an append-only transaction log exists; a mutable balance column alone is disqualifying for anything customer-facing.
• Documentation: likely sparse and possibly Chinese-language; budget for source-reading.

Key questions to answer before commit.

1. Does it own persistence (entities/migrations) or operate on our models?
2. Is there an immutable ledger, or only a balance field?
3. How are concurrent debits serialised — DB lock, version column, or nothing?
4. Are amounts integers in minor units? Any float in the value objects?
5. Idempotency keys on write operations? Retry semantics?
6. Does 1.0.1 change behaviour, or only metadata/CI? (Read the diff.)
7. Test coverage and CI status; are there integration tests against a real DB?
8. Expiry, refund, and negative-balance policy — modelled, or left to the caller?

Integration Approach

Stack fit. Viable for Laravel 10/11 on PHP 8.1+ if isolated. Do not let bundle types (Doctrine entities, Symfony service IDs) leak into controllers, jobs, or domain code. Target shape: App\Credit\* interfaces owned by us → TourzeCreditAdapter implementation → package. That preserves exit optionality and lets us swap in a first-party ledger if 1.x churns.

Migration path.

1. Spike (1–2 days): install 1.0.1 in a scratch Laravel app, exercise open/debit/credit/balance, read the 1.0.0→1.0.1 diff, and record actual behaviour vs. assumptions.
2. Adapter: wrap the package behind our own repository/service contract; map its persistence to either Eloquent or a dedicated Doctrine connection — pick one and document why.
3. Pilot: one non-critical feature (e.g., promotional credits or referral points), never the primary wallet.
4. Harden: add our own idempotency wrapper and reconciliation job regardless of what the package provides.
5. Promote only after a full accounting cycle reconciles to zero variance.

Compatibility. Pin exactly ("tourze/credit-bundle": "1.0.1"), commit the lockfile, and gate upgrades behind the diff review. Verify PHP constraint against our runtime, and check whether it pulls a Doctrine version that conflicts with existing Laravel/DB tooling. Watch for transitive Symfony packages entering the dependency graph — that is the main hidden cost.

Sequencing. Diff review → spike → adapter contract approved → pilot → reconciliation/observability → broader rollout. Each gate is a go/no-go; the spike is cheap and answers most of the Technical Evaluation questions above.

Operational Impact

Maintenance. We will effectively co-maintain this: pinning versions, reviewing upstream diffs ourselves (since changelogs are empty), and likely patching locally via a fork or composer patch plugin. Budget a standing small allocation (~0.1 FTE) for dependency stewardship. Assume no LTS; 1.0.x will move.

Support. Community/GitHub-issues only, no SLA, no vendor escalation. For a financial-adjacent component that is a real constraint — mitigate by keeping the blast radius small and the adapter thin, so a replacement is a contained project rather than a rewrite.

Scaling. The ledger is append-only and grows monotonically; plan for it from day one:

• Index on (account_id, created_at) and on idempotency key.
• Balance as a derived/materialised value, not the source of truth.
• Partition or archive transactions past the reporting window; keep hot data small.
• Read replicas for balance queries only if staleness is acceptable — for spend decisions, read primary. The package will not solve this for us; it is our schema and our operations.

Failure modes to instrument.

• Double-spend under concurrent debits — detect via reconciliation, prevent via DB-level locking.
• Non-idempotent retries on queue jobs — wrap every write in our own idempotency key.
• Precision drift if any float is involved — assert integer minor units at the boundary.
• Silent balance corruption from partial transactions — enforce single-transaction semantics per operation.
• Upstream breakage on a minor bump — caught only by pinned versions plus a contract test suite we own.

Ramp-up. Low for a Laravel developer to call the API; moderate-to-high to operate it, because the bundle conventions (DI, Doctrine mapping, config) are Symfony-shaped and unfamiliar to a typical Laravel team. Plan: one engineer does the spike and writes a short internal note covering wiring, transaction boundaries, and the reconciliation procedure. That note, not the upstream docs, becomes the team's onboarding artifact.

TPM recommendation for 1.0.1. No evidence of breaking change; no evidence of anything, given the empty changelog. Approve a time-boxed spike on 1.0.1, keep it out of the critical payment path, and make the 1.0.0→1.0.1 diff review a precondition for the go/no-go. Re-assess when a release ships an actual changelog or when the spike answers the eight questions above.