Installation

Winter is a library, not a skeleton with a mandatory structure. A project is assembled from a handful of files, and every one of them is explained below: what it does and why it is there. If you would rather not take it apart — the first command on this page gives you a working project.

Requirements

`call run` with a web tier needs ext-swoole (pecl install swoole).

The remaining extensions are installed for specific jobs:

Three ways

The ready-made skeleton

composer create-project flytachi/winter my-app
cd my-app
php call run dev

Composer finishes the setup itself after the install — its output says so:

> @php call storage init
|	 storage ..................................................... [CREATED]
|	 storage/cache ............................................... [CREATED]
|	 storage/logs ................................................ [CREATED]
> chmod -R 777 storage
> @php call cfg init
|	 .env ........................................................ [CREATED]
|	 Old key    (empty)
| [✓] WINTER_KEY generated and saved to .env
|	 New key    bf4ee7d770a565c21598e57e87d46fde6637c0181cac13f4c37fd7b4c194c652

The directories exist and are writable, the .env is in place, and the key is yours rather than shared with someone else’s project. There is nothing left to install or configure.

The skeleton contains exactly what is built by hand below: a bootstrap.php with the application class, a call file, the PSR-4 Main\ → main/ mapping, a ready MainController, and monolog/monolog in require-dev — so logs have somewhere to go from the start.

Through Docker, when there is no PHP

create-project is a PHP program too, but it can run in a throwaway container: the image carries PHP inside, and the project stays with you in the mounted directory.

docker run --rm -v "$PWD":/app -w /app composer:2 \
  create-project flytachi/winter my-app --ignore-platform-reqs

--ignore-platform-reqs is needed because the kernel requires ext-pcntl and ext-posix — they are needed by the running application, not by the installer, and the runtime image has them.

From there the project runs in its own container, where Swoole is already built, and console commands go the same throwaway way. The commands for all of it are in the Quickstart.

Building a project from scratch

1. The directory and the dependency

mkdir my-app && cd my-app
composer require flytachi/winter-kernel

2. The code directory and autoloading

Winter imposes nothing: the directory and the namespace are yours to pick — in the examples below they are main/ and Main\.

mkdir main

Now tie them together in composer.json:

{
  "autoload": {
      "psr-4": {
          "Main\\": "main/"
      }
  },
  "require": {
      "php": ">=8.4",
      "flytachi/winter-kernel": "^4.0"
  }
}

composer dump-autoload

3. The application class — bootstrap.php

This is the only configuration file. It pulls in the autoloader and declares what the application is made of:

<?php

declare(strict_types=1);

use Flytachi\Winter\Kernel\App\Attribute\EnableWeb;
use Flytachi\Winter\Kernel\WinterApplication;

require __DIR__ . '/vendor/autoload.php';

#[EnableWeb]
final class Application extends WinterApplication
{
  public static function main(array $argv): never
  {
      parent::run($argv);
  }
}

There are no hooks here that must be overridden — everything else lives in ordinary classes the scanner finds. What else can be declared alongside #[EnableWeb] is on the Application composition page.

This file’s directory becomes the project root: .env, storage/, resources/ and the start of the file walk are all measured from it.

4. The entry point — call

Every command goes through it, starting the server included:

#!/usr/bin/env php
<?php

if (PHP_VERSION_ID < 80400) {
  echo "Please use PHP version 8.4 or higher. Current: " . PHP_VERSION . "\n";
  exit(1);
}

chdir(__DIR__);
require './bootstrap.php';

Application::main($argv);

chmod +x call

The chdir() is not optional: it anchors the relative paths — .env, storage/, resources/ — to the project directory rather than to wherever you ran the command from.

5. The environment and the directories

php call cfg init       # .env from the template + a fresh WINTER_KEY
php call storage init   # the service directories inside storage/

The resulting .env is minimal:

WINTER_KEY=<the generated key>
TIME_ZONE=UTC
DEBUG=true

The rest of the variables — database, logs, server settings — are added as they are needed; see Configuration.

6. The first controller

php call make -c .Main   # → main/MainController.php

The generator writes a working stub: a hello() method carrying #[RequestMapping] with no arguments. Such an attribute mounts the method under the class name and answers every major HTTP method — you can check without opening the file:

php call mapping show

 | [ Routes (5) ]
|	 GET     /main                                 → Main\MainController::hello
|	 POST    /main                                 → Main\MainController::hello
|	 PUT     /main                                 → Main\MainController::hello
|	 PATCH   /main                                 → Main\MainController::hello
|	 DELETE  /main                                 → Main\MainController::hello
| [ Routes ]

What you end up with

my-app/
├── bootstrap.php     — the application class: what it is made of
├── call              — the entry point for every command
├── composer.json     — autoloading and dependencies
├── .env              — the environment
├── main/             — your code
└── storage/          — the service directories

A resources/ directory for views and translations appears when you need it. What is responsible for what: Project structure.

The first run

php call run dev

The server listens on port 8000 on every interface.

The word dev turns on file watching: change any .php and the application restarts itself. In production it is started without it — php call run.

The address and port are overridden with flags:

php call run dev --port=9000
php call run dev --host=127.0.0.1 --port=9000   # local only

What cfg init does

It is one command but several actions, and they are worth knowing because one of them cannot be undone.

You cloned an existing project

After git clone the skeleton is already there, but everything that stays out of the repository has to be created again:

composer install

php call cfg env -i       # create the .env if it is missing
php call cfg key -g       # generate your own WINTER_KEY
php call storage init     # create the directories inside storage/

php call run dev

The executable bit on call is kept in the repository itself, so chmod +x is normally unnecessary. If the file did arrive without it — through an archive, say — put it back: chmod +x call.

Packages as you need them

The kernel carries neither a database layer nor a Redis client: they are separate packages, installed when they are needed. The kernel picks them up on its own — there is nothing to switch on.

composer require flytachi/winter-ppa      # database: repositories, entities, migrations
composer require flytachi/winter-redis    # Redis: stores, hashes, lists, streams
composer require flytachi/jwt             # JWT and JWKS

Until a package is installed, the commands that need it do not blow up with a stack trace — they say what is missing:

 | [!] The 'db' command needs the database layer, which is not installed.
| [i] Add it with:  composer require flytachi/winter-ppa

Where to go next: PPA, Redis, Ecosystem.

Two more things worth having

Shell completion — hints for the commands and their arguments:

php call cfg completion -i

The Docker configuration — a Dockerfile, a docker-compose.yml and a docker/ directory with a Swoole entry point:

php call cfg docker

The mode is picked by the DEV variable, and it is off by default:

docker compose up            # production mode
DEV=true docker compose up   # development: restart on file change

Next

• Quickstart — the first route in five minutes
• Project structure — what is responsible for what
• Application composition — web, processes, daemons, scheduler
• Configuration — the environment variables