CLI · Winter Console

The di command

At startup the framework walks the project and finds its classes — that is the most expensive part of booting. di manages the cache of that walk: it builds it ahead of time, shows its contents and deletes it. It also builds the proxies for #[Async] and the cache attributes.

Actions build · clean · show · proxiesCache in .winter/buildDEBUG=true cache disabled

Why

Walking the project reads every .php and includes those that declare a class. On an average project that is tens of milliseconds and extra megabytes in the application process’s memory — the process every worker is then forked from.

di build does that work once, ahead of time, and puts the result in a file. At startup the application reads the prepared list instead of walking the disk.

Actions

Action What it does
build Walks the project once: writes the cache, generates the proxies, checks correctness and cache names
clean Deletes the cache and every generated proxy
show [pattern] Prints the classes from the cache; the pattern filters by FQCN substring
proxies [pattern] Prints the #[Async] and cached methods and whether a proxy was built for each; async is the old name of the same action
bash
php call di build
php call di clean
php call di show
php call di show Repository     # only those containing "Repository"
php call di proxies

build before starting

The main scenario is warming it up in a container, before the application starts. That is exactly how the flytachi/winter image, which cfg docker builds on, starts the application:

sh
if ! php /app/call di build; then
  echo "winter-entrypoint: 'call di build' failed — refusing to start" >&2
  exit 1
fi
exec php /app/call application start

`build` is also a check

The command does not merely store a list: it parses every #[Async] method and every method with a cache attribute and generates proxies for them. A method that cannot be proxied that way fails the build — here, with a comprehensible message and exit code 1, rather than in production on the first call. With #[EnableCaching] it also checks that every cache name in the attributes is declared in a CacheConfigurer.

That is why it goes into the entrypoint before startup: a broken application gives one intelligible line in docker logs instead of a container crash-looping.

The build also stops when .winter/ cannot be written — say, the project folder belongs to another user (root) and is mounted into the image, which runs as winter (uid 1000). The message names the folder and the user:

text
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.

Give the user the project folder (chown -R), or create .winter/ owned by it. Starting the application stops with the same message in that case.

build additionally warns when a class with such methods is created with new — the proxy will not apply then. The check is textual and does not see new $class or factories, so it is a warning specifically: it does not fail the build.

Where the cache lives

In the project’s service folder, .winter/build:

text
.winter/build/di.php       the class list
.winter/build/proxy.php    the list of proxied classes
.winter/build/proxy/       the #[Async] and #[Cacheable] proxies

The build itself prints the exact path:

text
 | [=================================== Di ===================================]
|	 di cache .................................................... [BUILT (21 classes)]
| [i] /app/.winter/build/di.php
|	 proxies ..................................................... [DISABLED (no #[EnableAsync] or #[EnableCaching])]
| [=================================== Di ===================================]

The folder can be deleted at any time — call di clean does exactly that — and the next start with DEBUG=false, or call di build, builds it again. It stays out of git and the image: one line, /.winter, in .gitignore and .dockerignore.

With `DEBUG=true` the cache is not used at all

In development mode the application walks the project on every start, so that a new class is picked up without a manual rebuild. A di build you made is simply ignored in that mode.

If changes are “not visible” after a di build, check DEBUG first.

show without a cache

If there is no cache, show does not fail: it performs a live walk, prints the result and warns that what it showed was not written to disk. That keeps the command useful in development too.

proxies

bash
php call di proxies

It shows every method with #[Async] or a cache attribute, which feature each belongs to and whether its proxy was built. This is how to answer the question “why does this method run synchronously” or “why is the cache not working”: if no proxy was built, the call goes through directly.

text
 | [ Proxied methods (1 classes) ]
|	 Main\Service\ProductService ................................. [BUILT]
|	     find() → ?Main\Entity\Product  [cache]
|	     reindex() → void  [async]

Next