README

Lightweight PHP client for Minecraft RCON with support for multi-packet responses. sendCommand() returns the full output of a command, also when the output is longer than 4096 bytes. Based on PHP-Minecraft-Rcon by thedudeguy.

composer require stilling/minecraft-rcon

The package requires PHP 8.3 or later.

Quick start

use Stilling\MinecraftRcon\Rcon;

$rcon = new Rcon("mc.example.com", 25575, "super-secret-password");
$rcon->connect();

$rcon->sendCommand("list");
// "There are 2 of a max of 20 players online: Alex, Steve"

$rcon->disconnect();

sendCommand() returns the response from the server as a string.

Large responses

Minecraft splits a response that is longer than 4096 bytes into several packets. sendCommand() reads all the packets of the response and joins them, so the output is not truncated. Commands such as help and data get entity <player> can give responses of this size.

Constructor arguments

Argument	Type	Default	Description
`host`	`string`		The server hostname or IP address.
`port`	`int`		The RCON port. The Minecraft default is `25575`.
`password`	`string`		The RCON password (`rcon.password` in `server.properties`).
`timeout`	`int`	`3`	The time in seconds to wait for the connection and for each response.

Connection state

isConnected() returns true after connect() succeeds. It returns false after disconnect(), and after the client finds that the connection is closed or not usable.

Errors

All exceptions extend Stilling\MinecraftRcon\Exceptions\RconException.

Exception	Thrown when
`AuthException`	The server rejects the password.
`ConnectionException`	The client cannot connect, `connect()` is called on a connected client, `sendCommand()` is called before `connect()`, or the server closes the connection.
`PacketException`	The command is too long (see Command length limit), or the server sends a packet with an invalid size.
`TimeoutException`	The server does not respond within the timeout.

After an AuthException, a closed connection, or an invalid packet from the server, the client is disconnected. Call connect() to connect again.

use Stilling\MinecraftRcon\Exceptions\RconException;
use Stilling\MinecraftRcon\Rcon;

$rcon = new Rcon("mc.example.com", 25575, "super-secret-password", timeout: 5);

try {
    $rcon->connect();
    $players = $rcon->sendCommand("list");
} catch (RconException $e) {
    // Log the error or show it to the user.
} finally {
    $rcon->disconnect();
}

disconnect() is safe to call when the client is not connected.

Command length limit

A command can be at most 1446 bytes. For a longer command, sendCommand() throws a PacketException and does not send the command.

Development

composer test
composer analyse

composer test starts a fake RCON server on 127.0.0.1:25575 and stops it when the tests end. If a server already listens on that port, the tests use it. The fake server writes its output to fake-server.log.

stilling / minecraft-rcon

Package info

Security

Statistics