Skip to main content

List Tournaments

The list tournaments method retrieves all available tournaments for a specific game. This is typically used to display available tournaments to players or to programmatically access tournament information.

Overview​

The getTournaments method:

  • Returns all tournaments configured for a specific game
  • Provides tournament metadata including names, IDs, and status
  • Returns an array of TournamentMeta objects
  • Handles empty results gracefully

Method Signature​

public function getTournaments(string $gameID): array

Parameters​

Required Parameters​

  • gameID (String) - The Game ID for which to retrieve tournaments
    • Must be a valid Moitribe Game ID
    • Cannot be empty

Return Value​

Returns an array of TournamentMeta objects:

  • Empty array - No tournaments found or game doesn't exist
  • Array with objects - Successfully retrieved tournaments

Each TournamentMeta object contains:

  • Tournament ID
  • Tournament name
  • Tournament status
  • Start/end dates
  • Prize information
  • Entry requirements

Basic Usage​

Get All Tournaments for a Game​

use Veniso\Moitribe\Sdk\modules\classes\MoitribeApi;

$moitribe = new MoitribeApi([
    'gameid' => 'your-game-id',
    'channelid' => 'your-channel-id',
    'playerid' => 'player-123'
]);

try {
    $tournaments = $moitribe->tournRequestsHandler->getTournaments('your-game-id');
    
    echo "Found " . count($tournaments) . " tournaments:\n";
    
    foreach ($tournaments as $tournament) {
        echo "- " . $tournament->getName() . " (ID: " . $tournament->getId() . ")\n";
        echo "  Status: " . $tournament->getStatus() . "\n";
        echo "  Start: " . $tournament->getStartDate() . "\n";
        echo "  End: " . $tournament->getEndDate() . "\n\n";
    }
    
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

Filter Active Tournaments Only​

function getActiveTournaments($gameId) {
    global $moitribe;
    
    try {
        $allTournaments = $moitribe->tournRequestsHandler->getTournaments($gameId);
        $activeTournaments = [];
        
        foreach ($allTournaments as $tournament) {
            if ($tournament->getStatus() === 'active') {
                $activeTournaments[] = $tournament;
            }
        }
        
        return $activeTournaments;
        
    } catch (Exception $e) {
        error_log("Error getting tournaments: " . $e->getMessage());
        return [];
    }
}

// Usage
$activeTournaments = getActiveTournaments('your-game-id');
echo "Active tournaments: " . count($activeTournaments) . "\n";

Integration Examples​

Tournament List Display​

function displayTournamentList($gameId) {
    global $moitribe;
    
    try {
        $tournaments = $moitribe->tournRequestsHandler->getTournaments($gameId);
        
        if (empty($tournaments)) {
            echo "<p>No tournaments available at the moment.</p>";
            return;
        }
        
        echo "<div class='tournament-list'>";
        echo "<h2>Available Tournaments</h2>";
        
        foreach ($tournaments as $tournament) {
            $statusClass = $tournament->getStatus() === 'active' ? 'active' : 'inactive';
            $canJoin = $tournament->getStatus() === 'active' && $tournament->canJoin();
            
            echo "<div class='tournament-item $statusClass'>";
            echo "<h3>" . htmlspecialchars($tournament->getName()) . "</h3>";
            echo "<p><strong>Status:</strong> " . ucfirst($tournament->getStatus()) . "</p>";
            echo "<p><strong>Start:</strong> " . date('M j, Y', strtotime($tournament->getStartDate())) . "</p>";
            echo "<p><strong>End:</strong> " . date('M j, Y', strtotime($tournament->getEndDate())) . "</p>";
            
            if ($tournament->getPrizePool()) {
                echo "<p><strong>Prize Pool:</strong> " . $tournament->getPrizePool() . "</p>";
            }
            
            if ($tournament->getEntryFee()) {
                echo "<p><strong>Entry Fee:</strong> " . $tournament->getEntryFee() . "</p>";
            }
            
            if ($canJoin) {
                echo "<button onclick='joinTournament(\"" . $tournament->getId() . "\")' class='join-btn'>Join Tournament</button>";
            } else {
                echo "<button disabled class='join-btn disabled'>" . getJoinButtonText($tournament->getStatus()) . "</button>";
            }
            
            echo "</div>";
        }
        
        echo "</div>";
        
    } catch (Exception $e) {
        echo "<div class='error'>Failed to load tournaments. Please try again later.</div>";
        error_log("Tournament list error: " . $e->getMessage());
    }
}

function getJoinButtonText($status) {
    switch ($status) {
        case 'upcoming':
            return 'Coming Soon';
        case 'ended':
            return 'Tournament Ended';
        case 'full':
            return 'Tournament Full';
        default:
            return 'Not Available';
    }
}

// Display on your page
displayTournamentList('your-game-id');

Tournament Selection for Game Integration​

class TournamentManager {
    private $moitribe;
    private $gameId;
    
    public function __construct($moitribe, $gameId) {
        $this->moitribe = $moitribe;
        $this->gameId = $gameId;
    }
    
    public function getTournamentOptions() {
        try {
            $tournaments = $this->moitribe->tournRequestsHandler->getTournaments($this->gameId);
            $options = [];
            
            foreach ($tournaments as $tournament) {
                if ($tournament->getStatus() === 'active') {
                    $options[$tournament->getId()] = [
                        'name' => $tournament->getName(),
                        'entry_fee' => $tournament->getEntryFee(),
                        'max_players' => $tournament->getMaxPlayers(),
                        'current_players' => $tournament->getCurrentPlayers()
                    ];
                }
            }
            
            return $options;
            
        } catch (Exception $e) {
            error_log("Error getting tournament options: " . $e->getMessage());
            return [];
        }
    }
    
    public function getTournamentById($tournamentId) {
        try {
            $tournaments = $this->moitribe->tournRequestsHandler->getTournaments($this->gameId);
            
            foreach ($tournaments as $tournament) {
                if ($tournament->getId() === $tournamentId) {
                    return $tournament;
                }
            }
            
            return null;
            
        } catch (Exception $e) {
            error_log("Error finding tournament: " . $e->getMessage());
            return null;
        }
    }
    
    public function validateTournamentAccess($tournamentId, $playerLevel = null) {
        $tournament = $this->getTournamentById($tournamentId);
        
        if (!$tournament) {
            return ['valid' => false, 'reason' => 'Tournament not found'];
        }
        
        if ($tournament->getStatus() !== 'active') {
            return ['valid' => false, 'reason' => 'Tournament is not active'];
        }
        
        if ($tournament->isFull()) {
            return ['valid' => false, 'reason' => 'Tournament is full'];
        }
        
        if ($playerLevel && $tournament->getMinLevel() && $playerLevel < $tournament->getMinLevel()) {
            return ['valid' => false, 'reason' => 'Player level too low'];
        }
        
        return ['valid' => true];
    }
}

// Usage
$tournamentManager = new TournamentManager($moitribe, 'your-game-id');
$tournamentOptions = $tournamentManager->getTournamentOptions();

// Create dropdown for tournament selection
echo "<select name='tournament_id'>";
foreach ($tournamentOptions as $id => $details) {
    echo "<option value='$id'>" . htmlspecialchars($details['name']) . "</option>";
}
echo "</select>";

Error Handling​

Common Error Scenarios​

  • Empty game ID - Invalid or missing game identifier
  • Invalid game ID - Game doesn't exist in Moitribe system
  • Network issues - API communication problems
  • Permission issues - Insufficient access to game data

Error Handling Example​

function safeGetTournaments($gameId) {
    global $moitribe;
    
    try {
        if (empty($gameId)) {
            throw new InvalidArgumentException("Game ID cannot be empty");
        }
        
        $tournaments = $moitribe->tournRequestsHandler->getTournaments($gameId);
        
        return [
            'success' => true,
            'data' => $tournaments,
            'count' => count($tournaments)
        ];
        
    } catch (InvalidArgumentException $e) {
        return [
            'success' => false,
            'error' => 'Invalid input: ' . $e->getMessage()
        ];
    } catch (Exception $e) {
        error_log("Tournament API error: " . $e->getMessage());
        return [
            'success' => false,
            'error' => 'Failed to retrieve tournaments'
        ];
    }
}

// Usage
$result = safeGetTournaments('your-game-id');

if ($result['success']) {
    echo "Found {$result['count']} tournaments\n";
    // Process tournaments...
} else {
    echo "Error: " . $result['error'] . "\n";
}

Best Practices​

  1. Cache Tournament Data

    • Tournament lists don't change frequently
    • Cache for 5-15 minutes to improve performance
    • Invalidate cache when tournaments are updated

  2. Handle Empty Results

    • Always check if the returned array is empty
    • Provide user-friendly messages when no tournaments are available

  3. Validate Tournament Status

    • Check tournament status before allowing players to join
    • Filter out inactive or ended tournaments

  4. Error Logging

    • Log API failures for debugging
    • Monitor for unusual patterns or repeated failures