PHP library to check Minecraft Servers Status
Clone or download
Latest commit 7a9d458 Jan 2, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src Completed MCPing Oct 6, 2018
tests/Features Added unit tests Jan 2, 2019
.editorconfig Completed MCPing Oct 6, 2018
.gitignore Completed MCPing Oct 6, 2018
CHANGELOG.md Updated readme Oct 7, 2018
LICENSE Added license Oct 7, 2018
README.md Updated readme Dec 13, 2018
composer.json Added unit tests Jan 2, 2019

README.md

Minecraft Server Status

Latest Stable Version Total Downloads License PHP

This library can be used to check Minecraft Servers Status for some basic information.

⚠ 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.

Differences between Ping and Query

There are two methods of retrieving information about a Minecraft server.

  • Ping

    Ping protocol was added in Minecraft 1.7 and is used to query the server for minimal amount of information (hostname, motd, icon, and a sample of players). This is easier to use and doesn't require extra setup on server side. It uses TCP protocol on the same port as you would connect to your server an optional parameter IsOld17 which can be used to query servers on version 1.6 or older. N.B.: this method doesn't work with Minecraft: Bedrock Edition

  • Query

    This method uses GameSpy4 protocol, and requires enabling query listener in your server.properties like this:

    enable-query=true

    query.port=25565

    Query allows to request a full list of servers' plugins and players, however this method is more prone to breaking, so if you don't need all this information, stick to the ping method as it's more reliable.

Requirements

  • PHP >= 5.6
  • Json Extension
  • Iconv Extension

Installation

You can install this library with composer:

composer require lukasss93/minecraft-server-status

Using

MCPing

Using

<?php
	//using the class
	use MCServerStatus\MCPing;
	
	//include composer autoload
	require_once('../vendor/autoload.php');
	
	//checking account
	$response=MCPing::check('hostname or IP');
	
	//get informations from object
	var_dump($response);
	
	//or from array
	var_dump($response->toArray());
?>

If you want to get ping info from a server that uses a version older than Minecraft 1.7, then add true parameter after $timeout.

Please note that this library does resolve SRV records too.

Input

The check() method has 4 optional parameters:

# Parameter Type Default Description
1 host string 127.0.0.1 Server Hostname or IP address
2 port int 25565 Server port
3 timeout int 2 Timeout (in seconds)
4 isOld17 bool false Boolean value to find informations on servers that uses a version older than Minecraft 1.7

Output

The check() method return an object with the following properties:

Key Type Description
online bool Returns true if the server is online else false
error string Returns any error message
hostname string Returns the server hostname or IP address
address string Returns server IP address
port int Returns the server port
ping int Returns server ping
version string Returns the server version
protocol int Returns the server protocol
players int Returns the number of online players
max_players int Returns the maximum number of players that can enter the server
sample_player_list array Returns a partial list of online players
motd string Returns server description
favicon string Returns an image in Base64 string
mods array Returns a list of installed mods on the server

You can use the following methods after check() method:

Method Description
toArray() Return the object properties as an array
getMotdToText() Get the motd without the format codes
getMotdToHtml() Get the motd as HTML

MCQuery

Using

<?php
	//using the class
	use MCServerStatus\MCQuery;
	
	//include composer autoload
	require_once('../vendor/autoload.php');
	
	//checking account
	$response=MCQuery::check('hostname or IP');
	
	//get informations from object
	var_dump($response);
	
	//or from array
	var_dump($response->toArray());
?>

Input

The check() method has 4 optional parameters:

# Parameter Type Default Description
1 host string 127.0.0.1 Server Hostname or IP address
2 port int 25565 Server query port
3 timeout int 2 Timeout (in seconds)
4 resolveSRV bool true Resolve SRV record

Output

The check() method return an array with the following properties:

Key Type Description
online bool Returns true if the server is online else false
error string Returns any error message
hostname string Returns the server hostname or IP address
address string Returns server IP address
port int Returns the server port
version string Returns the server version
software string Returns the server software
game_type string Returns the server software type
game_name string Return the server software name
players int Returns the number of online players
max_players int Returns the maximum number of players that can enter the server
player_list array Returns a list of online players
motd string Returns server description
map string Returns the server map name
plugins array Returns a list of installed plugins on the server

You can use the following methods after check() method:

Method Description
toArray() Return the object properties as an array
getMotdToText() Get the motd without the format codes
getMotdToHtml() Get the motd as HTML

Changelog

All notable changes to this project will be documented here.

Recent changes

[2.0]

  • First release