Getting started

Configuration

There is no config/ directory in Winter. Values live in .env, the application’s make-up is declared with attributes on the entry class, and everything else is described by ordinary classes the scanner finds. Nothing has to be registered.

Values .envMake-up #[Enable*] attributesBehaviour configurer classes

Three levels

Configuration is split across three places, and the division is simple.

Where What lives there Example
.env Values that change between environments database host, log level
The application class What the application consists of #[EnableHttp], #[EnableScheduler]
Configurer classes Behaviour expressed as code CORS, server settings, beans

Why there are no config files. Anything that is a value belongs to the environment and changes without a rebuild. Anything that is a decision — which implementation to use, how to assemble an object, which origins to allow — is expressed as code, where types and editor hints work. The intermediate layer of arrays in PHP files is deliberately absent.

.env — the values

The file is created from a template by php call cfg init and holds three lines:

.env
WINTER_KEY=<generated key>
TIME_ZONE=UTC
DEBUG=true
Variable Default What it sets
WINTER_KEY — The project secret: signatures, tokens. Generated locally
TIME_ZONE UTC Default timezone
DEBUG false Development mode

The process environment wins over the file. A variable set at launch overrides the same line in .env, and .env fills in whatever the environment does not set:

bash
LOG_LEVEL=debug php call run   # debug, even with LOG_LEVEL=info in .env

A container (environment: in compose), CI and a local run all behave this way — whatever PHP’s variables_order says. .env stays the development defaults, and a deployment sets its own through the environment.

What `DEBUG` actually changes

It is not just “show errors”. The variable switches five things:

  • error display — at false PHP hides them; a failed start still writes one line to stderr, without the stack trace;
  • the error response body — stack traces and debug data reach the client only at true;
  • the class-list cache — at false the project is scanned once and the result is written to di.php; at true the cache is not used at all;
  • #[Async] and cache proxies — at true they are regenerated when the source changes;
  • the access line for every request — at true it is written unless LOG_ACCESS is set explicitly.

In production: false, always. At true the application’s internals leak outwards.

Logging

Variable Default What it sets
LOG_LEVEL unset — output disabled Minimum level to record
LOG_OUTPUT auto auto, stdout, stderr, file, syslog, null
LOG_FORMAT line line or json
LOG_DIR logs The directory with LOG_OUTPUT=file: sys.log and http.log in it; a relative path counts from the project root
LOG_FILE_MAX 30 How many days of rotated files to keep
LOG_COLOR auto auto, always, never
LOG_ACCESS as DEBUG One line per HTTP request: "POST /path?query" HTTP/1.1 agent

The level, output, format, colour and LOG_FILE_MAX can be set for one channel with the LOG_{CHANNEL}_ prefix. LOG_DIR is shared: a channel’s file is always <LOG_DIR>/<channel>.log.

.env
LOG_LEVEL=info
LOG_HTTP_LEVEL=warning     # from requests — problems only
LOG_SYS_OUTPUT=file        # system events into a file

More on the Logging page.

Web server

These apply only when the application declares #[EnableHttp].

Variable What it sets
SERVER_PROFILE Memory profile: stable, balance, performance, stress
SERVER_WORKERS Number of worker processes
SERVER_TASKS Number of Swoole task processes
SERVER_MAX_CONCURRENCY Concurrent requests per worker
SERVER_MAX_CONNECTIONS Concurrent connections
SERVER_MAX_REQUEST Requests before a worker is replaced
SERVER_MAX_REQUEST_GRACE Jitter so workers do not all recycle at once
SERVER_MAX_REQUEST_SIZE Largest request in bytes
SERVER_REQUEST_TIMEOUT Request deadline in seconds
SERVER_IDLE_TIMEOUT When to close a silent connection
SERVER_MEMORY_LIMIT Memory ceiling for each worker
SERVER_MEMORY_TRIM When to return unused memory to the system
SERVER_HEADER The Server response header; Winter by default, empty — no header
SERVER_COMPRESSION Whether responses are compressed; true by default
SERVER_COMPRESSION_LEVEL Compression level, 1–9; 1 by default
SERVER_COMPRESSION_MIN Responses smaller than this are not compressed; 1K by default
SERVER_TLS_CERT, SERVER_TLS_KEY HTTPS in the application itself: the certificate and key; unset by default
SERVER_HTTP2 HTTP/2; false by default

What each one means and how they relate is on the Web-layer configuration page. Address and port are not set by variables — they are declared in #[EnableHttp(port:, host:)] and overridden at launch by the --http.port and --http.host flags.

Everything else

Variable What it sets
WINTER_BANNER off removes the startup banner
CACHE_ENABLED false switches method caching off without a code change; read at startup
PPA_POOL_TELEMETRY How often pool statistics are published; 0 disables it

Database variables are declared by you

The core does not read DB_HOST or anything like it — connecting is your configuration class’s job, and which variables it asks for is your decision. The convention is to read them through env(); see Database.

The application manifest

What the application consists of is declared with attributes on the entry class:

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

Every available attribute and how they combine is on the Components page.

Two hooks — configure() and components()

The application class has two methods to override. components() declares components in code — when attributes are not enough: conditions, values from the environment, outside programs. It runs after the scan; see Components.

configure() is needed only when the project layout is unusual: this method runs before the scan and decides where the scanner should look.

bootstrap.php
use Flytachi\Winter\Kernel\App\ApplicationArguments;
use Flytachi\Winter\Kernel\Kernel;

protected static function configure(ApplicationArguments $args): void
{
  Kernel::init(
      pathRoot:     __DIR__,
      pathResource: __DIR__ . '/assets',
  );
}

Without an override the paths are derived from where the application class sits, and for a normal layout there is no reason to touch it.

Configurer classes

Everything else is described by ordinary classes. They need no registration — the scanner finds them by the interface they implement or the attribute they carry.

What to configure With what
Container bindings, factories, values from .env #[Configuration] with #[Bean] methods
CORS and web-server settings A class extending WebConfigurerAdapter
Extra log channels A class implementing LoggingConfigurer
Caches for #[Cacheable] A class implementing CacheConfigurer; read only with #[EnableCaching]
Plugins The #[Import] attribute on the application class
Diagnostic endpoints The #[EnableActuator] attribute
main/AppConfig.php
#[Configuration]
final class AppConfig
{
  #[Bean]
  public function cache(#[Value('REDIS_URL')] string $url): CacheInterface
  {
      return new RedisCache($url);
  }
}

Each has its own page: Dependency injection, Web-layer configuration, Logging, Packages.

Boot order

The same for every entry point — the server and a console command alike:

text
1. configure()      — paths, .env, timezone, logging
2. Container        — created empty
3. One project walk (the #[Import] package roots first):
    · classes carrying a scope         → container
    · #[Configuration] / #[Bean]       → factories
    · WebConfigurer, LoggingConfigurer → collected
    · CacheConfigurer                  → only with #[EnableCaching]
    · the scope graph                  → checked
4. #[Singleton] ↔ #[Request] conflict check
5. Apply what was found: logging, CORS, plugins, actuator
6. Then either the server or the console command

The project walk is one, not one per kind of configuration. Two consequences follow:

  • the order in which configurer classes are declared does not matter — they are collected in a single pass and applied afterwards;
  • a new configurer is picked up by a restart, like everything else.

Scope conflicts are caught here

Step 4 walks the dependency graph and refuses to start the application when a #[Singleton] holds a #[Request] object: the first request’s data would otherwise be frozen inside it for the worker’s whole life. The log shows the chain A → $prop: B.

Managing the key

bash
php call cfg key -g     # generate a new one
php call cfg key -s     # show the current one
php call cfg env -s     # show every environment variable

Next