Winter Boot: PHP Microservices Framework Documentation

Welcome to the Winter Boot documentation. Winter Boot is a modern PHP 8 microservices framework inspired by Spring Boot, bringing attribute-driven dependency injection, AOP, REST routing, async task execution, caching, transactions, and scheduling to the PHP ecosystem. Whether you are migrating from a Spring Boot project or starting fresh, this documentation covers everything you need to build, configure, and deploy production-ready PHP microservices.

Quick StartInstall Winter Boot, create your first service and REST controller, and have a running Swoole HTTP server in minutes.

Core ConceptsUnderstand the application context, bean lifecycle, dependency injection, and AOP weaving that power every Winter Boot service.

Web & RESTMap HTTP routes with #[RestController], handle path variables and request bodies, and return typed ResponseEntity objects.

Data AccessConnect datasources, run schema migrations, and manage transactions declaratively with #[Transactional].

Async & SchedulingOffload work with #[Async] coroutines and schedule recurring jobs with cron-style #[Scheduled] tasks.

OperationsAdd caching, distributed locking, structured logging, Prometheus metrics, and OpenTelemetry tracing to your services.

Get Up and Running in Four Steps

Follow these steps to go from a blank directory to a live HTTP service.

1. Install Winter Boot via Composer

   Create a new project directory, initialise Composer, and require the core framework package. Install the Swoole extension for the built-in async HTTP server.

   mkdir my-service && cd my-service
   composer init --no-interaction
   composer require suvera/winter-boot
   pecl install swoole

2. Configure application.yml

   Create a config/ directory and add application.yml. At minimum, set the server port and give your service a name.

   config/application.yml

   server:
       port: 8080
       address: 127.0.0.1
   
   winter:
       application:
           name: My Service
           id: my-service
           version: 1.0.0-DEV

3. Write Your First Service and Controller

   Annotate a plain PHP class with #[Service] to register it as a managed bean, then expose it over HTTP with a #[RestController].

   src/HelloService.php

   <?php
   
   declare(strict_types=1);
   
   namespace com\example\myapp;
   
   use dev\winterframework\stereotype\Service;
   
   #[Service]
   class HelloService
   {
       public function sayHello(string $name): string
       {
           return "Hello, {$name}! Welcome to Winter Boot.";
       }
   }

   src/HelloController.php

   <?php
   
   declare(strict_types=1);
   
   namespace com\example\myapp;
   
   use dev\winterframework\stereotype\Autowired;
   use dev\winterframework\stereotype\RestController;
   use dev\winterframework\stereotype\web\GetMapping;
   use dev\winterframework\stereotype\web\RequestParam;
   use dev\winterframework\web\http\ResponseEntity;
   
   #[RestController]
   class HelloController
   {
       #[Autowired]
       private HelloService $helloService;
   
       #[GetMapping(path: '/api/hello')]
       public function hello(#[RequestParam] string $name = 'World'): ResponseEntity
       {
           return ResponseEntity::ok()->withJson([
               'message' => $this->helloService->sayHello($name),
           ]);
       }
   }

4. Run the Application

   Create the entry-point class with #[WinterBootApplication], then start the server. Swoole forks worker processes and begins accepting connections on your configured port.

   Application.php

   <?php
   
   declare(strict_types=1);
   
   use dev\winterframework\stereotype\WinterBootApplication;
   use dev\winterframework\core\app\WinterWebSwooleApplication;
   
   require_once __DIR__ . '/vendor/autoload.php';
   
   #[WinterBootApplication(
       configDirectory: [__DIR__ . '/config'],
       scanNamespaces: [['com\\example\\myapp', __DIR__ . '/src']]
   )]
   class Application
   {
       public static function main(): void
       {
           (new WinterWebSwooleApplication())->run(Application::class);
       }
   }
   
   Application::main();

   php Application.php
   # Http server started on 127.0.0.1:8080, pid:12345, master_pid:12344

   Test your endpoint:

   curl "http://127.0.0.1:8080/api/hello?name=Alice"
   # {"message":"Hello, Alice! Welcome to Winter Boot."}