Getting started

Project structure

A Winter project is flat: a handful of files at the root and one directory for your code. There is no config/, no routes/, no mandatory app/. The layout inside your own directory is yours to choose — the framework finds classes by walking the directories composer.json autoloads, not by reading a list in a config.

Your code main/Service data .winter/Scanned autoload · bootstrap.phpNot scanned vendor · .winter · resources

After the install

text
my-app/
├── bootstrap.php      the application class: what it is made of
├── call               the entry point for every command
├── composer.json      autoloading and dependencies
├── composer.lock      pinned versions
├── .env               environment variables
├── .gitignore
│
├── main/              your code, namespace Main\
│   └── MainController.php
│
└── vendor/

That is everything composer create-project leaves behind. The rest appears when it is needed:

What When it appears
.winter/ at the first start — the framework’s service data, see below
logs/ when logs go to a file (LOG_OUTPUT=file), see Logging
resources/ you create it — for views, translations, static files
Dockerfile, docker-compose.yml, .dockerignore php call cfg docker
directories inside main/ you create them, or the make generator does

The project root

bootstrap.php

The application class. It declares what the application consists of and serves as the entry point.

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

The #[Enable*] attributes are the single place where the application’s composition is listed. See Application composition.

This file also fixes the project root: the framework takes the directory the application class lives in and derives every other path from it — .env, .winter/, logs/, resources/, the location of composer.json. That is why bootstrap.php sits at the root rather than in a subdirectory.

call

It runs everything: the server, the console commands, the generators. Inside are a PHP version guard, a chdir(__DIR__), the bootstrap.php include, and the handover to the application class.

bash
php call run dev          # development server
php call mapping show     # the route list
php call make -c .User    # create a controller

The chdir inside means commands work from any directory: php /path/to/my-app/call run starts the server with the right paths.

composer.json

Besides the dependencies it sets up PSR-4 — which namespace maps to which directory:

composer.json
{
  "autoload": {
      "psr-4": {
          "Main\\": "main/"
      }
  }
}

A single Main\ prefix is not the limit. Add your own and they start working after composer dump-autoload:

composer.json
"psr-4": {
  "Main\\":  "main/",
  "Api\\":   "api/",
  "Admin\\": "admin/"
}

Separate roots are convenient when parts of the application live their own lives: a public API and an admin panel have different routes, different middleware, and often different people. Every root is scanned the same way: the walk takes exactly the paths listed in autoload — psr-4, psr-0 and classmap. A new root joins the scan after composer dump-autoload.

.env

The environment-dependent values. It is not committed — it and vendor/ are what the .gitignore covers.

bash
php call cfg env -s     # what actually loaded
php call cfg env -i     # create .env from the template
php call cfg key -g     # reissue the WINTER_KEY

The full list of variables is on the Configuration page.

main/ — your code

The only directory you fill. Its inner structure is yours: the framework requires neither Controllers/ nor Models/ nor any other name.

text
main/
├── MainController.php
├── User/
│   ├── UserController.php
│   ├── UserService.php
│   └── UserRepository.php
└── Order/
  ├── OrderController.php
  └── OrderProcess.php

Here the classes are grouped by domain rather than by type — but a by-type layout (Controllers/, Services/, Repositories/) works exactly the same. It makes no difference to the framework: it looks for classes, not for directories.

Where make puts files

The generator goes by namespace. There are only two rules.

Give it a dotted path and the path decides. It is resolved against the PSR-4 roots, with vendor/ excluded:

bash
php call make -c api.user.Profile   # main/Api/User/ProfileController.php
php call make -c admin.Report       # admin/ReportController.php  (given an Admin\ root)

Give it no path (.Name) and it looks for a directory you already use. The first existing one from the list wins:

Type Flag Looks for (first existing)
Controller -c Rests, Rest, Controllers, Controller
Middleware -m Middlewares, Middleware, Controllers/Middlewares, Controllers/Middleware, Controller/Middlewares, Controller/Middleware
Service -s Services, Service
Repository -r Repositories, Repository
Redis store -t Stores, Store
Entity -e Entity, Entities
DTO -d Dto, DTOs, Entity/Dto, Entity/DTOs, Entities/Dto, Entities/DTOs
Process -P Processes, Process
Daemon -N Daemons, Daemon
WebSocket -W Sockets, Processes, Process
Database config -D Configs/Databases, Config/Database, Configs, Config
Redis config -R Configs/Redis, Configs, Config
Console command -n Cmd

If none of them exists the file lands in the PSR-4 root itself, that is, straight in main/. There is nothing to create in advance: make the one directory you like once, and the generator will keep finding it.

bash
php call make -c .User        # main/UserController.php
mkdir main/Controllers
php call make -c .Order       # main/Controllers/OrderController.php

The --mvc option does not look, it creates: it prepends the by-type directory (Controllers/, Services/, Repositories/…) whether or not it is already there. The details and every flag are in call make.

What gets scanned at boot

The framework does not read a list of classes from a config — it walks files. The order is:

  1. every package imported through #[Import], in declaration order;
  2. then the project’s code — the directories in the autoload section of its composer.json, and the file declaring the application class (bootstrap.php).

The application goes last on purpose: where a package’s contribution and the application’s conflict, the application must be the one that wins.

The project’s code is what autoload declares: every psr-4 and psr-0 path and every classmap entry. The autoload-dev and files sections are not scanned. In the skeleton that is main/ ("Main\\": "main/"). The file declaring the application class is added to them separately, so classes declared in bootstrap.php are still found. Spring’s base package and Symfony’s resource directories work the same way: the framework scans the application’s code, not everything that sits next to it.

The other folders at the root — tests/, scripts/, data volumes — are not scanned unless autoload declares them. A test class without its dev dependencies (composer install --no-dev) does not stop the boot, and a script’s top-level code does not run at startup.

In each directory only .php files are read. Every class declared in a file is collected, and the file is then required. That is how controllers, configurations, processes and commands are found — none of them has to be registered anywhere.

No autoload, no boot

If there is no composer.json, or its autoload declares no directory, the boot stops with ScanException. The message names the fix: add "autoload": {"psr-4": {"Main\\": "main/"}} and run composer dump-autoload. The skeleton already has this entry.

A directory inside the code that cannot be opened (no permission, a mounted volume that refuses it) is skipped instead of stopping the boot. Its classes are not registered, and a warning says so once per booting process (WARN, channel sys):

text
Class scan skipped <dir>: it cannot be opened (permissions?). Its classes are not registered.

The warning appears only on a cold scan: when the class list comes from the di.php cache, nothing is walked.

Three directories are left out of the walk — this matters when the project autoloads from its root ("App\\": "") and they end up inside a scanned path:

Directory Why
vendor/ Dependencies take no part in finding application classes; excluded by the scanner itself
.winter/ It holds generated code — the walk would be reading the previous walk’s output
resources/ It holds views: PHP files by nature, not classes

The exclusions are bound to the configured paths, not to the names: move the resources to assets/ through pathResource and the exclusion moves with them. The scanner does not enter an excluded directory, and matching is by folder boundary: excluding vendor leaves vendor-tools/ alone.

Views are excluded for correctness, not for speed

The scanner looks for a class declaration in every .php and requires the file it found one in. For a template that means execution: it echoes its markup into the application’s output and runs whatever else sits at its top level. Verified on a live project, not assumed.

So keep templates under resources/. A template directory placed inside main/ falls into the walk.

Hence the practical rule: only application classes belong inside the autoload directories. Templates go in resources/; scripts, dumps and migration one-liners go in folders outside autoload — the scanner does not look there.

Upgrading from before 4.4.1

The walk used to start at the project root and cover all of it, so a class was found wherever it lived. Now a class outside the autoload directories and outside bootstrap.php is not discovered. Move it into an autoloaded folder, or add its folder to autoload, then run composer dump-autoload.

.winter/ — the framework’s service data

Everything the framework writes for itself sits in one hidden folder in the project root. Nothing in it is edited by hand or committed: one line, /.winter, in .gitignore and .dockerignore.

text
.winter/
├── build/              what the framework builds to start faster
│   ├── di.php          the project's class list
│   ├── proxy.php       the list of proxied classes
│   └── proxy/          generated #[Async] and #[Cacheable] proxies
├── cache/              #[Cacheable] values in the file store
│   └── <cache name>/
└── runnable/           the state of running processes
  ├── Main.Process.Heartbeat/     record: PID, state, who manages it
  ├── Main.Process.Heartbeat.lock lock: held while the process lives
  ├── app/                        the application's record and its components
  ├── app.Application.lock        "one application, one run"
  ├── requests/, replies/         console ↔ application: start, restart
  └── ppa.pool/                   connection-pool load
Folder What is in it When it appears Safe to delete
build/ the class list and proxies on a start with DEBUG=false, or call di build yes, any time: call di clean
cache/ #[Cacheable] caches of the file type on the first write to such a cache yes: call cache clear --all
runnable/ the state of processes and the application the first time a process or the application starts only when nothing is running

The folder does not move: neither a parameter nor an environment variable moves it. So every process of the project — the console on the host and the application in a container, when the project is mounted — sees the same files: call process status, call app status and the “already running” check are built on that.

The folder must be writable

The user the application runs as must be able to write to .winter/ — in the flytachi/winter image that is winter, uid 1000. If the project belongs to another user (for example root, with the project mounted into a container), the start and call di build stop at once:

The framework cannot write /app/.winter as this user (winter, uid 1000): it keeps its process records, locks and caches there. Give the user the project folder (chown -R), or create .winter/ owned by it.

The fix is to give that user the folder: chown -R 1000:1000 <project folder>.

With DEBUG=true there is no class cache at all

build/ is written and read only with DEBUG=false. In debugging every start walks the files again — a new class is visible at once, with no di build and no “why is my controller not found”.

The other side of it: in production a class added without a rebuild does not appear. That is why di build is an image build step, not a manual operation.

Do not delete runnable/ while processes run

Running processes lose their records — status and stop stop seeing them — and their lock files, after which a second instance of the same process can be started.

Logs are not written to .winter/: with LOG_OUTPUT=file they go to the LOG_DIR directory, logs/ in the project root by default — worth adding to .gitignore.

resources/ — views, translations, static files

The directory does not exist at first; create it when you need it. The subdirectory names are the framework’s convention and there is no reason to change them.

Path What is in it
resources/views/ Templates and layouts for ResponseView
resources/lang/ Translation dictionaries: ru.php, en.php
resources/static/ Static files, if the application serves them

Serving static files is switched on explicitly, in the web layer settings:

php
public function configureServer(ServerSettings $server, ApplicationArguments $args): void
{
  $server->staticPath('resources/static');
}

Those requests are served by the server directly and never reach PHP: middleware, CORS and request logging do not apply to them.

The container files

The php call cfg docker command adds a ready build to the project:

text
my-app/
├── Dockerfile             on the flytachi/winter image: the project's vendor/ and code
├── docker-compose.yml     the port, the mounted sources, the DEV switch
└── .dockerignore

Swoole, the extensions, the winter user and the application’s start come with the flytachi/winter image — none of it lives in the project.

The mode is picked with a variable: DEV=true docker compose up — development with a restart on file change, docker compose up — production with opcache. How to add an extension of your own — in cfg docker.

Your own paths

The default layout is derived from the root, and the root from where the application class sits. All of it is overridable in configure():

bootstrap.php
protected static function configure(ApplicationArguments $args): void
{
  Kernel::init(
      pathRoot:     __DIR__,
      pathResource: __DIR__ . '/assets',
  );
}
Parameter Default
pathRoot the directory of the file holding the application class
pathResource <root>/resources

.winter/ and .env are not on this list on purpose: the service folder is always <root>/.winter and .env is always <root>/.env, so every process of the project finds the same files. Overriding the paths one at a time rather than all at once is fine: what you leave out is derived from what you set.

Next