Download the PHP package dev-lancer/minecraft-status without Composer

Minecraft Status

Minecraft Status is a PHP 8.1+ library for reading Minecraft server information without running a Minecraft client.

Use it when you want to show server availability, MOTD, player counts, version, protocol, favicon, player samples or Query data in a website, panel, bot, monitor or backend job.

The library supports:

• Java Edition status ping, used by the Minecraft multiplayer server list;
• Java Edition GameSpy4 Query, when enable-query=true is enabled on the server;
• Bedrock Edition RakNet unconnected ping/pong;
• legacy Java ping for servers before Minecraft 1.7.

Installation

Install the package with Composer:

Requirements:

• PHP ^8.1;
• ext-json;
• ext-iconv;
• ext-mbstring.

The Basic Flow

Every client follows the same shape: instantiate it for a host, call fetch(), then read the typed result with getResult(). Use raw() or getInfo() only when you need the parsed protocol array.

fetch() returns the same client instance, so chaining is safe:

Your First Java Status Check

Most Java Edition servers should be queried with MinecraftJavaStatus. It uses the same TCP status ping that the Minecraft multiplayer screen uses.

The repository also contains a fuller Java example in examples/ping.php.

Choosing The Right Client

Pick the client by protocol, not only by server edition:

Start with MinecraftJavaStatus for Java servers. Query is optional server functionality and is commonly disabled on public servers.

Reading Typed Results

getResult() returns a result object. Every result object has these methods:

The common methods are enough for many dashboards:

Each protocol also exposes extra readonly properties:

For Java status, the players property is the sample returned by the server. Servers are allowed to return no sample even when players are online.

If a server sends a favicon, Java status exposes it as a data URI string:

Reading Raw Data

Use raw data when you need protocol fields that are not represented by the typed result yet.

getInfo() is kept for compatibility. New code should prefer getResult() for common fields and getResult()->raw() for raw protocol data.

Java Query

MinecraftJavaQuery uses the GameSpy4 Query protocol. It is not the same thing as normal Java status ping.

The Minecraft server must enable Query in server.properties:

Then query it:

Example file: examples/query.php

If Java status works but Query times out, the most likely reason is that Query is disabled or blocked by firewall rules.

Bedrock

Bedrock Edition uses UDP and usually listens on port 19132:

Example file: examples/bedrock.php

Bedrock status data is a length-prefixed, semicolon-delimited RakNet status string. The parser treats ; as a field separator and requires the expected Bedrock field count.

Vanilla Bedrock Dedicated Server treats server-name as a string without semicolons. This library does not try to guess or rebuild names that contain ;, because doing so could shift protocol, version, player count and port fields. Payloads with an unexpected field count are rejected as invalid responses.

Legacy Java

Use MinecraftJavaPreOld17Status only for old Java servers that still implement the legacy ping used before Minecraft 1.7:

Modern Java servers should use MinecraftJavaStatus instead.

Timeouts, Encoding And SRV Records

All clients accept host, port, timeout and SRV resolving flag:

Timeouts are seconds and accept int|float. The value must be greater than zero.

Set encoding when you need raw strings converted to a specific encoding:

SRV lookup is enabled by default. Pass false as the fourth constructor argument when you want to query the exact host and port:

SRV resolution ignores literal IPv4 and IPv6 hosts, validates SRV records, normalizes trailing dots and sorts candidates by priority ascending and weight descending.

Lifecycle

The lifecycle state describes the last fetch result:

disconnect() closes only the socket. It does not clear a successfully fetched result, so getResult() and getInfo() still work after disconnecting.

If a later fetch() fails, the previous result is cleared and status() becomes StatusState::Failed.

isConnected() only reports whether the socket is currently open. Use status() when you need to know whether parsed data is available.

Error Handling

Handle the specific exceptions when you want precise error messages:

TimeoutException, ProtocolException and InvalidResponseException extend ReceiveStatusException, so older catch (ReceiveStatusException $exception) blocks still work.

Convenience Getters

Typed results are the preferred API, but clients also expose convenience getters:

Additional client-specific getters:

Compatibility And Migration

connect() remains available as an alias of fetch() for older code:

The deprecated class aliases Ping, Query, QueryBedrock and PingPreOld17 still exist. New code should use MinecraftJavaStatus, MinecraftJavaQuery, MinecraftBedrockStatus and MinecraftJavaPreOld17Status.

See UPGRADE-4.0.md for migration notes from V3.

Development

Run the default checks:

Real public server smoke tests are opt-in. Create an ignored .servers-list.php file in the repository root, then run:

The real server config should return sections for java_status, java_query, bedrock, legacy_java and srv_java_status. Public servers are not reliable enough for the default test suite, so these tests are intentionally separate from composer test.

License

MIT