> ## Documentation Index
> Fetch the complete documentation index at: https://suvera.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Winter Boot: PHP Microservices Framework Documentation

> Official docs for Winter Boot, a PHP 8 microservices framework inspired by Spring Boot, with attribute-driven DI, REST routing, AOP, async, and scheduling.

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.

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Install Winter Boot, create your first service and REST controller, and have a running Swoole HTTP server in minutes.
  </Card>

  <Card title="Core Concepts" icon="layer-group" href="/core/dependency-injection">
    Understand the application context, bean lifecycle, dependency injection, and AOP weaving that power every Winter Boot service.
  </Card>

  <Card title="Web & REST" icon="globe" href="/web/rest-controllers">
    Map HTTP routes with `#[RestController]`, handle path variables and request bodies, and return typed `ResponseEntity` objects.
  </Card>

  <Card title="Data Access" icon="database" href="/data/database">
    Connect datasources, run schema migrations, and manage transactions declaratively with `#[Transactional]`.
  </Card>

  <Card title="Async & Scheduling" icon="clock" href="/async/async-tasks">
    Offload work with `#[Async]` coroutines and schedule recurring jobs with cron-style `#[Scheduled]` tasks.
  </Card>

  <Card title="Operations" icon="gear" href="/ops/caching">
    Add caching, distributed locking, structured logging, Prometheus metrics, and OpenTelemetry tracing to your services.
  </Card>
</CardGroup>

## Get Up and Running in Four Steps

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

<Steps>
  <Step title="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.

    ```bash theme={null}
    mkdir my-service && cd my-service
    composer init --no-interaction
    composer require suvera/winter-boot
    pecl install swoole
    ```
  </Step>

  <Step title="Configure application.yml">
    Create a `config/` directory and add `application.yml`. At minimum, set the server port and give your service a name.

    ```yaml config/application.yml theme={null}
    server:
        port: 8080
        address: 127.0.0.1

    winter:
        application:
            name: My Service
            id: my-service
            version: 1.0.0-DEV
    ```
  </Step>

  <Step title="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]`.

    ```php src/HelloService.php theme={null}
    <?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.";
        }
    }
    ```

    ```php src/HelloController.php theme={null}
    <?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),
            ]);
        }
    }
    ```
  </Step>

  <Step title="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.

    ```php Application.php theme={null}
    <?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();
    ```

    ```bash theme={null}
    php Application.php
    # Http server started on 127.0.0.1:8080, pid:12345, master_pid:12344
    ```

    Test your endpoint:

    ```bash theme={null}
    curl "http://127.0.0.1:8080/api/hello?name=Alice"
    # {"message":"Hello, Alice! Welcome to Winter Boot."}
    ```
  </Step>
</Steps>