rodssmp / libpmquery

dev-master 2026-11-12 15:42 UTC

Requires

• php: ^7.4|^8.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.11
• phpstan/extension-installer: ^1.3.0
• phpstan/phpstan: ^1.10.14
• phpstan/phpstan-strict-rules: ^1.5.1

lgpl-3.0-or-later

• jasonw4331

Published on Packagist.org on 2026-11-12 15:43 UTC

README

A PocketMine Virion which allows plugins to query other servers for a selection of information

Basic Usage

This virion was made for developers to query Pocketmine-MP servers with ease. Here is some basic functionality:

Required imports

The following imports are necessary to use the virion library:

use jasonw4331\libpmquery\PMQuery;
use jasonw4331\libpmquery\PmQueryException;

API

The querying API is a single function which grabs the data from whatever server you input. Usage is as follows:

$query = PMQuery::query("my.server.net", 19132);

The values returned will follow these values/types:

$query['GameName'];         // Returns the server software being used
$query['HostName'];         // Returns the server host name
$query['Protocol'];         // Returns the protocol version allowed to connect
$query['Version'];          // Returns the client version allowed to connect
$query['Players'];          // Returns the number of players on the server currently
$query['MaxPlayers'];       // Returns the maximum player count of the server
$query['ServerId'];         // Returns the raknet server id
$query['Map'];              // Returns the default world name
$query['GameMode'];         // Returns the default gamemode
$query['NintendoLimited'];  // Returns the status of Nintendo's limitation to join
$query['IPv4Port'];         // Returns the ipv4 port number
$query['IPv6Port'];         // Returns the ipv6 port number
$query['Extra'];            // I still don't know what this info is

Offline Queries

Queries sent to offline servers always throw a PmQueryException. Exceptions can be caught in a try/catch statement to log their offline status.

try{
    $query = PMQuery::query("my.server.net", 19133);
    $players = (int) $query['Players'];
    Server::getInstance()->getLogger()->info("There are ".$players." on the queried server right now!");
}catch(PmQueryException $e){
    //you can choose to log this if you want
    Server::getInstance()->getLogger()->info("The queried server is offline right now!");
}

NetherNet and RakNet transports

The query API supports both the RakNet UDP unconnected ping and the NetherNet HTTP(S) status endpoint (/v1/join). By default, auto tries NetherNet first and falls back to RakNet. You can also select a transport explicitly:

// Automatic: NetherNet first, then RakNet
$query = PMQuery::query("my.server.net", 19132);

// Force RakNet UDP
$query = PMQuery::query("my.server.net", 19132, 4, "raknet");

// NetherNet uses plain HTTP by default (no SSL requirement)
$query = PMQuery::query("my.server.net", 19132, 4, "nethernet");

// HTTPS is optional and is used only when explicitly requested
$query = PMQuery::query("https://status.example.net", 443, 4, "nethernet");

The equivalent direct methods are PMQuery::queryRakNet() and PMQuery::queryNetherNet(). NetherNet querying retrieves status metadata only; it does not perform a WebRTC join or create a gameplay connection. HTTP requests are performed with stream sockets, bounded response sizes, and socket timeouts. Plain HTTP is the default; the library never upgrades an HTTP request to HTTPS. TLS peer verification is applied only when the caller explicitly supplies an https:// URL.

For NetherNet results, IPv4Port and IPv6Port are populated by resolving the original query hostname through the system resolver. Each field contains the query port when that address family is available, or 0 when it is not. These legacy fields contain port numbers, not IP address strings. NintendoLimited and Extra are always null for NetherNet because the /v1/join status response does not provide those RakNet-specific values. You can read the official documentation of Nethernet signaling on minecraft protocol.