Minecraft Server List

A small PHP application that checks Minecraft servers and stores their status in PostgreSQL. The Docker setup runs a Postgres database and a poller that refreshes server status every 60 seconds.

The source is structured by responsibility:

• src/Entity: domain entities (Server, ServerStatus)
• src/Repository: data access repositories
• src/Infrastructure: implementation details (Doctrine DBAL connection + Minecraft status client)

Run

php -S 127.0.0.1:8080 -t public

Then open http://127.0.0.1:8080.

Run With Docker Compose

Copy the environment template first:

cp env.example .env

Then edit .env with your credentials/host values and start:

docker compose up

Then open http://127.0.0.1:${APP_PORT} (default: 2555).

Admin panel is available at http://127.0.0.1:${APP_PORT}/admin/ and requires ADMIN_PASSWORD from .env.

The poller service checks each configured server and writes the current status to Postgres every 60 seconds. The web app serves the latest stored status from the database. Both app and poller install Composer dependencies on container start. Credentials and database IP/host are loaded from .env. The server list is stored in the servers database table and can be managed in the admin panel.

Static Analysis

Install development dependencies and run Psalm:

composer install
composer psalm

Database Layer

The database layer uses Doctrine DBAL (doctrine/dbal) for connection management and SQL execution.

Server list management is done through the admin UI at /admin/.

Notes

• The app uses the Minecraft Java status ping protocol.
• Vanilla Minecraft servers do not expose true process uptime through the status ping. The displayed uptime is observed uptime, starting when this app first sees the server online and resetting when it sees the server offline.
• You can adjust the per-server timeout with SERVER_CHECK_TIMEOUT, in seconds. The default is 3.