PHPackages                             mrnamra/bracket-manager - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. mrnamra/bracket-manager

ActiveLibrary[Utility & Helpers](/categories/utility)

mrnamra/bracket-manager
=======================

Tournament bracket manager

v1.0.0(3mo ago)02↓93.8%MITPHPPHP ^8.0

Since Apr 4Pushed 2w ago1 watchersCompare

[ Source](https://github.com/MrNamra/bracket-manager)[ Packagist](https://packagist.org/packages/mrnamra/bracket-manager)[ RSS](/packages/mrnamra-bracket-manager/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (1)Versions (2)Used By (0)

Bracket Manager PHP Library
===========================

[](#bracket-manager-php-library)

[![Bracket Manager](image.png)](image.png)

A high-performance, developer-friendly PHP library for generating and managing tournament bracket data.

This library is **inspired by** [brackets-manager.js](https://github.com/Drarig29/brackets-manager.js) and its output is **fully JSON compatible** with [brackets-viewer.js](https://github.com/Drarig29/brackets-viewer.js), providing a robust PHP backend for tournament visualizations.

---

🚀 Key Features
--------------

[](#-key-features)

- 🏆 **Single & Double Elimination**: Native support for standard tournament structures.
- ⚡ **Automatic Advancement**: Intelligent winner/loser propagation, including seamless **BYE** handling.
- 🧬 **Advanced Seeding**: 7 built-in seeding algorithms (Inner-Outer, Natural, Reverse, etc.).
- 🧩 **Flexible Data Model**: Works with custom participant IDs and supports arbitrary metadata.
- 📦 **Composer Ready**: Easy integration into any modern PHP project.

---

🛠 Installation
--------------

[](#-installation)

Install the package via Composer:

```
composer require mrnamra/bracket-manager
```

---

📖 Quick Start
-------------

[](#-quick-start)

### 1. Initialize the Manager

[](#1-initialize-the-manager)

The `BracketManager` uses a bootstrapper to set up its internal repositories and services.

```
use MrNamra\BracketManager\BracketManager;

// Boot the manager with its default repositories
$manager = BracketManager::boot();
```

### 2. Creating a Single Elimination Bracket

[](#2-creating-a-single-elimination-bracket)

Perfect for quick knockout tournaments where one loss means elimination.

```
$stage = [
    'tournament_id' => 123,
    'type' => 'single_elimination',
    'seeding' => [
        '101' => 'Team Alpha',
        '102' => 'Team Beta',
        '103' => 'Team Gamma',
        '104' => 'Team Delta'
    ],
    'settings' => [
        'size' => 4,
        'seedOrdering' => ['inner_outer'],
        'grandFinal' => 'simple',
        'matchesChildCount' => 0
    ]
];

$result = $manager->create($stage);

// Output:
// Round 1: [101 vs 104], [102 vs 103]
// Final: [Winner vs Winner]
```

**Visual Structure:**

```
  Round 1          Final          Winner
+---------+      +---------+
| Alpha   |--+   |         |
+---------+  |   | TBD     |--+   +----------+
             +---|         |  |---| Champion |
+---------+  |   +---------+  |   +----------+
| Delta   |--+                |
+---------+      +---------+  |
                 |         |--+
+---------+      | TBD     |
| Beta    |--+   |         |
+---------+  |   +---------+
             +---|
+---------+  |
| Gamma   |--+
+---------+

```

### 3. Creating a Double Elimination Bracket

[](#3-creating-a-double-elimination-bracket)

Includes a Winners Bracket and a Losers Bracket, giving participants a second chance.

```
$stage['type'] = 'double_elimination';
$stage['settings']['size'] = 8;
$stage['settings']['grandFinal'] = 'double'; // Allows for a Grand Final Reset

$result = $manager->create($stage);
```

**Visual Structure:**

```
  Winners Bracket       Losers Bracket        Grand Final
+-----------------+   +-----------------+   +--------------+
| Round 1 (WB)    |   | Round 1 (LB)    |   | Winner (WB)  |
| Round 2 (WB)    |-->| Round 2 (LB)    |-->|      vs      |--> Champion
| Round 3 (WB)    |   | Round 3 (LB)    |   | Winner (LB)  |
+-----------------+   +-----------------+   +--------------+

```

---

📝 Configuration Schema
----------------------

[](#-configuration-schema)

When calling `$manager->create($stage)`, the following structure is used:

### Stage Configuration (`$stage`)

[](#stage-configuration-stage)

KeyTypeRequiredDescription`tournament_id``int`**Yes**ID of the parent tournament.`type``string`**Yes**`single_elimination` or `double_elimination`.`seeding``array`**Yes**Key-Value pairs: `['ID' => 'Name']`.`settings``array`**Yes**See Settings table below.`id``int`NoInternal stage ID (defaults to 0).`name``string`NoDisplay name (defaults to "Stage").`metadata``array`NoCustom data preserved in the result.### Settings Configuration (`settings`)

[](#settings-configuration-settings)

KeyTypeRequiredDescription`size``int`**Yes**Total slots (must be power of 2, e.g., 4, 8, 16).`seedOrdering``array`**Yes**Array containing one of the Seeding types.`grandFinal``string`**Yes**`simple`, `none`, or `double` (DE only).`matchesChildCount``int`**Yes**Sub-match count (usually 0 for standard).---

🧬 Seeding Algorithms
--------------------

[](#-seeding-algorithms)

Specify the algorithm in `settings['seedOrdering']` (e.g., `['inner_outer']`):

1. `natural`: Standard 1-2, 3-4 progression.
2. `inner_outer`: Traditional bracket seeding (1-8, 4-5, 2-7, 3-6).
3. `reverse`: 8-7, 6-5 progression.
4. `half_shift`: Rotational seeding for variety.
5. `reverse_half_shift`: Inverted rotational seeding.
6. `pair_flip`: Flips adjacent pairs.
7. `half_shift_inner_outer`: Hybrid approach.

---

🔄 Updating Scores & Advancement
-----------------------------------

[](#-updating-scores--advancement)

The library handles the complexity of advancing winners and dropping losers.

```
// Existing tournament data (as array)
$currentData = $result->toArray();

// Update Match ID 0 with scores
$scoreUpdate = [
    'id' => 0,
    'opponent1' => ['score' => 2],
    'opponent2' => ['score' => 1]
];

// Result will automatically advance the winner
$updatedResult = $manager->update($currentData, $scoreUpdate);

// Get fresh JSON for the frontend
$json = $updatedResult->getJson();
```

### Match Status Codes

[](#match-status-codes)

The result uses standardized status codes compatible with the `brackets-viewer.js` UI:

- `0`: **Locked** - Dependencies (previous rounds) are not yet finished.
- `1`: **Waiting** - One participant is ready, waiting for the other.
- `2`: **Ready** - Both participants are ready to play.
- `3`: **Running** - The match is currently in progress.
- `4`: **Completed** - Match is finished; winner has advanced.

---

🏆 Credits & License
-----------------------

[](#-credits--license)

Developed with ❤️ by **MrNamra**.

This project is licensed under the **MIT License**. See the `LICENSE` file for details.

###  Health Score

36

—

LowBetter than 79% of packages

Maintenance91

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity39

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

93d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/18a34b79fb2a1829620c649f1359cb4fbb3c0f02b4a56e0929adcdc75916a571?d=identicon)[mrnamra](/maintainers/mrnamra)

---

Top Contributors

[![MrNamra](https://avatars.githubusercontent.com/u/168954031?v=4)](https://github.com/MrNamra "MrNamra (28 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/mrnamra-bracket-manager/health.svg)

```
[![Health](https://phpackages.com/badges/mrnamra-bracket-manager/health.svg)](https://phpackages.com/packages/mrnamra-bracket-manager)
```

###  Alternatives

[hiromi2424/collectionable

Collectionable plugin for CakePHP

172.3k](/packages/hiromi2424-collectionable)[96qbhy/hyid

hidden your id

152.4k](/packages/96qbhy-hyid)[nsd7/laravel-activitylog-ui

A Tailwind CSS powered UI for the Spatie/laravel-activitylog package that we all love!

171.0k](/packages/nsd7-laravel-activitylog-ui)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)