Task Balancer Laravel Package

Getting Started

• Install with composer require toplan/task-balancer and pin it (^1.0) — the last tagged release is June 2017, so treat it as a legacy dependency. Run your test suite on your target PHP version immediately after installing; PHP 8.1+ compatibility is the first thing to verify.
• The repository is listed as unknown in the package metadata, so take the README/Packagist page as the source of truth for class and method names. The mental model is nginx: you register a task (the unit of work), a set of workers (upstreams), and a strategy/driver (round-robin/polling, weighted, random, least-used) that chooses which worker handles the task.
• Read first: the basic usage example, then the driver/strategy classes (that's where the actual "balancing" lives), then the Task/Worker classes to see how data is handed to a worker.
• First use case in a Laravel app: an Artisan command or queued job that must hand units of work to one of several interchangeable runnables — e.g. fanning image conversions across a pool of processors, or picking among several equivalent external API accounts. Keep it in app/Console/Commands or a small service class; do not wire it into normal HTTP request handling.
• It is a plain PSR-4 PHP library, not a Laravel package: there is no service provider, facade, or config file to publish. You register it yourself if you want container bindings.

Illustrative shape (confirm names against the README):

$task = new Task($payload);
$task->worker('worker-a', fn ($t) => /* ... */);
$task->worker('worker-b', fn ($t) => /* ... */);
$task->driver('polling');   // round-robin-ish
(new Balancer())->addTask($task)->start();

Implementation Patterns

• Wrap it. Create a TaskBalancerService that exposes your domain verbs (dispatchImageJob(), pickApiClient()) and hides the package API. Bind it as a singleton in a service provider only if it's stateless; otherwise resolve a fresh instance per job.
• Workers as thin adapters. Each worker should be a small callable that delegates to a Laravel job, a console command, or an HTTP client. Keep business logic out of the worker registration so a future replacement library is a one-file change.
• Weighted workers mirror nginx's weight=. Use them when upstreams are not equal — a higher-rate-limit API account gets a bigger weight. This is the pattern that maps most directly to the package's advertised "like nginx" behaviour.
• Deterministic strategy in tests. Inject a fixed round-robin driver or a stub worker so tests don't depend on random selection; assert that a worker was invoked and with the right payload, not which one.
• Pair with Laravel queues, don't replace them. For production job distribution, Redis queues + Horizon already balance work across workers. Use this package for in-process selection among heterogeneous workers in CLI/batch tooling, where you deliberately want a strategy object deciding the target.
• Observability wrapper. Log the chosen worker name and emit a Laravel event on each selection; that's the only visibility you'll get, because the library won't integrate with your logging or Context out of the box.
• Failover pattern. Mark a worker unhealthy on exception, remove it from the pool, and re-balance; the package provides the selection primitive, not retry/health-check semantics.

Gotchas and Tips

• Abandoned since 2017. No PHP 8 types, possibly deprecated constructs. If it won't run, a 30-line round-robin selector in a service class is often a better outcome than patching vendor code.
• "Load balancing" ≠ nginx. PHP is single-process unless you fork or queue. This library chooses a worker; it does not execute workers concurrently. Don't assume throughput gains from installing it.
• No built-in health checks or retries unless the driver provides them. Wrap every worker call in try/catch, implement your own failover, and don't let a worker exception silently drop the task.
• Long-lived state. Round-robin cursors often live on a singleton. In Octane or queue workers, that counter persists across requests/jobs — rebind or reset per unit of work if even distribution matters.
• Request lifecycle hazard. Long workers will hit max_execution_time and tie up an FPM worker. Keep this out of web controllers.
• Strategy naming quirks. Driver names are usually plain strings and may be case-sensitive; verify the default driver and whether weights are set via constructor, setter, or worker name — the README is the only reference, so encode it in a test.
• Debugging. If selection looks wrong, dump the registered worker list and the driver's internal pointer. There's no profiler integration; a quick dd() in your wrapper is the fastest path.
• Extension points. A custom driver/strategy class is the clean way to add least-connections or sticky routing. Prefer that over editing vendor/, and pin the version in composer.json so a fork/rename doesn't break installs.
• Recommendation. For typical Laravel apps this is niche tooling; adopt it only where the nginx-style selection model genuinely simplifies your CLI batch flow, and keep an abstraction layer so swapping it out later is cheap.