{"id":20540567,"url":"https://github.com/utopia-php/balancer","last_synced_at":"2025-09-02T13:08:59.648Z","repository":{"id":62162790,"uuid":"557720786","full_name":"utopia-php/balancer","owner":"utopia-php","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-31T12:01:11.000Z","size":65,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-07-19T17:29:00.959Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/utopia-php.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-10-26T07:15:29.000Z","updated_at":"2025-03-31T12:01:16.000Z","dependencies_parsed_at":"2025-04-14T08:38:35.749Z","dependency_job_id":"76ec5f2e-4511-431d-9848-6a107d0cc22e","html_url":"https://github.com/utopia-php/balancer","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/utopia-php/balancer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/utopia-php%2Fbalancer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/utopia-php%2Fbalancer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/utopia-php%2Fbalancer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/utopia-php%2Fbalancer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/utopia-php","download_url":"https://codeload.github.com/utopia-php/balancer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/utopia-php%2Fbalancer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273287698,"owners_count":25078581,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-02T02:00:09.530Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-16T01:16:13.866Z","updated_at":"2025-09-02T13:08:59.619Z","avatar_url":"https://github.com/utopia-php.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Utopia Balancer\n\n[![Build Status](https://github.com/utopia-php/balancer/actions/workflows/tester.yml/badge.svg)](https://github.com/utopia-php/balancer/actions/workflows/tester.yml)\n[![Total Downloads](https://img.shields.io/packagist/dt/utopia-php/database.svg)](https://packagist.org/packages/utopia-php/balancer)\n[![Discord](https://img.shields.io/discord/564160730845151244?label=discord)](https://appwrite.io/discord)\n\nUtopia Balancer library is simple and lite library for balancing choices between multiple options. This library is aiming to be as simple and easy to learn and use. This library is maintained by the [Appwrite team](https://appwrite.io).\n\nAlthough this library is part of the [Utopia Framework](https://github.com/utopia-php/framework) project it is dependency free and can be used as standalone with any other PHP project or framework.\n\n## Getting Started\n\nInstall using composer:\n```bash\ncomposer require utopia-php/balancer\n```\n\nBalancer supports multiple algorithms. Each picks option differently, and may have different set of methods available for configuration.\n\n### Balancer Algorithms\n\n1. Random\n\n`Random` algorithm pick option randomly. The same option could be picked multiple times in a row. Example:\n\n```php\n\u003c?php\n\nrequire_once '../vendor/autoload.php';\n\nuse Utopia\\Balancer\\Algorithm\\Random;\nuse Utopia\\Balancer\\Balancer;\nuse Utopia\\Balancer\\Option;\n\n$balancer = new Balancer(new Random());\n\n$balancer-\u003eaddFilter(fn (Option $option) =\u003e $option-\u003egetState('online', false) === true);\n\n$balancer\n    -\u003eaddOption(new Option([ 'hostname' =\u003e 'proxy-1', 'online' =\u003e true ]))\n    -\u003eaddOption(new Option([ 'hostname' =\u003e 'proxy-2', 'online' =\u003e false ]))\n    -\u003eaddOption(new Option([ 'hostname' =\u003e 'proxy-3', 'online' =\u003e true ]));\n\nvar_dump($balancer-\u003erun());\nvar_dump($balancer-\u003erun());\nvar_dump($balancer-\u003erun());\n```\n\n2. First and Last\n\n`First` algorithm always picks first option. Similiarly, `Last` algorithm always picks last option. Example:\n\n```php\n\u003c?php\n\nrequire_once '../vendor/autoload.php';\n\nuse Utopia\\Balancer\\Algorithm\\First;\nuse Utopia\\Balancer\\Algorithm\\Last;\nuse Utopia\\Balancer\\Balancer;\nuse Utopia\\Balancer\\Option;\n\n$balancer = new Balancer(new First());\n\n$balancer\n    -\u003eaddOption(new Option([ 'runtime' =\u003e 'PHP' ]))\n    -\u003eaddOption(new Option([ 'runtime' =\u003e 'JavaScript' ]))\n    -\u003eaddOption(new Option([ 'runtime' =\u003e 'Java' ]));\n\nvar_dump($balancer-\u003erun());\n\n$balancer = new Balancer(new Last());\n\n$balancer\n    -\u003eaddOption(new Option([ 'runtime' =\u003e 'PHP' ]))\n    -\u003eaddOption(new Option([ 'runtime' =\u003e 'JavaScript' ]))\n    -\u003eaddOption(new Option([ 'runtime' =\u003e 'Java' ]));\n\nvar_dump($balancer-\u003erun());\n```\n\n3. Round Robin\n\n`RoundRobin` algorithm cycles over all options starting first. Once algorithm cycles over all options, it resets back to the beginning. Example:\n\n```php\n\u003c?php\n\nrequire_once '../vendor/autoload.php';\n\nuse Utopia\\Balancer\\Algorithm\\RoundRobin;\nuse Utopia\\Balancer\\Balancer;\nuse Utopia\\Balancer\\Option;\n\n$balancer = new Balancer(new RoundRobin(-1));\n\n$balancer-\u003eaddFilter(fn (Option $option) =\u003e $option-\u003egetState('online', false) === true);\n\n$balancer\n    -\u003eaddOption(new Option([ 'dataCenter' =\u003e 'fra-1' ]))\n    -\u003eaddOption(new Option([ 'dataCenter' =\u003e 'fra-2' ]))\n    -\u003eaddOption(new Option([ 'dataCenter' =\u003e 'lon-1' ]));\n\nvar_dump($balancer-\u003erun()); // fra-1\nvar_dump($balancer-\u003erun()); // fra-2\nvar_dump($balancer-\u003erun()); // lon-1\nvar_dump($balancer-\u003erun()); // fra-1\nvar_dump($balancer-\u003erun()); // fra-2\n```\n\nWhen using `RoundRobin` in concurrency model, make sure to store index in atomic way. Example:\n\n```php\n\u003c?php\n\nrequire_once '../vendor/autoload.php';\n\nuse Utopia\\Balancer\\Algorithm\\RoundRobin;\nuse Utopia\\Balancer\\Balancer;\nuse Utopia\\Balancer\\Option;\n\n$atomic = new Atomic(-1); // Some atomic implementation, for example: https://openswoole.com/docs/modules/swoole-atomic\n\nfunction onRequest() {\n    $lastIndex = $atomic-\u003eget();\n    $algo = new RoundRobin($lastIndex);\n    $balancer = new Balancer();\n\n    $balancer-\u003eaddFilter(fn (Option $option) =\u003e $option-\u003egetState('online', false) === true);\n\n    $balancer\n        -\u003eaddOption(new Option([ 'dataCenter' =\u003e 'fra-1' ]))\n        -\u003eaddOption(new Option([ 'dataCenter' =\u003e 'fra-2' ]))\n        -\u003eaddOption(new Option([ 'dataCenter' =\u003e 'lon-1' ]));\n\n    var_dump($balancer-\u003erun());\n\n    $atomic-\u003ecmpset($lastIndex, $algo-\u003egetIndex());\n}\n```\n\n### Balancer Group\n\nIf balancer filters cause balancer to have no options to pick from, `null` will be returned. More often then not, you will need a backup logic for this scenario. You can use `Group` to create a group of multiple balancers and if one fails, next can be used as fallback. Notice `Group` tries balances in order you added them.\n\n```php\n\u003c?php\n\nrequire_once '../vendor/autoload.php';\n\nuse Utopia\\Balancer\\Algorithm\\First;\nuse Utopia\\Balancer\\Balancer;\nuse Utopia\\Balancer\\Group;\nuse Utopia\\Balancer\\Option;\n\n// Prepare options where each has high CPU load\n$options = [\n    new Option([ 'dataCenter' =\u003e 'fra-1', 'cpu' =\u003e 91 ]),\n    new Option([ 'dataCenter' =\u003e 'fra-2', 'cpu' =\u003e 95 ]),\n    new Option([ 'dataCenter' =\u003e 'lon-1', 'cpu' =\u003e 87 ]),\n];\n\n// Prepare balancer that allows only low CPU load options\n$balancer1 = new Balancer(new First());\n$balancer1-\u003eaddFilter(fn ($option) =\u003e $option-\u003egetState('cpu') \u003c 80);\n\n// Prepare balancer that allows all options\n$balancer2 = new Balancer(new First());\n\n// Add options to both balancers\nforeach ($options as $option) {\n    $balancer1-\u003eaddOption($option);\n    $balancer2-\u003eaddOption($option);\n}\n\n// Prepare group with both balancers\n$group = new Group();\n$group\n    -\u003eadd($balancer1)\n    -\u003eadd($balancer2);\n\n// Run group to get option\n$option = $group-\u003erun() ?? new Option([]);\n\n\\var_dump($option);\n// We got fra-1 option. First balancer filtered out all options, but second balancer allowed any, and First algorithm picked first option\n```\n\n## System Requirements\n\nUtopia Framework requires PHP 8.0 or later. We recommend using the latest PHP version whenever possible.\n\n## Copyright and license\n\nThe MIT License (MIT) [http://www.opensource.org/licenses/mit-license.php](http://www.opensource.org/licenses/mit-license.php)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Futopia-php%2Fbalancer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Futopia-php%2Fbalancer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Futopia-php%2Fbalancer/lists"}