PHP-Minecraft-Query: How to Monitor Your Server Status in Real Time

If you're running a Minecraft server and want to check who's playing or if the server's actually up without launching the game itself, this PHP library saves you time. It pulls live server data through the Minecraft protocol with just a few lines of code.

What This Project Actually Does

PHP-Minecraft-Query is a library that lets you ask a Minecraft server questions remotely. Think of it like poking a server to see if it's awake and what it's doing. With 740 stars on GitHub and built in PHP, it's been quietly trusted by developers for years.

The library gives you two main ways to get information. This first is called Ping, which is the simpler approach. It's been around since Minecraft 1.7 and uses the same protocol your client uses when you click "refresh server" in the multiplayer menu. It'll tell you the server's MOTD (message of the day), player count, and a sample of who's online.

You could also use RCON if you want to send console commands to a server remotely, though the library points you toward a separate project for that specific need.

When You'd Actually Use This

Let's say you run a small server and want a dashboard showing who's online right now. Or maybe you're building a Minecraft server browser website and need to pull live player counts from dozens of servers. And this library handles that.

Network admins use it to monitor whether their servers crashed. Some developers use it to build Discord bots that respond to commands like "!status" with live server info. You could also use it for automated scripts that alert you when a server goes down (actually useful if you're hosting for friends and don't want surprised messages at 2 AM).

If you're building something on minecraft.how like a server tracking tool or integration with our Server Properties Generator, this is the kind of library you'd reach for to verify your settings actually worked.

Installation and Getting Started

Getting it running is straightforward. Drop this into your project:

composer require xpaw/php-minecraft-query

That's it for installation. The library requires PHP 8.0 or higher (version 5.0.0 bumped the minimum version, which is a good sign the project stays modern).

Here's the simplest example. You create a MinecraftPing object, call Query(), and it returns all the server's info:

require __DIR__. '/vendor/autoload.php';

use xPaw\MinecraftPing;
use xPaw\MinecraftPingException;

$Query = null;

try
{
 $Query = new MinecraftPing( 'localhost', 25565 );
 print_r( $Query->Query() );
}
catch( MinecraftPingException $e )
{
 echo $e->getMessage();
}
finally
{
 if( $Query!== null )
 {
 $Query->Close();
 }
}

One thing to note: always close the connection when you're done. That's what the finally block does. It's a small detail but prevents connection leaks if you're running this repeatedly.

Ping vs Query: Understanding the Difference

People get confused about when to use which method, so let's clear that up.

Ping is the lightweight option. It doesn't require any server configuration. You just point it at the server's IP and port (usually 25565), and it works immediately. In return, you get the server name, MOTD, player count, max players, and a small sample of player names. It's fast and reliable because it uses the same protocol players use every time they connect.

Ping also has backward compatibility. The library includes a QueryOldPre17 method if you somehow need to query a server running Minecraft 1.6 or older (unlikely, but it's there).

Query is the heavy-hitter. It uses the GameSpy4 protocol and requires the server admin to enable it explicitly in server.properties by setting enable-query=true. The payoff is you get the complete player list and a full list of installed plugins. But this method is more brittle.

Here's my take: use Ping unless you specifically need the full plugin list or the exact player names. It's less prone to breaking when a server updates or acts weird.

Real Examples You Could Build

Let's say you want to check if a server is running before displaying it on a website. You'd wrap the Query call in a try-catch, and if it fails, you know the server is unreachable (or offline).

Or imagine building a monitoring script that runs every 5 minutes and logs player counts to a database. You could then graph those numbers over time to see when your community plays most. Useful for planning events or knowing when to upgrade server resources.

For Bedrock servers (Minecraft on consoles, mobile, and Windows 10/11), the library has a ConnectBedrock method that works the same way but connects to port 19132 instead. So if you're tracking a mixed Java and Bedrock network, this library handles both.

One detail worth highlighting: the library automatically tries to resolve SRV DNS records. If a server uses a SRV record to route traffic, it figures that out automatically. You can disable this by passing false as the fourth parameter if you want direct IP queries only.

Where Things Break (and How to Fix Them)

The biggest gotcha is confusing Query with Ping. You'll write code expecting the Query method to work, fire it at a random server, and get an exception. The server probably doesn't have query enabled. Switch to Ping instead.

Another thing: timeouts. If you're querying a lot of servers or the network is slow, connections might time out. The constructor takes a timeout parameter (in seconds) that you can adjust. Default is 4, which works for most cases, but on slow networks you might need 8 or 10.

String encoding is another layer. Recent versions decode strings from ISO-8859-1, so if you're seeing garbled characters in server MOTDs, that's why. Just something to be aware of if you're displaying those strings on a website.

The README has a warning right at the top: don't open issues if you can't retrieve information from a server unless you've confirmed it's actually a library bug. Most of the time, if Query doesn't work, it's because the server doesn't have querying enabled. Check your server.properties file. And if you're querying across the internet, check your firewall.

Similar Tools and When to Look Elsewhere

If you need to send console commands to a server, the project recommends PHP Source Query for RCON functionality. That's built by the same author and handles that specific use case better.

For JavaScript users, similar libraries exist in the Node.js ecosystem. And if you're not using PHP at all, there are query libraries in most programming languages. But if you're already in PHP, this is the solid choice.

One last thing: this library has been maintained consistently and the latest release bumped the minimum PHP to 8.0, which shows the maintainer keeps it contemporary. It's not abandoned, and it actually improves over time.