Minecraft Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require codingbyjerez/minecraft-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       CodingByJerez\MinecraftBundle\MinecraftBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php artisan vendor:publish --provider="CodingByJerez\MinecraftBundle\MinecraftBundle" --tag="config"
   

   Edit config/minecraft.php to include your server’s IP, port, and timeout (default: 5s).

3. First Use Case Inject the MinecraftService into a controller or command:

   use CodingByJerez\MinecraftBundle\Service\MinecraftService;
   
   public function checkServerStatus(MinecraftService $minecraft)
   {
       $status = $minecraft->getServerStatus();
       return response()->json($status);
   }
   

   Call the endpoint (e.g., /api/minecraft/status) to see server details like player count, version, and online status.

Implementation Patterns

Common Workflows

1. Real-Time Status Monitoring Use a Laravel Queue Job to periodically fetch server status and store it in the database:

   use CodingByJerez\MinecraftBundle\Service\MinecraftService;
   use Illuminate\Bus\Queueable;
   
   class CheckMinecraftStatus implements ShouldQueue
   {
       use Queueable;
   
       public function handle(MinecraftService $minecraft)
       {
           $status = $minecraft->getServerStatus();
           ServerStatus::updateOrCreate(
               ['server_id' => 1],
               ['players_online' => $status['players']['online'], 'last_checked' => now()]
           );
       }
   }
   

   Schedule with Laravel’s scheduler:

   $schedule->command('check:minecraft')->everyMinute();
   

2. API Endpoint for External Services Create a dedicated route and controller:

   Route::get('/minecraft/status', [MinecraftController::class, 'status']);
   

   public function status(MinecraftService $minecraft)
   {
       return response()->json($minecraft->getServerStatus());
   }
   

   Secure with middleware (e.g., auth:api) if needed.

3. Integration with Frontend Use Laravel Echo or Livewire to push real-time updates to users:

   // Livewire example
   <script>
       window.addEventListener('minecraft-updated', event => {
           console.log('Players online:', event.detail.players_online);
       });
   </script>
   

   Dispatch events from your job/controller:

   broadcast(new MinecraftStatusUpdated($status))->toOthers();
   

4. Customizing Status Data Extend the service to include additional logic:

   $status = $minecraft->getServerStatus();
   $customData = [
       'is_popular' => $status['players']['online'] > 50,
       'uptime' => now()->diffInHours($status['last_seen']),
   ];
   

Gotchas and Tips

Pitfalls

1. Connection Timeouts

   • Default timeout (5s) may be too short for slow servers. Increase in config/minecraft.php:

     'timeout' => 10, // seconds
     

   • Handle exceptions gracefully:

     try {
         $status = $minecraft->getServerStatus();
     } catch (\RuntimeException $e) {
         return response()->json(['error' => 'Server unreachable'], 503);
     }
     

2. Firewall/Network Restrictions

   • Ensure your server’s port (default: 25565) is open and not blocked by firewalls.
   • Test connectivity manually:

     telnet your_minecraft_server_ip 25565
     

3. Rate Limiting

   • Avoid flooding the Minecraft server with requests. Cache results:

     $status = Cache::remember('minecraft_status', now()->addMinutes(1), function () use ($minecraft) {
         return $minecraft->getServerStatus();
     });
     

Debugging

• Enable Debug Mode Set 'debug' => true in config/minecraft.php to log raw responses for troubleshooting.

• Common Errors

  • "Connection refused": Verify the server IP/port and firewall rules.
  • Empty response: Check if the server supports the RakNet protocol (most modern servers do).
  • Deprecated methods: Monitor for updates if the package lacks maintenance.

Extension Points

1. Custom Status Fields Override the service to add proprietary data:

   namespace App\Services;
   
   use CodingByJerez\MinecraftBundle\Service\MinecraftService as BaseService;
   
   class CustomMinecraftService extends BaseService
   {
       public function getServerStatus()
       {
           $status = parent::getServerStatus();
           $status['custom_field'] = $this->fetchCustomData();
           return $status;
       }
   }
   

   Bind the custom service in AppServiceProvider:

   $this->app->bind(MinecraftService::class, CustomMinecraftService::class);
   

2. Multiple Servers Configure multiple servers in config/minecraft.php:

   'servers' => [
       'main' => ['ip' => '127.0.0.1', 'port' => 25565],
       'backup' => ['ip' => '192.168.1.100', 'port' => 25566],
   ],
   

   Access via:

   $minecraft->getServerStatus('backup');
   

3. Testing Mock the service in PHPUnit:

   $this->mock(MinecraftService::class)->shouldReceive('getServerStatus')
       ->once()
       ->andReturn(['players' => ['online' => 10]]);