Upgrading from 4.x

Upgrading from GameQ 4.x

Home · Installation · Changelog

GameQ 5 preserves the 4.0.0 public and protected API where practical, but its platform requirements and validation are stricter.

Composer package

Replace the upstream package requirement with the maintained fork:

{
  "require": {
    "softcreatr/gameq": "^5.0"
  }
}

Then update Composer:

composer remove austinb/gameq --no-update
composer require softcreatr/gameq:^5.0
composer check-platform-reqs

Review the lockfile and deployed package name rather than assuming that changing an import statement selects the fork; both packages expose the GameQ namespace.

Platform requirements

Version 5 requires PHP 8.1 or newer plus bz2, curl, libxml, simplexml, and xml. Test the exact deployment runtime, not only a development CLI installation.

API compatibility and deprecation

Normal GameQ usage remains familiar:

$gameQ = new GameQ\GameQ();
$gameQ->addServer([
    'type' => 'css',
    'host' => '192.0.2.10:27015',
]);
$results = $gameQ->process();

Server::protocol() is deprecated because its historical nullable return type does not describe an initialized Server. New code should use:

$protocol = $server->protocolInstance();

The deprecated method remains available in version 5.

Stricter validation

Version 5 rejects invalid ports, malformed host definitions, unsafe buffer operations, truncated framing, inconsistent lengths, oversized responses, and malformed JSON/XML more consistently. Code that previously relied on warnings, truncation, coercion, or partial parsing can now receive ServerException, QueryException, or ProtocolException.

Wrap server construction and processing appropriately, and use debug mode in staging to identify bad definitions:

$gameQ->setOption('debug', true);

Do not “fix” a new exception by disabling bounds or framing checks. Verify the server type, query port, and current wire format first.

Query behavior changes

• Source/Source 2 challenges, player queries, and rules queries are response-driven follow-ups.
• Native TCP/TLS queries wait for complete buffered records and HTTP bodies.
• Large lists are processed in bounded batches, defaulting to 50 servers.
• Response size, packet count, decompression, and follow-up limits are enforced.
• HTTP/master protocols validate status codes, schemas, timeouts, and response sizes.

Applications with very large lists should review performance and batching. Applications that expose server configuration to users must review security.

Custom protocols and filters

If the application ships subclasses:

1. run them on PHP 8.1 or newer;
2. add native types only when they remain compatible with the parent contract;
3. check changed shared-family behavior against recorded fixtures;
4. replace calls to deprecated APIs;
5. run composer bc-check and the application test suite;
6. confirm the custom autoloader still resolves GameQ\Protocols\<Type> and GameQ\Filters\<Name>.

Recommended rollout

1. Upgrade in a branch and run composer test for GameQ plus the consuming application's tests.
2. Query representative servers for every protocol used in production.
3. Compare normalized and native result shapes.
4. Test offline, malformed, slow, and credentialed endpoints separately.
5. Deploy with logging around GameQ exceptions and monitor offline/error rates by protocol.

See the changelog for the complete version 5 summary.