Task Balancer Laravel Package

Technical Evaluation

What the package is. toplan/task-balancer is a framework-agnostic PHP library that implements client-side load balancing strategies for dispatching work to a set of targets — the nginx analogy in the description points to weighted/round-robin style selection rather than HTTP proxying. It ships as a Composer package under MIT, with a single release dated June 2017 and 47 GitHub stars.

Architecture fit. Superficially this overlaps with capabilities Laravel already provides: the queue system (Redis/SQS/database drivers), Horizon for worker supervision and balancing, and Supervisor at the process level. The package is only architecturally justified where those do not apply — dispatching to heterogeneous downstream targets (multiple DB shards, multiple upstream API endpoints, multiple worker pools with different capacity) and needing weighting or health-aware selection inside application code. If the underlying need is "our queue is not keeping up," this package is the wrong tool and should be rejected in favor of Horizon/tuning. If the need is "route each unit of work to one of N downstream targets according to capacity," it is a candidate. It is not a Laravel package in the conventional sense — expect no service provider, facade, config publishing, or container bindings; any framework integration is ours to write.

Integration feasibility. Low-to-moderate. Composer installation is trivial; the real work is (a) confirming the code runs on our PHP runtime, and (b) wrapping it so its types do not leak into domain code. A 2017 release almost certainly predates PHP 8 typed properties, named arguments, and stricter deprecation handling — verify against our PHP matrix before anything else, and check composer.json constraints against our illuminate/* and PSR versions. Expect conflicts with modern Laravel dependency graphs.

Technical risk. High on sustainability. Eight years dormant, one minor release, 47 stars, effectively a single-maintainer project with no visible issue triage. We would be adopting code that nobody is patching. Security risk is low in absolute terms (small, in-process algorithm library with minimal attack surface), but transitive dependency advisories are unmanaged. Correctness risk is medium: load-balancing semantics have deceptively sharp edges — health-check staleness, retry/backoff interaction with selection, counter drift, behavior when all targets are marked down. Legal risk is clean: MIT permits forking, vendoring, and internal modification.

Key questions to answer before committing:

1. Which concrete routing decision in our system does this replace, and does Laravel's queue or an actual L4/L7 proxy already solve it?
2. Does the library support the strategy we need (weighted round-robin, least-connections, consistent hashing) with health awareness, or only naive round-robin?
3. Does it run on our PHP version and framework version, verified by a test harness rather than a README claim?
4. What state does selection depend on — per-process counters only, or externally supplied target health? Is that state correct under PHP-FPM's shared-nothing model?
5. What is the failure behavior when a target is unhealthy or the balancer's state is empty?
6. Are we prepared to own the code permanently, including a fork and a named maintainer?

Integration Approach

Stack fit. Place it behind an application-level port — a TargetSelector/Dispatcher interface defined in our domain — with the package as one adapter implementation. Do not inject its classes into controllers, jobs, or models. In Laravel terms: bind the adapter in a service provider, configure target pools in config/, and expose it through constructor injection. It belongs in the service/infrastructure layer, not middleware and not as a queue driver.

Build vs. adopt. Given the dormancy and low adoption, the honest options are: (a) adopt as a dependency with a wrapper, (b) fork-and-vendor into our own namespace, or (c) reimplement the needed strategy in ~100–200 lines with full test coverage. For plain weighted round-robin, (c) is almost always cheaper over a three-year horizon and removes the supply-chain question entirely. Reserve (a)/(b) for cases where the package's semantics — health tracking, consistent hashing — are genuinely non-trivial and validated by the spike.

Migration path.

1. Spike (1–2 days): install in a scratch branch, run the PHP/Laravel compatibility matrix, exercise every strategy under load with failing targets, and read the source for retry and health semantics. Produce a one-page go/no-go.
2. Wrap: define the port interface; implement the adapter; write contract tests that the port must satisfy so any future implementation is drop-in.
3. Shadow: run the new selector alongside existing dispatch logic in one non-critical path, log the decisions, diff them, and confirm behavioral parity or documented intentional differences.
4. Canary: route a small slice of real traffic (5% → 25% → 100%) with rollback via config flag.
5. Contingency: if the spike or shadow stage surfaces compatibility problems, fall back to the internal implementation with no change to callers.

Compatibility. Pin an exact version or commit hash; add the package to a dependency-review list; run static analysis (PHPStan at high level) and the full PHP version matrix in CI before merge. Confirm PSR-4 autoloading and check for any global function or constant pollution.

Sequencing dependencies. The port interface and observability must land before the adapter — otherwise the first swap becomes a refactor. The config-driven pool definitions should be owned by whoever owns the target inventory, not the application team.

Operational Impact

Maintenance. We become the de facto maintainers. Budget a named owner, a quarterly review of the pinned commit, automated dependency scanning, and an annual "still needed?" check. A vendored fork adds merge-overhead every time a PHP version bump lands.

Support. There is no upstream to escalate to. Any defect becomes an internal incident with internal MTTR. That is acceptable for a small algorithm library; it is not acceptable if the library sits on a critical dispatch path with no fallback.

Scaling. The balancing logic is in-process and computationally free, but selection state is per-process. Under PHP-FPM or multi-container deployment, every worker balances independently and no global view exists. Round-robin and random are fine under that model; least-connections or load-aware weighting is not — those require shared state (Redis) or, better, delegating to real infrastructure (Nginx Plus, Envoy, HAProxy, or a managed LB). Do not expect this package to behave like a load balancer at the fleet level; it is a decision function inside one request.

Failure modes to instrument and runbook:

• Dead or degraded target continuing to receive work because health state is stale or never updated.
• All-targets-unhealthy behavior — silent fail-open to the first target versus a hard error; pin this down explicitly.
• Retry amplification: retries re-entering the selector and landing on the same target (no jitter/backoff awareness).
• Weight drift between config and actual target capacity, producing chronic hotspots.
• Counter skew after deploys or restarts, causing briefly uneven distribution.
• No circuit-breaking: a slow target keeps getting traffic until it fails outright.

Mitigations: per-target counters for dispatches, errors, and latency; alert on distribution deviation and on any target receiving zero traffic while marked healthy; config-driven weights with a change-review step.

Ramp-up. Conceptually small — a competent PHP engineer understands the strategies in under an hour. The real ramp-up is operational: on-call must know the failover semantics and where the pool configuration lives. Estimate a half-day of onboarding plus a written runbook, and require the port interface to be documented so the team is not learning package internals to debug production.

Bottom line for the TPM. The license and scope are fine, but the project's age and adoption profile make this a code sample, not a supply-chain dependency. Default to reimplementing the narrow strategy behind our own interface, using this package as a design reference; adopt or vendor it only if the compatibility spike proves PHP-8-era viability and the strategy is materially non-trivial. Either way, keep the interface in our codebase so the decision is reversible in days, not quarters.