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)

Settings Configuration (settings)

🧬 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.