| Connect( $Ip, $Port, $Timeout, $Engine ) |
Opens connection to a server |
| Disconnect( ) |
Closes all open connections |
| Ping( ) |
Ping the server to see if it exists
Warning: Source engine may not answer to this |
| GetInfo( ) |
Returns server info in an array |
| GetPlayers( ) |
Returns players on the server in an array |
| GetRules( ) |
Returns public rules (cvars) in an array |
| SetRconPassword( $Password ) |
Sets rcon password for later use with Rcon() |
| Rcon( $Command ) |
Execute rcon command on the server |
Also refer to [examples folder](Examples/) to work things out.
## License
PHP Source Query
Copyright (C) 2012-2025 Pavel Djundik
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
================================================
FILE: SourceQuery/BaseRcon.php
================================================
Close( );
}
abstract public function Close( ) : void;
abstract public function Open( string $Address, int $Port, int $Timeout, int $Engine ) : void;
abstract public function Write( int $Header, string $String = '' ) : bool;
abstract public function Read( ) : Buffer;
protected function ReadInternal( Buffer $Buffer, callable $SherlockFunction ) : Buffer
{
if( $Buffer->Remaining( ) === 0 )
{
throw new InvalidPacketException( 'Failed to read any data from socket', InvalidPacketException::BUFFER_EMPTY );
}
$Header = $Buffer->ReadInt32( );
if( $Header === -1 ) // Single packet
{
// We don't have to do anything
}
else if( $Header === -2 ) // Split packet
{
$Packets = [];
$IsCompressed = false;
$ReadMore = false;
$PacketChecksum = null;
do
{
$RequestID = $Buffer->ReadInt32( );
$PacketCount = 0;
$PacketNumber = 0;
switch( $this->Engine )
{
case SourceQuery::GOLDSOURCE:
{
$PacketCountAndNumber = $Buffer->ReadByte( );
$PacketCount = $PacketCountAndNumber & 0xF;
$PacketNumber = $PacketCountAndNumber >> 4;
break;
}
case SourceQuery::SOURCE:
{
$IsCompressed = ( $RequestID & 0x80000000 ) !== 0;
$PacketCount = $Buffer->ReadByte( );
$PacketNumber = $Buffer->ReadByte( ) + 1;
if( $IsCompressed )
{
$Buffer->ReadInt32( ); // Split size
$PacketChecksum = $Buffer->ReadUInt32( );
}
else
{
$Buffer->ReadInt16( ); // Split size
}
break;
}
default:
{
throw new SocketException( 'Unknown engine.', SocketException::INVALID_ENGINE );
}
}
$Packets[ $PacketNumber ] = $Buffer->Read( );
$ReadMore = $PacketCount > sizeof( $Packets );
}
while( $ReadMore && $SherlockFunction( $Buffer ) );
$Data = implode( $Packets );
// TODO: Test this
if( $IsCompressed )
{
// Let's make sure this function exists, it's not included in PHP by default
if( !function_exists( 'bzdecompress' ) )
{
throw new \RuntimeException( 'Received compressed packet, PHP doesn\'t have Bzip2 library installed, can\'t decompress.' );
}
$Data = bzdecompress( $Data );
if( !is_string( $Data ) || crc32( $Data ) !== $PacketChecksum )
{
throw new InvalidPacketException( 'CRC32 checksum mismatch of uncompressed packet data.', InvalidPacketException::CHECKSUM_MISMATCH );
}
}
$Buffer->Set( substr( $Data, 4 ) );
}
else
{
throw new InvalidPacketException( 'Socket read: Raw packet header mismatch. (0x' . dechex( $Header ) . ')', InvalidPacketException::PACKET_HEADER_MISMATCH );
}
return $Buffer;
}
}
================================================
FILE: SourceQuery/Buffer.php
================================================
Buffer = $Buffer;
$this->Length = strlen( $Buffer );
$this->Position = 0;
}
/**
* Get remaining bytes
*
* @return int Remaining bytes in buffer
*
* @phpstan-impure
*/
public function Remaining( ) : int
{
return $this->Length - $this->Position;
}
/**
* Reads the specified number of bytes.
*
* @param int $Length Bytes to read
*/
public function Read( int $Length = -1 ) : string
{
if( $Length === 0 )
{
return '';
}
$Remaining = $this->Remaining( );
if( $Length === -1 )
{
$Length = $Remaining;
}
else if( $Length > $Remaining )
{
return '';
}
$Data = substr( $this->Buffer, $this->Position, $Length );
$this->Position += $Length;
return $Data;
}
/**
* Reads the next byte.
*/
public function ReadByte( ) : int
{
if( $this->Remaining( ) < 1 )
{
return 0;
}
return ord( $this->Read( 1 ) );
}
/**
* Reads a 2-byte signed integer.
*/
public function ReadInt16( ) : int
{
if( $this->Remaining( ) < 2 )
{
throw new InvalidPacketException( 'Not enough data to unpack.', InvalidPacketException::BUFFER_EMPTY );
}
$Data = unpack( 'v', $this->Read( 2 ) );
if( $Data === false )
{
throw new InvalidPacketException( 'Failed to unpack.', InvalidPacketException::UNPACK_FAILED );
}
return (int)$Data[ 1 ];
}
/**
* Reads a 4-byte signed integer.
*/
public function ReadInt32( ) : int
{
if( $this->Remaining( ) < 4 )
{
throw new InvalidPacketException( 'Not enough data to unpack.', InvalidPacketException::BUFFER_EMPTY );
}
$Data = unpack( 'l', $this->Read( 4 ) );
if( $Data === false )
{
throw new InvalidPacketException( 'Failed to unpack.', InvalidPacketException::UNPACK_FAILED );
}
return (int)$Data[ 1 ];
}
/**
* Reads a 4-byte floating point value.
*/
public function ReadFloat32( ) : float
{
if( $this->Remaining( ) < 4 )
{
throw new InvalidPacketException( 'Not enough data to unpack.', InvalidPacketException::BUFFER_EMPTY );
}
$Data = unpack( 'f', $this->Read( 4 ) );
if( $Data === false )
{
throw new InvalidPacketException( 'Failed to unpack.', InvalidPacketException::UNPACK_FAILED );
}
return (float)$Data[ 1 ];
}
/**
* Reads a 4-byte unsigned integer.
*/
public function ReadUInt32( ) : int
{
if( $this->Remaining( ) < 4 )
{
throw new InvalidPacketException( 'Not enough data to unpack.', InvalidPacketException::BUFFER_EMPTY );
}
$Data = unpack( 'V', $this->Read( 4 ) );
if( $Data === false )
{
throw new InvalidPacketException( 'Failed to unpack.', InvalidPacketException::UNPACK_FAILED );
}
return (int)$Data[ 1 ];
}
/**
* Read a null-terminated string.
*/
public function ReadNullTermString( ) : string
{
$ZeroBytePosition = strpos( $this->Buffer, "\0", $this->Position );
if( $ZeroBytePosition === false )
{
return '';
}
$String = $this->Read( $ZeroBytePosition - $this->Position );
$this->Position++;
return $String;
}
}
================================================
FILE: SourceQuery/Exception/AuthenticationException.php
================================================
Socket = $Socket;
}
public function Close( ) : void
{
$this->RconChallenge = '';
$this->RconPassword = '';
}
public function Open( ) : void
{
//
}
public function Write( int $Header, string $String = '' ) : bool
{
if( $this->Socket->Socket === null )
{
throw new SocketException( 'Not connected.', SocketException::NOT_CONNECTED );
}
$Command = pack( 'cccca*', 0xFF, 0xFF, 0xFF, 0xFF, $String );
$Length = strlen( $Command );
return $Length === fwrite( $this->Socket->Socket, $Command, $Length );
}
/**
* @throws AuthenticationException
*/
public function Read( ) : Buffer
{
// GoldSource RCON has same structure as Query
$Buffer = $this->Socket->Read( );
$StringBuffer = '';
$ReadMore = false;
// There is no indentifier of the end, so we just need to continue reading
do
{
$ReadMore = $Buffer->Remaining( ) > 0;
if( $ReadMore )
{
if( $Buffer->ReadByte( ) !== SourceQuery::S2A_RCON )
{
throw new InvalidPacketException( 'Invalid rcon response.', InvalidPacketException::PACKET_HEADER_MISMATCH );
}
$Packet = $Buffer->Read( );
$StringBuffer .= $Packet;
//$StringBuffer .= SubStr( $Packet, 0, -2 );
// Let's assume if this packet is not long enough, there are no more after this one
$ReadMore = strlen( $Packet ) > 1000; // use 1300?
if( $ReadMore )
{
$Buffer = $this->Socket->Read( );
}
}
}
while( $ReadMore );
$Trimmed = trim( $StringBuffer );
if( $Trimmed === 'Bad rcon_password.' )
{
throw new AuthenticationException( $Trimmed, AuthenticationException::BAD_PASSWORD );
}
else if( $Trimmed === 'You have been banned from this server.' )
{
throw new AuthenticationException( $Trimmed, AuthenticationException::BANNED );
}
$Buffer->Set( $Trimmed );
return $Buffer;
}
public function Command( string $Command ) : string
{
if( !$this->RconChallenge )
{
throw new AuthenticationException( 'Tried to execute a RCON command before successful authorization.', AuthenticationException::BAD_PASSWORD );
}
$this->Write( 0, 'rcon ' . $this->RconChallenge . ' "' . $this->RconPassword . '" ' . $Command . "\0" );
$Buffer = $this->Read( );
return $Buffer->Read( );
}
public function Authorize( string $Password ) : void
{
$this->RconPassword = $Password;
$this->Write( 0, 'challenge rcon' );
$Buffer = $this->Socket->Read( );
if( $Buffer->Read( 14 ) !== 'challenge rcon' )
{
throw new AuthenticationException( 'Failed to get RCON challenge.', AuthenticationException::BAD_PASSWORD );
}
$this->RconChallenge = trim( $Buffer->Read( ) );
}
}
================================================
FILE: SourceQuery/Socket.php
================================================
Socket ) )
{
fclose( $this->Socket );
$this->Socket = null;
}
}
public function Open( string $Address, int $Port, int $Timeout, int $Engine ) : void
{
$this->Timeout = $Timeout;
$this->Engine = $Engine;
$this->Port = $Port;
$this->Address = $Address;
$Socket = @fsockopen( 'udp://' . $Address, $Port, $ErrNo, $ErrStr, $Timeout );
if( $ErrNo || $Socket === false )
{
throw new SocketException( 'Could not create socket: ' . $ErrStr, SocketException::COULD_NOT_CREATE_SOCKET );
}
$this->Socket = $Socket;
stream_set_timeout( $this->Socket, $Timeout );
stream_set_blocking( $this->Socket, true );
}
public function Write( int $Header, string $String = '' ) : bool
{
if( $this->Socket === null )
{
throw new SocketException( 'Not connected.', SocketException::NOT_CONNECTED );
}
$Command = pack( 'ccccca*', 0xFF, 0xFF, 0xFF, 0xFF, $Header, $String );
$Length = strlen( $Command );
return $Length === fwrite( $this->Socket, $Command, $Length );
}
private const MaxPacketLength = 1 << 16;
/**
* Reads from socket and returns Buffer.
*
* @throws InvalidPacketException
*/
public function Read( ) : Buffer
{
if( $this->Socket === null )
{
throw new SocketException( 'Not connected.', SocketException::NOT_CONNECTED );
}
$Data = fread( $this->Socket, self::MaxPacketLength );
$Buffer = new Buffer( );
$Buffer->Set( $Data === false ? '' : $Data );
$this->ReadInternal( $Buffer, [ $this, 'Sherlock' ] );
return $Buffer;
}
public function Sherlock( Buffer $Buffer ) : bool
{
if( $this->Socket === null )
{
throw new SocketException( 'Not connected.', SocketException::NOT_CONNECTED );
}
$Data = fread( $this->Socket, self::MaxPacketLength );
if( $Data === false || strlen( $Data ) < 4 )
{
return false;
}
$Buffer->Set( $Data );
return $Buffer->ReadInt32( ) === -2;
}
}
================================================
FILE: SourceQuery/SourceQuery.php
================================================
Socket = $Socket ?? new Socket( );
}
public function __destruct( )
{
$this->Disconnect( );
}
/**
* Opens connection to server
*
* @param string $Address Server ip
* @param int $Port Server port
* @param int $Timeout Timeout period
* @param int $Engine Engine the server runs on (goldsource, source)
*
* @throws InvalidArgumentException
* @throws SocketException
*/
public function Connect( string $Address, int $Port, int $Timeout = 3, int $Engine = self::SOURCE ) : void
{
$this->Disconnect( );
if( $Timeout < 0 )
{
throw new InvalidArgumentException( 'Timeout must be a positive integer.', InvalidArgumentException::TIMEOUT_NOT_INTEGER );
}
$this->Socket->Open( $Address, $Port, $Timeout, $Engine );
$this->Connected = true;
}
/**
* Forces GetChallenge to use old method for challenge retrieval because some games use outdated protocol (e.g Starbound)
*
* @param bool $Value Set to true to force old method
*
* @return bool Previous value
*/
public function SetUseOldGetChallengeMethod( bool $Value ) : bool
{
$Previous = $this->UseOldGetChallengeMethod;
$this->UseOldGetChallengeMethod = $Value === true;
return $Previous;
}
/**
* Closes all open connections
*/
public function Disconnect( ) : void
{
$this->Connected = false;
$this->Challenge = '';
$this->Socket->Close( );
if( $this->Rcon !== null )
{
$this->Rcon->Close( );
$this->Rcon = null;
}
}
/**
* Sends ping packet to the server
* NOTE: This may not work on some games (TF2 for example)
*
* @throws InvalidPacketException
* @throws SocketException
*
* @return bool True on success, false on failure
*/
public function Ping( ) : bool
{
if( !$this->Connected )
{
throw new SocketException( 'Not connected.', SocketException::NOT_CONNECTED );
}
$this->Socket->Write( self::A2A_PING );
$Buffer = $this->Socket->Read( );
return $Buffer->ReadByte( ) === self::A2A_ACK;
}
/**
* Get server information
*
* @throws InvalidPacketException
* @throws SocketException
*
* @return array{
* Protocol: int,
* HostName: string,
* Map: string,
* ModDir: string,
* ModDesc: string,
* AppID?: int,
* Players: int,
* MaxPlayers: int,
* Bots: int,
* Dedicated: string,
* Os: string,
* Password: bool,
* Secure: bool,
* Version?: string,
* ExtraDataFlags?: int,
* GamePort?: int,
* SteamID?: string|int,
* SpecPort?: int,
* SpecName?: string,
* GameTags?: string,
* GameID?: int,
* Address?: string,
* IsMod?: bool,
* Mod?: array{
* Url: string,
* Download: string,
* Version: int,
* Size: int,
* ServerSide: bool,
* CustomDLL: bool
* },
* GameMode?: int,
* WitnessCount?: int,
* WitnessTime?: int
* } Returns an array with server information on success
*/
public function GetInfo( ) : array
{
if( !$this->Connected )
{
throw new SocketException( 'Not connected.', SocketException::NOT_CONNECTED );
}
if( $this->Challenge )
{
$this->Socket->Write( self::A2S_INFO, "Source Engine Query\0" . $this->Challenge );
}
else
{
$this->Socket->Write( self::A2S_INFO, "Source Engine Query\0" );
}
$Buffer = $this->Socket->Read( );
$Type = $Buffer->ReadByte( );
$Server = [];
if( $Type === self::S2C_CHALLENGE )
{
$this->Challenge = $Buffer->Read( 4 );
$this->Socket->Write( self::A2S_INFO, "Source Engine Query\0" . $this->Challenge );
$Buffer = $this->Socket->Read( );
$Type = $Buffer->ReadByte( );
}
// Old GoldSource protocol, HLTV still uses it
if( $Type === self::S2A_INFO_OLD && $this->Socket->Engine === self::GOLDSOURCE )
{
/**
* If we try to read data again, and we get the result with type S2A_INFO (0x49)
* That means this server is running dproto,
* Because it sends answer for both protocols
*/
$Server[ 'Address' ] = $Buffer->ReadNullTermString( );
$Server[ 'HostName' ] = $Buffer->ReadNullTermString( );
$Server[ 'Map' ] = $Buffer->ReadNullTermString( );
$Server[ 'ModDir' ] = $Buffer->ReadNullTermString( );
$Server[ 'ModDesc' ] = $Buffer->ReadNullTermString( );
$Server[ 'Players' ] = $Buffer->ReadByte( );
$Server[ 'MaxPlayers' ] = $Buffer->ReadByte( );
$Server[ 'Protocol' ] = $Buffer->ReadByte( );
$Server[ 'Dedicated' ] = chr( $Buffer->ReadByte( ) );
$Server[ 'Os' ] = chr( $Buffer->ReadByte( ) );
$Server[ 'Password' ] = $Buffer->ReadByte( ) === 1;
$Server[ 'IsMod' ] = $Buffer->ReadByte( ) === 1;
if( $Server[ 'IsMod' ] )
{
$Mod = [];
$Mod[ 'Url' ] = $Buffer->ReadNullTermString( );
$Mod[ 'Download' ] = $Buffer->ReadNullTermString( );
$Buffer->Read( 1 ); // NULL byte
$Mod[ 'Version' ] = $Buffer->ReadInt32( );
$Mod[ 'Size' ] = $Buffer->ReadInt32( );
$Mod[ 'ServerSide' ] = $Buffer->ReadByte( ) === 1;
$Mod[ 'CustomDLL' ] = $Buffer->ReadByte( ) === 1;
$Server[ 'Mod' ] = $Mod;
}
$Server[ 'Secure' ] = $Buffer->ReadByte( ) === 1;
$Server[ 'Bots' ] = $Buffer->ReadByte( );
return $Server;
}
if( $Type !== self::S2A_INFO_SRC )
{
throw new InvalidPacketException( 'GetInfo: Packet header mismatch. (0x' . dechex( $Type ) . ')', InvalidPacketException::PACKET_HEADER_MISMATCH );
}
$Server[ 'Protocol' ] = $Buffer->ReadByte( );
$Server[ 'HostName' ] = $Buffer->ReadNullTermString( );
$Server[ 'Map' ] = $Buffer->ReadNullTermString( );
$Server[ 'ModDir' ] = $Buffer->ReadNullTermString( );
$Server[ 'ModDesc' ] = $Buffer->ReadNullTermString( );
$Server[ 'AppID' ] = $Buffer->ReadInt16( );
$Server[ 'Players' ] = $Buffer->ReadByte( );
$Server[ 'MaxPlayers' ] = $Buffer->ReadByte( );
$Server[ 'Bots' ] = $Buffer->ReadByte( );
$Server[ 'Dedicated' ] = chr( $Buffer->ReadByte( ) );
$Server[ 'Os' ] = chr( $Buffer->ReadByte( ) );
$Server[ 'Password' ] = $Buffer->ReadByte( ) === 1;
$Server[ 'Secure' ] = $Buffer->ReadByte( ) === 1;
// The Ship (they violate query protocol spec by modifying the response)
if( $Server[ 'AppID' ] === 2400 )
{
$Server[ 'GameMode' ] = $Buffer->ReadByte( );
$Server[ 'WitnessCount' ] = $Buffer->ReadByte( );
$Server[ 'WitnessTime' ] = $Buffer->ReadByte( );
}
$Server[ 'Version' ] = $Buffer->ReadNullTermString( );
// Extra Data Flags
if( $Buffer->Remaining( ) > 0 )
{
$Server[ 'ExtraDataFlags' ] = $Flags = $Buffer->ReadByte( );
// S2A_EXTRA_DATA_HAS_GAME_PORT - Next 2 bytes include the game port.
if( $Flags & 0x80 )
{
$Server[ 'GamePort' ] = $Buffer->ReadInt16( );
}
// S2A_EXTRA_DATA_HAS_STEAMID - Next 8 bytes are the steamID
// Want to play around with this?
// You can use https://github.com/xPaw/SteamID.php
if( $Flags & 0x10 )
{
$SteamIDLower = $Buffer->ReadUInt32( );
$SteamIDInstance = $Buffer->ReadUInt32( ); // This gets shifted by 32 bits, which should be steamid instance
$SteamID = 0;
if( PHP_INT_SIZE === 4 )
{
if( extension_loaded( 'gmp' ) )
{
$SteamIDLower = gmp_abs( $SteamIDLower );
$SteamIDInstance = gmp_abs( $SteamIDInstance );
$SteamID = gmp_strval( gmp_or( $SteamIDLower, gmp_mul( $SteamIDInstance, gmp_pow( 2, 32 ) ) ) );
}
else
{
throw new \RuntimeException( 'Either 64-bit PHP installation or "gmp" module is required to correctly parse server\'s steamid.' );
}
}
else
{
$SteamID = $SteamIDLower | ( $SteamIDInstance << 32 );
}
$Server[ 'SteamID' ] = $SteamID;
unset( $SteamIDLower, $SteamIDInstance, $SteamID );
}
// S2A_EXTRA_DATA_HAS_SPECTATOR_DATA - Next 2 bytes include the spectator port, then the spectator server name.
if( $Flags & 0x40 )
{
$Server[ 'SpecPort' ] = $Buffer->ReadInt16( );
$Server[ 'SpecName' ] = $Buffer->ReadNullTermString( );
}
// S2A_EXTRA_DATA_HAS_GAMETAG_DATA - Next bytes are the game tag string
if( $Flags & 0x20 )
{
$Server[ 'GameTags' ] = $Buffer->ReadNullTermString( );
}
// S2A_EXTRA_DATA_GAMEID - Next 8 bytes are the gameID of the server
if( $Flags & 0x01 )
{
$Server[ 'GameID' ] = $Buffer->ReadUInt32( ) | ( $Buffer->ReadUInt32( ) << 32 );
}
if( $Buffer->Remaining( ) > 0 )
{
throw new InvalidPacketException( 'GetInfo: unread data? ' . $Buffer->Remaining( ) . ' bytes remaining in the buffer. Please report it to the library developer.',
InvalidPacketException::BUFFER_NOT_EMPTY );
}
}
return $Server;
}
/**
* Get players on the server
*
* @throws InvalidPacketException
* @throws SocketException
*
* @return array