php-minecraft-query: querying Minecraft servers from PHP

A small library with an unusually honest warning

PHP-Minecraft-Query is a PHP library to query Minecraft servers for some basic information, and it is published on Packagist as xpaw/php-minecraft-query under the MIT licence.

The first thing in the readme is a warning, and it is worth quoting because it sets the tone of the project. Please do not create issues when you are unable to retrieve information from a server, unless you can prove that there is a bug within the library.

That is a maintainer saying the difference between a broken library and an unreachable server is not always visible from the client side, and asking for evidence before the report. It is a reasonable position for a library that talks to servers you do not control, and it tells you that the support burden here is bounded by what the library can prove.

The implementation is a small source tree with a src directory and a tests directory, and the quality tooling is a full set, with a PHPStan configuration, a Psalm configuration and a PHPUnit configuration in the same repository. There are also two small viewer scripts at the root, view.php and view_serverping.php, which are the kind of small utility that tells you what the library is for.

The last push was on 2026-08-24, and the release history shows version 5.0.0 on 2024-10-18, after 4.0.1 in 2021 and 4.0.0 in 2019.

Ping is the default because it needs nothing on the server

There are two ways to ask a Minecraft server about itself, and the readme explains the difference in terms of what you need to change on the server.

The ping protocol was added in Minecraft 1.7 and is used to query the server for a minimal amount of information: the hostname, the motd, the icon and a sample of the players. It is easier to use and requires no extra setup on the server side, and it uses the TCP protocol on the same port you would connect to the server on. That last point is what makes it usable in practice, because a Minecraft server is already listening on that port and a status checker does not need a second one.

For servers older than 1.7 there is a separate path, because the protocol did not exist then. The MinecraftPing class contains a method called QueryOldPre17 which can be used to query servers on version 1.6 or older, so a library that supports a wide range of servers has to carry the old handshake as well as the new one.

The information you get back is a deliberate subset. The player list is a sample rather than the full roster, which is what the server chooses to return, and the icon is the small image the server advertises. For a status page or a server list, that is exactly the right amount, and it is why ping is the one to reach for first.

Query gives you everything and needs the server to cooperate

The second method uses the GameSpy4 protocol, and it is the one that returns the full picture.

Query allows you to request a full list of the server's plugins and players. To use it, the query listener has to be enabled in the server's server.properties file, with enable-query set to true and query.port set to 25565.

That requirement is the whole trade-off, and the readme is blunt about the consequence: this method is more prone to breaking, so if you do not need all this information, stick to the ping method as it is more reliable.

The code for the query path is short, and the shape of it is worth noting because the resource has to be closed even when the call fails:

$Query = new MinecraftQuery( );

try
{
    $Query->Connect( 'localhost', 25565 );

    print_r( $Query->GetInfo( ) );
    print_r( $Query->GetPlayers( ) );
}
catch( MinecraftQueryException $e )
{
    echo $e->getMessage( );
}

The exception type is specific to this library, MinecraftQueryException, so a caller can distinguish a failed query from any other failure. The information and the player list are separate calls, which means you can fetch the server description without paying for the player list.

Bedrock servers need a different connect call and a different port

Not every Minecraft server is a Java server, and the library handles the other kind with a different method rather than a different class.

For Bedrock servers, which the readme calls MCPE, you use ConnectBedrock instead of Connect:

$Query->ConnectBedrock( 'localhost', 19132 );

The port in that example is the Bedrock port rather than the Java one, and it is the kind of detail that trips people up when a status checker suddenly reports a Java server as offline and a Bedrock server as offline too, for entirely different reasons.

The rest of the API is shared. The same MinecraftQuery object, the same GetInfo and GetPlayers calls and the same exception type, so a status page that shows both kinds of server does not need two code paths.

That the library treats Bedrock as a variation rather than as a separate implementation is a reasonable design choice. The underlying protocol is different, RakNet rather than the Java protocol, and the topic list on the repository names both Minecraft and Bedrock along with the protocol names, but from the caller's point of view the difference is one method name and one port number.

SRV resolution happens unless you turn it off

A detail that will either save you or confuse you, depending on how you configure it.

The library automatically tries to resolve SRV records. If you do not wish it to do so, you pass false as the fourth parameter in the constructor, after the timeout parameter.

That is a sensible default in one direction and a trap in the other. The SRV record is the standard way for a Minecraft server to advertise the actual host and port to connect to, so resolving it is usually what you want, and the alternative is that your checker resolves a hostname that the server owner has never pointed at the game port.

The trouble is that the resolution adds a DNS lookup and a second network round trip to every query, and in a status checker that runs every thirty seconds against a hundred servers, that is a hundred DNS lookups you did not ask for. Being able to switch it off per instance, rather than globally, is what makes the default workable.

The constructor therefore takes a host, a port, a timeout, and this resolution flag, and the readme documents the order explicitly, which is the kind of detail that saves an hour when the fourth argument does not do what you assumed.

Remote console commands are deliberately someone else's job

The readme mentions RCON, and the way it does so is a good example of a library drawing a boundary around itself.

It is possible to send console commands to a Minecraft server remotely using the Source RCON protocol. The readme then tells you to use the PHP Source Query library for your RCON needs.

That is a different repository, also by the same author, and the split is the interesting part. Querying a server for information is a read operation on public data that any client can attempt, while sending console commands is a privileged operation that requires a password and can change anything on the server. Bundling the two would put an administrative capability in a package that most people install for a status widget, and the dependencies of the RCON protocol would come along for the ride.

So the package stays small, with one job, and the escalation path is a separate library that you only add if you need it. That is the more common design in this ecosystem, and it is the reason the dependency list of a status checker can be short.

The installation is correspondingly simple, one Composer command:

composer require xpaw/php-minecraft-query

Editorial conclusion

php-minecraft-query fits a PHP application that needs to display whether a game server is up, who is on it and what it is running, because the ping path needs no server side configuration and the library resolves SRV records and handles Bedrock addresses for you. It is the wrong choice if you need to run commands on the server, because remote console access is deliberately out of scope and the readme points you at a separate library for the Source RCON protocol, and it is the wrong choice if you need a guaranteed result, because the query protocol depends on a server side setting that most operators never enable. Before you adopt it, decide whether ping alone is enough, because the difference in setup on the server side is the whole decision, and remember that the ping information is a sample of the player list rather than the full roster.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. xPaw/PHP-Minecraft-Query on GitHub