Servers

Server definitions and query ports

Home · Supported identifiers · Protocol options

Every server passed to addServer() or addServers() is an associative array.

Key	Required	Meaning
type	Yes	GameQ identifier such as css, cod4, ut2004, or teamspeak3. Identifiers are case-insensitive.
host	Yes	Address and client/connect port, for example example.net:27015 or [2001:db8::10]:27015.
id	No	Stable result key chosen by the application. Defaults to the resolved address and client port.
options	No	Per-server options such as query_port, credentials, or protocol-specific switches.

$gameQ->addServer([
    'id' => 'public-server',
    'type' => 'css',
    'host' => 'game.example.net:27015',
    'options' => [
        'query_port' => 27016,
    ],
]);

Client port versus query port

The port in host is always the port players use to connect. GameQ asks the selected protocol for its query-port offset. For example, a protocol with an offset of 1 queries client port 27015 on port 27016.

If the server administrator configured a different query port, override the calculation:

'options' => [
    'query_port' => 28015,
],

query_port must be an integer or a decimal integer string between 1 and 65535. It is required for TeamSpeak 2 and TeamSpeak 3 because their server-query ports cannot be derived reliably from the selected virtual server's client port.

Address formats

Accepted examples:

192.0.2.10:27015
game.example.net:27015
[2001:db8::10]:27015

An IPv6 literal must be enclosed in square brackets. Hostnames are currently resolved to IPv4 with PHP's gethostbyname(); use a bracketed IPv6 literal when IPv6 is required.

Missing ports, invalid IP literals, unresolved hostnames, unknown protocol types, and out-of-range ports raise GameQ\Exception\ServerException while the server definition is added.

Result IDs

Use explicit IDs whenever the result must be associated with an application record:

$gameQ->addServers([
    ['id' => 'database-42', 'type' => 'tf2', 'host' => '192.0.2.42:27015'],
    ['id' => 'database-43', 'type' => 'tf2', 'host' => '192.0.2.43:27015'],
]);

$results = $gameQ->process();
$server42 = $results['database-42'];

IDs should be unique within a GameQ instance. Duplicate result IDs overwrite earlier results when the final result array is assembled.

JSON server lists

addServersFromFiles() accepts one filename or a list of filenames. Each file contains the same array shape accepted by addServers():

[
  {
    "id": "database-42",
    "type": "tf2",
    "host": "192.0.2.42:27015"
  }
]

Missing, unreadable, malformed, and non-array files are skipped. Valid-looking entries are still validated by Server, so an entry with a missing host or unknown type can raise ServerException.

Do not place protocol passwords or tokens in a web-accessible JSON file. See security.