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.
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 |
php call di build
php call di clean
php call di show
php call di show Repository # only those containing "Repository"
php call di proxiesbuild 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:
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:
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:
.winter/build/di.php the class list
.winter/build/proxy.php the list of proxied classes
.winter/build/proxy/ the #[Async] and #[Cacheable] proxiesThe build itself prints the exact path:
| [=================================== 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
php call di proxiesIt 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.
| [ Proxied methods (1 classes) ]
| Main\Service\ProductService ................................. [BUILT]
| find() → ?Main\Entity\Product [cache]
| reindex() → void [async]Next
- Dependency injection — what lands in the container
- Asynchronous calls —
#[Async]and its proxy - Method caching — the cache attributes and the name check
- cfg docker — where
di buildsits in a container’s startup - Console — overview — every command