PHP-Minecraft-Query: Monitor Servidor em Tempo Real

Se você está executando um servidor Minecraft e quer verificar quem está jogando ou se o servidor realmente está ativo sem iniciar o jogo, esta biblioteca PHP economiza seu tempo. Ela puxa dados ao vivo do servidor através do protocolo Minecraft com apenas algumas linhas de código.

O que Este Projeto Faz

PHP-Minecraft-Query é uma biblioteca que permite fazer perguntas a um servidor Minecraft remotamente. Pense nela como dar um toque em um servidor para ver se ele está acordado e o que está fazendo. Com 740 estrelas no GitHub e construída em PHP, ela é confiável pelos desenvolvedores há anos.

A biblioteca oferece duas formas principais de obter informações. A primeira é chamada Ping, que é a abordagem mais simples. Ela existe desde o Minecraft 1.7 e usa o mesmo protocolo que seu cliente usa quando você clica em "atualizar servidor" no menu multijogador. Ela vai te dizer o MOTD (mensagem do dia) do servidor, contagem de jogadores e uma amostra de quem está online.

Você também pode usar RCON se quiser enviar comandos de console para um servidor remotamente, embora a biblioteca o aponte para um projeto separado para essa necessidade específica.

Quando Você Usaria Isso

Digamos que você execute um pequeno servidor e queira um painel mostrando quem está online agora. Ou talvez você esteja construindo um site navegador de servidor Minecraft e precise extrair contagens de jogadores ao vivo de dezenas de servidores. E esta biblioteca faz isso.

Administradores de rede a usam para monitorar se seus servidores falharam. Alguns desenvolvedores a usam para criar bots do Discord que respondem a comandos como "!status" com informações ao vivo do servidor. Você também pode usá-la para scripts automatizados que o alertam quando um servidor fica offline (realmente útil se você está hospedando para amigos e não quer mensagens surpresa às 2 da manhã).

Se você está construindo algo no minecraft.how como uma ferramenta de rastreamento de servidor ou integração com nosso Gerador de Propriedades do Servidor, este é o tipo de biblioteca que você buscaria para verificar se suas configurações realmente funcionaram.

Instalação e Primeiros Passos

Fazer isso funcionar é direto. Coloque isto no seu projeto:

composer require xpaw/php-minecraft-query

É isso para a instalação. A biblioteca requer PHP 8.0 ou superior (a versão 5.0.0 elevou a versão mínima, o que é um bom sinal de que o projeto se mantém moderno).

Aqui está o exemplo mais simples. Você cria um objeto MinecraftPing, chama Query() e ele retorna todas as informações do 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();
 }
}

Uma coisa a notar: sempre feche a conexão quando terminar. É o que o bloco finally faz. É um pequeno detalhe, mas evita vazamento de conexão se você estiver executando isso repetidamente.

Ping vs Query, Entendendo a Diferença

As pessoas ficam confusas sobre quando usar qual método, então vamos deixar isso claro.

Ping é a opção leve. Não requer nenhuma configuração do servidor. Você simplesmente aponta para o IP e porta do servidor (geralmente 25565) e funciona imediatamente. Em troca, você obtém o nome do servidor, MOTD, contagem de jogadores, máximo de jogadores e uma pequena amostra de nomes de jogadores. É rápido e confiável porque usa o mesmo protocolo que os jogadores usam toda vez que se conectam.

Ping também tem compatibilidade retroativa. A biblioteca inclui um método QueryOldPre17 se você precisar de alguma forma consultar um servidor executando Minecraft 1.6 ou anterior (improvável, mas está lá).

Query é o peso pesado. Ele usa o protocolo GameSpy4 e requer que o administrador do servidor o ative explicitamente em server.properties definindo enable-query=true. O ganho é que você obtém a lista completa de jogadores e uma lista completa de plugins instalados. Mas este método é mais frágil.

Aqui está minha opinião: use Ping a menos que você especificamente precise da lista completa de plugins ou dos nomes exatos dos jogadores. É menos propenso a quebrar quando um servidor atualiza ou age estranho.

Exemplos Reais Que Você Poderia Construir

Digamos que você queira verificar se um servidor está executando antes de exibi-lo em um site. Você envolveria a chamada Query em um try-catch, e se falhar, você sabe que o servidor está inacessível (ou offline).

Ou imagine construir um script de monitoramento que é executado a cada 5 minutos e registra contagens de jogadores em um banco de dados. Você poderia então gráfico esses números ao longo do tempo para ver quando sua comunidade joga mais. Útil para planejar eventos ou saber quando atualizar recursos do servidor.

Para servidores Bedrock (Minecraft em consoles, celular e Windows 10/11), a biblioteca tem um método ConnectBedrock que funciona da mesma forma, mas se conecta à porta 19132. Portanto, se você está rastreando uma rede mista de Java e Bedrock, esta biblioteca lida com ambos.

Um detalhe que vale a pena destacar: a biblioteca tenta automaticamente resolver registros SRV de DNS. Se um servidor usar um registro SRV para rotear tráfego, ela descobre automaticamente. Você pode desabilitar isso passando false como o quarto parâmetro se quiser apenas consultas de IP direto.

Onde as Coisas Quebram (e Como Corrigi-las)

A maior pegadinha é confundir Query com Ping. Você escreverá código esperando que o método Query funcione, o disparará em um servidor aleatório e obterá uma exceção. O servidor provavelmente não tem query ativada. Mude para Ping em vez disso.

Outra coisa: timeouts. Se você estiver consultando muitos servidores ou a rede for lenta, as conexões podem expirar. O construtor recebe um parâmetro de timeout (em segundos) que você pode ajustar. O padrão é 4, o que funciona na maioria dos casos, mas em redes lentas você pode precisar de 8 ou 10.

Codificação de string é outra camada. Versões recentes decodificam strings de ISO-8859-1, portanto, se você estiver vendo caracteres confusos nos MOTDs do servidor, é por isso. Apenas algo a estar ciente se você estiver exibindo essas strings em um site.

O README tem um aviso bem no topo: não abra issues se você não conseguir recuperar informações de um servidor, a menos que você tenha confirmado que é realmente um bug da biblioteca. Na maioria das vezes, se Query não funcionar, é porque o servidor não tem querying ativada. Verifique seu arquivo server.properties. E se você está consultando pela internet, verifique seu firewall.

Ferramentas Similares e Quando Procurar em Outro Lugar

Se você precisa enviar comandos de console para um servidor, o projeto recomenda PHP Source Query para funcionalidade RCON. Que foi construída pelo mesmo autor e lida melhor com esse caso de uso específico.

Para usuários de JavaScript, bibliotecas similares existem no ecossistema Node.js. E se você não está usando PHP, há bibliotecas de query na maioria das linguagens de programação. Mas se você já está em PHP, esta é a escolha sólida.

Uma última coisa: esta biblioteca foi mantida consistentemente e o lançamento mais recente elevou o PHP mínimo para 8.0, o que mostra que o mantenedor a mantém contemporânea. Não é abandonada, e na verdade melhora ao longo do tempo.