README

Translations: Español

PHP library to get live statistics about players on Minecraft servers.

Requirements
Relevant details
Installation
Available Classes
- MinecraftServer Class
- MinecraftPlayerStat Instance
Exceptions Used
Usage
Tests
TODO
Changelog
Contribution
Sponsor
License

Requirements

This library is compatible with the PHP versions: 8.1.
Minecraft Server: Spigot.
Minecraft Versión: 1.17.
Operating System: Linux | Windows.

Relevant details

This library was developed for an application running from the PHP command line (CLI), specifically to power a Twitch bot that displayed live player statistics. I do not recommend using it for a web environment, although it will work.
It probably works for recent versions of the Spigot server, but I can't say for sure as it has only been tested with the requirements detailed above. Feel free to add new tests for other servers or Minecraft versions.
The available terms are set from the minecraft-assets repository of InventivetalentDev.

Installation

The preferred way to install this extension is through Composer.

To install PHP Minecraft Server Player Stat library, simply:

composer require josantonius/minecraft-server-player-stat

The previous command will only install the necessary files, if you prefer to download the entire source code you can use:

composer require josantonius/minecraft-server-player-stat --prefer-source

You can also clone the complete repository with Git:

git clone https://github.com/josantonius/php-minecraft-server-player-stat.git

Available Classes

MinecraftServer Class

Josantonius\MinecraftServerPlayerStat\MinecraftServer

Create a new instance for the Minecraft server:

/**
 * @param string $version     Server version.
 * @param string $language    Server language.
 * @param string $logsPath    Server logs directory path.
 * @param string $statsPath   Server stats directory path.
 * @param string $storagePath Directory path where available terms and players will be stored.
 *
 * @throws MinecraftServerException      if the Minecraft version or language is not valid.
 * @throws UnreadableDirectoryException  if the logs or stats path is not valid.
 * @throws UnwriteableDirectoryException if the storage path is not valid.
 *
 * @see https://mcasset.cloud/1.19.2/assets/minecraft/lang to see available languages.
 */
public function __construct(
    private string $version,
    private string $language,
    private string $logsPath,
    private string $statsPath,
    private string $storagePath,
);

Gets details about certain player statistics:

/**
 * @param string $username Username in case insensitive.
 * @param string $term     Literal Minecraft term in case insensitive.
 *                         In Spanish, a term with accents can be written without them. 
 *                         For another languages accents are required.
 *
 * @throws WrongTermException       if the term is not valid.
 * @throws StatsNotFoundException   if the stats file is not found.
 * @throws UnknownUsernameException if the username is not valid.
 */
public function getPlayerStat(string $username, string $term): MinecraftPlayerStat;

Get list of available statistics:

public function getAvailableStats(): array;

Get list of players from the server:

public function getPlayerList(): array;

MinecraftPlayerStat Instance

Josantonius\MinecraftServerPlayerStat\MinecraftPlayerStat

Number of broken items or null if there are no statistics:

public readonly int|null $broken;

Number of crafted items or null if there are no statistics:

public readonly int|null $crafted;

Number of dropped items or null if there are no statistics:

public readonly int|null $dropped;

Number of killed mobs or null if there are no statistics:

public readonly int|null $killed;

Number of killed by mobs or null if there are no statistics:

public readonly int|null $killedBy;

Number of mined items or null if there are no statistics:

public readonly int|null $mined;

Number of picked up items or null if there are no statistics:

public readonly int|null $pickedUp;

Number of used items or null if there are no statistics:

public readonly int|null $used;

Custom statistics value or null if there are no statistics:

/**
 * If the unit type is distance, this value is given in centimeters.
 * If the unit type is time, this value is given in ticks.
 * 
 * @see https://minecraft.fandom.com/wiki/Tutorials/Units_of_measure to see the unit conversions.
 */
public readonly int|null $custom;

Sanitized key for the term:

public readonly string $key;

Term expressed in a nice way:

public readonly string $prettyTerm;

Query term:

public readonly string $term;

Item type:

/**
 * Available types: block, entity, item, stat.
 */
public readonly string $type;

Unit type:

/**
 * Available types: amount, distance, time.
 */
public readonly string $unitType;

Username for which the query is being made:

public readonly string $username;

User UUID for which the query is being made:

public readonly string $uuid;

Exceptions Used

Example of use for this library:

use Josantonius\MinecraftServerPlayerStat\Exceptions\WrongTermException;
use Josantonius\MinecraftServerPlayerStat\Exceptions\StatsNotFoundException;
use Josantonius\MinecraftServerPlayerStat\Exceptions\UnknownUsernameException;
use Josantonius\MinecraftServerPlayerStat\Exceptions\MinecraftServerException;
use Josantonius\MinecraftServerPlayerStat\Exceptions\UnreadableDirectoryException;
use Josantonius\MinecraftServerPlayerStat\Exceptions\UnwriteableDirectoryException;