PHP-Minecraft-Query: Monitorea tu Servidor en Tiempo Real

Si ejecutas un servidor Minecraft y quieres verificar quién está jugando o si el servidor realmente funciona sin lanzar el juego, esta librería PHP te ahorra tiempo. Extrae datos en vivo del servidor a través del protocolo Minecraft con solo algunas líneas de código.

Qué Hace este Proyecto

PHP-Minecraft-Query es una librería que te permite hacer preguntas a un servidor Minecraft remotamente. Piénsalo como si pincharas un servidor para ver si está despierto y qué está haciendo. Con 740 estrellas en GitHub y construida en PHP, ha sido confiable para desarrolladores durante años.

La librería te ofrece dos formas principales de obtener información. La primera se llama Ping, que es el enfoque más simple. Ha existido desde Minecraft 1.7 y usa el mismo protocolo que tu cliente cuando haces clic en "actualizar servidor" en el menú multijugador. Te dirá el MOTD (mensaje del día) del servidor, la cantidad de jugadores y una muestra de quién está en línea.

También podrías usar RCON si quieres enviar comandos de consola a un servidor remotamente, aunque la librería te señala hacia un proyecto separado para esa necesidad específica.

Cuándo Usarías Esto

Digamos que ejecutas un pequeño servidor y quieres un panel de control que muestre quién está en línea ahora. O quizás estés construyendo un sitio web de navegador de servidores Minecraft y necesites extraer conteos de jugadores en vivo de docenas de servidores. Esta librería lo maneja.

Los administradores de red la usan para monitorear si sus servidores se cayeron. Algunos desarrolladores la usan para construir bots de Discord que respondan a comandos como "!status" con información en vivo del servidor. También podrías usarla para scripts automatizados que te alerten cuando un servidor se caiga (muy útil si estás alojando para amigos y no quieres mensajes sorpresa a las 2 AM).

Si estás construyendo algo en minecraft.how como una herramienta de seguimiento de servidores o integración con nuestro Generador de Propiedades de Servidor, este es el tipo de librería que usarías para verificar que tus configuraciones realmente funcionaron.

Instalación y Primeros Pasos

Hacerla funcionar es sencillo. Pon esto en tu proyecto:

composer require xpaw/php-minecraft-query

Eso es todo para la instalación. La librería requiere PHP 8.0 o superior (la versión 5.0.0 aumentó la versión mínima, lo cual es una buena señal de que el proyecto se mantiene moderno).

Aquí está el ejemplo más simple. Creas un objeto MinecraftPing, llamas a Query() y devuelve toda la información del servidor:

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();
 }
}

Una cosa a tener en cuenta: siempre cierra la conexión cuando termines. Eso es lo que hace el bloque finally. Es un pequeño detalle pero previene fugas de conexión si estás ejecutando esto repetidamente.

Ping vs Query, Entendiendo la Diferencia

La gente se confunde sobre cuándo usar qué método, así que aclaremos eso.

Ping es la opción ligera. No requiere ninguna configuración del servidor. Solo apuntas a la IP y puerto del servidor (normalmente 25565) y funciona de inmediato. A cambio, obtienes el nombre del servidor, MOTD, cantidad de jugadores, máximo de jugadores y una pequeña muestra de nombres de jugadores. Es rápido y confiable porque usa el mismo protocolo que los jugadores usan cada vez que se conectan.

Ping también tiene compatibilidad hacia atrás. La librería incluye un método QueryOldPre17 si de alguna manera necesitas consultar un servidor que ejecuta Minecraft 1.6 o más antiguo (improbable, pero está ahí).

Query es el método pesado. Usa el protocolo GameSpy4 y requiere que el administrador del servidor lo habilite explícitamente en server.properties estableciendo enable-query=true. La recompensa es que obtienes la lista completa de jugadores y una lista completa de complementos instalados. Pero este método es más frágil.

Aquí está mi opinión: usa Ping a menos que específicamente necesites la lista completa de complementos o los nombres exactos de los jugadores. Es menos propenso a romperse cuando un servidor se actualiza o actúa de forma extraña.

Ejemplos Reales que Podrías Construir

Digamos que quieres verificar si un servidor está funcionando antes de mostrarlo en un sitio web. Envolverías la llamada de Query en un try-catch, y si falla, sabes que el servidor es inaccesible u offline.

O imagina construir un script de monitoreo que se ejecuta cada 5 minutos y registra conteos de jugadores en una base de datos. Podrías graficar esos números a lo largo del tiempo para ver cuándo juega más tu comunidad. Útil para planificar eventos o saber cuándo actualizar recursos del servidor.

Para servidores Bedrock (Minecraft en consolas, móvil y Windows 10/11), la librería tiene un método ConnectBedrock que funciona de la misma manera pero se conecta al puerto 19132 en su lugar. Así que si estás rastreando una red mixta de Java y Bedrock, esta librería maneja ambas.

Un detalle que vale la pena destacar: la librería intenta automáticamente resolver registros DNS de SRV. Si un servidor usa un registro SRV para enrutar tráfico, lo descubre automáticamente. Puedes deshabilitarlo pasando false como el cuarto parámetro si solo quieres consultas directas de IP.

Dónde Fallan las Cosas (y Cómo Arreglarlas)

La mayor trampa es confundir Query con Ping. Escribirás código esperando que el método Query funcione, lo dispararás a un servidor aleatorio y obtendrás una excepción. El servidor probablemente no tiene la consulta habilitada. Cambia a Ping en su lugar.

Otra cosa: tiempos de espera. Si estás consultando muchos servidores o la red es lenta, las conexiones podrían agotarse. El constructor toma un parámetro de tiempo de espera (en segundos) que puedes ajustar. El predeterminado es 4, que funciona para la mayoría de los casos, pero en redes lentas podrías necesitar 8 o 10.

La codificación de cadenas es otra capa. Las versiones recientes decodifican cadenas de ISO-8859-1, así que si ves caracteres garrapateados en MOTDs del servidor, es por eso. Solo algo a tener en cuenta si estás mostrando esas cadenas en un sitio web.

El README tiene una advertencia justo en la parte superior: no abras problemas si no puedes recuperar información de un servidor a menos que hayas confirmado que es realmente un error de librería. La mayoría de las veces, si Query no funciona, es porque el servidor no tiene la consulta habilitada. Verifica tu archivo server.properties. Y si estás consultando a través de internet, verifica tu firewall.

Herramientas Similares y Cuándo Buscar en Otro Lugar

Si necesitas enviar comandos de consola a un servidor, el proyecto recomienda PHP Source Query para funcionalidad RCON. Está construida por el mismo autor y maneja ese caso de uso específico mejor.

Para usuarios de JavaScript, existen librerías similares en el ecosistema de Node.js. Y si no estás usando PHP en absoluto, hay librerías de consulta en la mayoría de los lenguajes de programación. Pero si ya estás en PHP, esta es la opción sólida.

Una última cosa: esta librería ha sido mantenida consistentemente y el lanzamiento más reciente aumentó el PHP mínimo a 8.0, lo que muestra que el mantenedor la mantiene contemporánea. No está abandonada y realmente mejora con el tiempo.