Skip to main content

Join Group Tournament

The join group tournament method allows players to register their team for group tournaments. This is used for multiplayer competitions and team-based events.

Overview​

The joinGroupTournament method:

  • Registers a player/team for a group tournament
  • Validates tournament availability and team requirements
  • Returns status code indicating success or failure
  • Handles team size and player capacity limits

Method Signature​

public function joinGroupTournament(string $gameID, string $tournamentID): int

Parameters​

Required Parameters​

  • gameID (String) - The Game ID for the group tournament
  • tournamentID (String) - The Group Tournament ID to join

Return Value​

Returns an integer status code:

  • Positive value - Successfully joined group tournament
  • Zero or negative - Join failed

Basic Usage​

Simple Group Tournament Join​

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

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

try {
    $result = $moitribe->groupTournRequestsHandler->joinGroupTournament(
        'your-game-id',
        'group-tournament-123'
    );
    
    if ($result > 0) {
        echo "Successfully joined group tournament!\n";
        echo "Registration ID: " . $result . "\n";
    } else {
        echo "Failed to join group tournament\n";
        echo "Error code: " . $result . "\n";
    }
    
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

Group Tournament Join with Validation​

function joinGroupTournamentSafely($gameId, $tournamentId, $playerId, $teamData = []) {
    global $moitribe;
    
    try {
        // First check if tournament exists and is joinable
        $groupTournaments = $moitribe->groupTournRequestsHandler->getGroupTournaments($gameId);
        $targetTournament = null;
        
        foreach ($groupTournaments as $tournament) {
            if ($tournament->getId() === $tournamentId) {
                $targetTournament = $tournament;
                break;
            }
        }
        
        if (!$targetTournament) {
            return ['success' => false, 'message' => 'Group tournament not found'];
        }
        
        if ($targetTournament->getStatus() !== 'active') {
            return ['success' => false, 'message' => 'Group tournament is not active'];
        }
        
        if ($targetTournament->isFull()) {
            return ['success' => false, 'message' => 'Group tournament is full'];
        }
        
        // Check team requirements
        $teamSize = $targetTournament->getMinTeamSize();
        $currentTeamSize = count($teamData['players'] ?? []);
        
        if ($currentTeamSize < $teamSize) {
            return ['success' => false, 'message' => "Team size too small. Minimum: {$teamSize} players"];
        }
        
        if ($currentTeamSize > $targetTournament->getMaxTeamSize()) {
            return ['success' => false, 'message' => "Team size too large. Maximum: {$targetTournament->getMaxTeamSize()} players"];
        }
        
        // Join group tournament
        $result = $moitribe->groupTournRequestsHandler->joinGroupTournament($gameId, $tournamentId);
        
        if ($result > 0) {
            return [
                'success' => true,
                'message' => 'Successfully joined group tournament',
                'registration_id' => $result,
                'tournament_name' => $targetTournament->getName(),
                'team_size' => $currentTeamSize
            ];
        } else {
            return ['success' => false, 'message' => 'Failed to join group tournament'];
        }
        
    } catch (Exception $e) {
        error_log("Group tournament join error: " . $e->getMessage());
        return [
            'success' => false,
            'message' => 'Server error occurred'
        ];
    }
}

// Usage
$teamData = [
    'players' => ['player-456', 'player-789'],
    'team_name' => 'Super Team'
];

$result = joinGroupTournamentSafely('your-game-id', 'group-tournament-456', 'player-123', $teamData);

if ($result['success']) {
    echo "Success: " . $result['message'] . "\n";
    echo "Tournament: " . $result['tournament_name'] . "\n";
    echo "Team Size: " . $result['team_size'] . "\n";
} else {
    echo "Error: " . $result['message'] . "\n";
}

Integration Examples​

Team Management System​

class GroupTournamentManager {
    private $moitribe;
    private $gameId;
    
    public function __construct($moitribe, $gameId) {
        $this->moitribe = $moitribe;
        $this->gameId = $gameId;
    }
    
    public function createTeam($playerIds, $teamName = null) {
        try {
            // Validate team
            if (count($playerIds) < 1) {
                throw new InvalidArgumentException("Team must have at least 1 player");
            }
            
            // Check if players are valid
            foreach ($playerIds as $playerId) {
                if (empty($playerId)) {
                    throw new InvalidArgumentException("Player ID cannot be empty");
                }
            }
            
            // Create team
            $teamData = [
                'name' => $teamName ?: 'Team ' . uniqid(),
                'players' => $playerIds,
                'created_at' => date('Y-m-d H:i:s')
            ];
            
            // Store team in your database
            $this->storeTeam($teamData);
            
            return [
                'success' => true,
                'team_id' => $teamData['name'],
                'players' => $playerIds
            ];
            
        } catch (Exception $e) {
            error_log("Team creation error: " . $e->getMessage());
            return [
                'success' => false,
                'message' => 'Failed to create team'
            ];
        }
    }
    
    public function joinTournamentWithTeam($tournamentId, $teamId, $playerId) {
        try {
            // Get tournament details
            $tournaments = $this->moitribe->groupTournRequestsHandler->getGroupTournaments($this->gameId);
            $targetTournament = null;
            
            foreach ($tournaments as $tournament) {
                if ($tournament->getId() === $tournamentId) {
                    $targetTournament = $tournament;
                    break;
                }
            }
            
            if (!$targetTournament) {
                return ['success' => false, 'message' => 'Group tournament not found'];
            }
            
            // Get team details
            $team = $this->getTeamById($teamId);
            if (!$team) {
                return ['success' => false, 'message' => 'Team not found'];
            }
            
            // Validate team size
            $teamSize = count($team['players']);
            $minTeamSize = $targetTournament->getMinTeamSize();
            $maxTeamSize = $targetTournament->getMaxTeamSize();
            
            if ($teamSize < $minTeamSize || $teamSize > $maxTeamSize) {
                return ['success' => false, 'message' => "Invalid team size for this tournament'];
            }
            
            // Join tournament with team
            $result = $this->moitribe->groupTournRequestsHandler->joinGroupTournament(
                $this->gameId,
                $tournamentId
            );
            
            if ($result > 0) {
                // Update team with tournament registration
                $this->updateTeamWithTournament($teamId, $tournamentId, $result);
                
                return [
                    'success' => true,
                    'message' => 'Team successfully joined tournament',
                    'registration_id' => $result,
                    'tournament_name' => $targetTournament->getName()
                ];
            } else {
                return ['success' => false, 'message' => 'Failed to join tournament with team'];
            }
            
        } catch (Exception $e) {
            error_log("Team tournament join error: " . $e->getMessage());
            return [
                'success' => false,
                'message' => 'Server error occurred'
            ];
        }
    }
    
    private function getTeamById($teamId) {
        // Retrieve team from your database
        // This is a placeholder - implement based on your system
        return [
            'id' => $teamId,
            'name' => 'Team Name',
            'players' => ['player-1', 'player-2'],
            'created_at' => '2024-01-01 12:00:00'
        ];
    }
    
    private function storeTeam($teamData) {
        // Store team in your database
        error_log("Storing team: " . json_encode($teamData));
    }
    
    private function updateTeamWithTournament($teamId, $tournamentId, $registrationId) {
        // Update team record with tournament registration
        $updateData = [
            'tournament_registration_id' => $registrationId,
            'updated_at' => date('Y-m-d H:i:s')
        ];
        
        // Update team in your database
        error_log("Updating team with tournament: " . json_encode($updateData));
    }
}

// Usage
$tournamentManager = new GroupTournamentManager($moitribe, 'your-game-id');

// Create a team
$teamResult = $tournamentManager->createTeam(['player-123', 'player-456'], 'Champions');

// Join tournament with team
$joinResult = $tournamentManager->joinTournamentWithTeam('tournament-789', 'team-1', 'player-123');

if ($joinResult['success']) {
    echo "Success: " . $joinResult['message'] . "\n";
} else {
    echo "Error: " . $joinResult['message'] . "\n";
}

Web Group Tournament Join Handler​

function handleGroupTournamentJoinRequest() {
    global $moitribe;
    
    if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
        http_response_code(405);
        echo json_encode(['error' => 'Method not allowed']);
        return;
    }
    
    $input = json_decode(file_get_contents('php://input'), true);
    
    $requiredFields = ['game_id', 'tournament_id', 'player_id'];
    foreach ($requiredFields as $field) {
        if (!isset($input[$field])) {
            http_response_code(400);
            echo json_encode(['error' => "Missing required field: $field"]);
            return;
        }
    }
    
    $gameId = $input['game_id'] ?? 'your-game-id';
    $tournamentId = $input['tournament_id'] ?? '';
    $playerId = $input['player_id'] ?? '';
    $teamId = $input['team_id'] ?? null;
    
    try {
        if (empty($gameId) || empty($tournamentId) || empty($playerId)) {
            throw new InvalidArgumentException('Game ID, Tournament ID, and Player ID are required');
        }
        
        // Join group tournament
        $result = $moitribe->groupTournRequestsHandler->joinGroupTournament($gameId, $tournamentId);
        
        if ($result > 0) {
            http_response_code(200);
            echo json_encode([
                'success' => true,
                'message' => 'Successfully joined group tournament',
                'registration_id' => $result
            ]);
        } else {
            http_response_code(400);
            echo json_encode([
                'success' => false,
                'message' => 'Failed to join group tournament',
                'error_code' => $result
            ]);
        }
        
    } catch (InvalidArgumentException $e) {
        http_response_code(400);
        echo json_encode(['success' => false, 'message' => $e->getMessage()]);
        } catch (Exception $e) {
            http_response_code(500);
            echo json_encode(['success' => false, 'message' => 'Server error occurred']);
            error_log("Group tournament join API error: " . $e->getMessage());
        }
    }
}

// Route handler
if (strpos($_SERVER['REQUEST_URI'], '/api/group-tournament/join') !== false) {
    handleGroupTournamentJoinRequest();
}

Error Handling​

Common Error Scenarios​

  • Tournament not found - Invalid tournament ID
  • Tournament not active - Tournament hasn't started or has ended
  • Tournament full - Maximum teams reached
  • Team size invalid - Team doesn't meet size requirements
  • Player already registered - Player already in tournament
  • Network issues - API communication problems

Error Handling Example​

function safeJoinGroupTournament($gameId, $tournamentId) {
    global $moitribe;
    
    try {
        if (empty($gameId) || empty($tournamentId)) {
            throw new InvalidArgumentException("Game ID and Tournament ID are required");
        }
        
        $result = $moitribe->groupTournRequestsHandler->joinGroupTournament($gameId, $tournamentId);
        
        if ($result > 0) {
            return ['success' => true, 'registration_id' => $result];
        } else {
            $errorMessage = $this->getGroupTournamentErrorMessage($result);
            return ['success' => false, 'message' => $errorMessage, 'error_code' => $result];
        }
        
    } catch (InvalidArgumentException $e) {
        return [
            'success' => false,
            'error' => 'Invalid input: ' . $e->getMessage()
        ];
    } catch (Exception $e) {
        error_log("Group tournament join error: " . $e->getMessage());
        return [
            'success' => false,
            'error' => 'Failed to join group tournament'
        ];
    }
}

function getGroupTournamentErrorMessage($errorCode) {
    switch ($errorCode) {
        case 0:
            return 'Group tournament join failed';
        case -1:
            return 'Group tournament not found';
        case -2:
            return 'Group tournament is not active';
        case -3:
            return 'Group tournament is full';
        case -4:
            return 'Team size requirements not met';
        case -5:
            return 'Player already registered for this tournament';
        case -6:
            return 'Invalid team configuration';
        default:
            return 'Unknown error occurred';
    }
}

Best Practices​

  1. Validate Team Requirements

    • Check minimum and maximum team sizes
    • Ensure all players are valid
    • Validate team composition before joining

  2. Handle Team Management

    • Create teams before joining tournaments
    • Track team registrations
    • Allow team modifications before tournaments start

  3. Provide Clear Feedback

    • Show specific error messages for team issues
    • Display tournament requirements clearly
    • Guide users through team creation process

  4. Manage Tournament Capacity

    • Monitor team registration limits
    • Handle waitlist scenarios
    • Implement fair team distribution