Windmill Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require cleentfaar/windmill-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Cleentfaar\WindmillBundle\CLWindmillBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console windmill:install
   

   Update config/packages/cleentfaar_windmill.yaml with your Windmill API key.

3. First Use Case Create a controller to fetch a chess game:

   use Cleentfaar\WindmillBundle\Service\WindmillService;
   
   class ChessController extends AbstractController
   {
       public function showGame(WindmillService $windmill): Response
       {
           $game = $windmill->getGame('game_id_here');
           return $this->render('chess/game.html.twig', ['game' => $game]);
       }
   }
   

Implementation Patterns

Core Workflows

1. Game Management

   • Fetch games: $windmill->getGame($id)
   • List games: $windmill->listGames($options)
   • Create moves: $windmill->makeMove($gameId, $move)
   • Update game state: $windmill->updateGame($gameId, $data)

2. Player Integration

   • Register players: $windmill->registerPlayer($playerData)
   • Fetch player stats: $windmill->getPlayerStats($playerId)

3. Event Listeners Subscribe to game events via Symfony’s event dispatcher:

   # config/services.yaml
   services:
       App\EventListener\ChessGameListener:
           tags:
               - { name: kernel.event_listener, event: windmill.game.created, method: onGameCreated }
   

Integration Tips

• API Rate Limiting: Cache responses aggressively (e.g., Symfony\Contracts\Cache\CacheInterface) to avoid hitting Windmill’s rate limits.

• Twig Integration: Extend Twig with custom filters for chess notation:

  {{ game.moves|chess_notation }}
  

  Register in twig.config.php:

  $twig->addFilter(new \Cleentfaar\WindmillBundle\Twig\ChessNotationFilter());
  

• Command-Line Tools Use the bundle’s console commands for bulk operations:

  php bin/console windmill:games:sync  # Sync local games with Windmill
  php bin/console windmill:players:export  # Export player data
  

Gotchas and Tips

Common Pitfalls

1. API Key Management

   • Gotcha: Hardcoding API keys in config/packages/cleentfaar_windmill.yaml is insecure. Use Symfony’s parameter_bag or environment variables:

     windmill:
         api_key: '%env(WINDMILL_API_KEY)%'
     

   • Tip: Rotate keys periodically and use the windmill:key:rotate command.

2. Rate Limits

   • Gotcha: Uncached requests to listGames() may trigger rate limits if called frequently.
   • Tip: Implement a decorator pattern around WindmillService to add caching:

     $windmill->setCache($cache);
     

3. Data Serialization

   • Gotcha: Windmill’s API returns nested arrays/objects. Use json_decode($response, true) carefully to avoid type mismatches.
   • Tip: Normalize responses with a DTO (Data Transfer Object) layer:

     $gameDto = new GameDto($windmill->getGame($id));
     

4. Event Dispatching

   • Gotcha: Events like windmill.game.updated may fire unexpectedly if the API returns partial updates.
   • Tip: Add a isValidUpdate() check in your event listener:

     public function onGameUpdated(GameEvent $event) {
         if ($event->getGame()->isValid()) {
             // Process update
         }
     }
     

Extension Points

1. Custom Move Validators Extend the MoveValidatorInterface to enforce business rules:

   class CustomMoveValidator implements MoveValidatorInterface
   {
       public function isValidMove(Game $game, string $move): bool
       {
           // Custom logic (e.g., check for checkmate)
       }
   }
   

   Register in services.yaml:

   services:
       App\Validator\CustomMoveValidator:
           tags:
               - { name: cleentfaar_windmill.move_validator }
   

2. Webhook Handlers Implement WebhookHandlerInterface for real-time updates:

   class SlackWebhookHandler implements WebhookHandlerInterface
   {
       public function handle(GameEvent $event): void
       {
           $this->slack->send("Game updated: {$event->getGame()->getId()}");
       }
   }
   

   Bind in config/packages/cleentfaar_windmill.yaml:

   webhooks:
       handlers:
           - App\Handler\SlackWebhookHandler
   

3. Testing

   • Tip: Use the WindmillService’s setClient() method to mock API calls in tests:

     $windmill->setClient($mockClient);
     $this->assertEquals('expected_move', $windmill->makeMove('game123', 'e4')->getMove());