mrnamra/bracket-manager

Tournament bracket manager

v1.0.0 2026-04-04 06:24 UTC

Requires

• php: ^8.0

Requires (Dev)

• phpunit/phpunit: ^12.1

MIT

• MrNamra

README

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

This library is inspired by brackets-manager.js and its output is fully JSON compatible with brackets-viewer.js, providing a robust PHP backend for tournament visualizations.

🚀 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

Install the package via Composer:

composer require mrnamra/bracket-manager

📖 Quick Start

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

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

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

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

Stage Configuration ($stage)

Key	Type	Required	Description
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	No	Internal stage ID (defaults to 0).
name	string	No	Display name (defaults to "Stage").
metadata	array	No	Custom data preserved in the result.

Settings Configuration (settings)

Key	Type	Required	Description
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

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

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

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

Developed with ❤️ by MrNamra.

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