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.
After the install
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.
#[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.
php call run dev # development server
php call mapping show # the route list
php call make -c .User # create a controllerThe 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:
{
"autoload": {
"psr-4": {
"Main\\": "main/"
}
}
}A single Main\ prefix is not the limit. Add your own and they start working after
composer dump-autoload:
"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.
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_KEYThe 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.
main/
├── MainController.php
├── User/
│ ├── UserController.php
│ ├── UserService.php
│ └── UserRepository.php
└── Order/
├── OrderController.php
└── OrderProcess.phpHere 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:
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.
php call make -c .User # main/UserController.php
mkdir main/Controllers
php call make -c .Order # main/Controllers/OrderController.phpThe --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:
- every package imported through
#[Import], in declaration order; - then the project’s code — the directories in the
autoloadsection of itscomposer.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):
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.
.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:
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:
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
└── .dockerignoreSwoole, 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():
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
- Configuration —
.envand the configurer classes - Application composition — the
#[Enable*]attributes - Quickstart — the first route
call make— the generators and every flag- Packages —
#[Import]and other people’s code in the walk