application.yml Reference: Configuration Keys

application.yml is the central configuration file for a Winter Boot application. It must live in the config directory referenced by #[WinterBootApplication(configDirectory: [...])]. This page indexes the keys the framework and its official libraries recognize, with short descriptions and links to the page that documents each in full.

For prose walkthroughs of properties, #[Value] injection, and additional property sources see Configuration.

Framework top-level keys

`server`

HTTP server configuration used by WinterWebSwooleApplication.

server:
    port: 8080
    address: 0.0.0.0
    context-path: /
    swoole:                       # passed to Swoole\Server::set()
        worker_num: 2
        hook_flags: SWOOLE_HOOK_ALL

Documented in Configuration.

server.port may come from the environment (port: "$env.PORT || 8080"): the resolved string is converted to an integer. Under server.swoole, values that resolve to integer strings ("4") or "true"/"false" are passed to Swoole as integers and booleans.

Every key under server.swoole is passed to Swoole’s server settings as is, except hook_flags, which also accepts names:

`server.swoole.hook_flags` value	Meaning
absent (default)	Swoole’s default `0`: no runtime hooks. PDO, sockets, `sleep()` and cURL block the whole worker, so each worker serves one request at a time.
`SWOOLE_HOOK_ALL` (or `all`)	Every blocking call yields to other coroutines, so a worker serves requests concurrently. Needed for the coroutine connection pool to matter.
`[SWOOLE_HOOK_PDO_PGSQL, SWOOLE_HOOK_TCP]`	Only the listed hooks (OR’ed).
`[SWOOLE_HOOK_ALL, -SWOOLE_HOOK_CURL]`	All hooks except cURL (a `-NAME` entry removes that flag).
`65536`	A raw number, as before.

An unknown name stops the application at startup.

With SWOOLE_HOOK_ALL, run on the suvera/winter-boot-hookall or suvera/winter-boot-mysql-hookall Docker image (see Docker Deployment). In the plain images, PDO-pgsql queries still block the worker and curl_multi (Guzzle) crashes it.

`winter`

Framework-wide runtime settings.

winter:
    application:
        name: "My Winter App"
        id: MyApp
        version: 1.0.0
    web:
        request:
            enableTrace: true
        json:
            prettyPrint: false
        cors:
            allowedOrigins: []
            allowedMethods: [GET, HEAD, POST, PUT, PATCH, DELETE]
            allowedHeaders: [Content-Type, Authorization, Accept, X-Requested-With]
            exposedHeaders: []
            allowCredentials: false
            maxAge: 1800
    rest:
        timeout: 10.0
        connect-timeout: 5.0
    task:
        async:
            poolSize: 1
            queueCapacity: 50
            argsSize: 2048
            maxConcurrency: 0
            queueStorage:
                handler: dev\winterframework\util\async\AsyncInMemoryQueue
        scheduling:
            poolSize: 1
            queueCapacity: 50
    kv:
        port: 0          # 0 = KV store off
        address: 127.0.0.1
    queue:
        port: 0          # 0 = queue store off
        address: 127.0.0.1
    coroutine:
        db:
            enabled: true
            maxConnections: 10
            maxWaitMs: 5000
    telemetry:
        enabled: true
    security:
        unserialize:
            allowedClasses: [App\Dto\User, App\Dto\Cart]
    mcp:
        path: /mcp
        serverName: "My Winter App"
        serverTitle: ""
        instructions: ""
        allowedOrigins: []
        maxBodyBytes: 1048576

application.name, application.id, application.version: service identity, shown in the startup banner and available from ApplicationContext.
web.request.enableTrace: when true, logs a TRACE START line on request arrival and a TRACE FINISH line (method, URI, response status, time taken) on completion. Default false. Documented in Logging.
web.json.prettyPrint: when false (default since 2.1.2), JSON response bodies are compact; set true to indent them. Documented in REST Controllers.
web.cors.*: Cross-Origin Resource Sharing, off unless allowedOrigins is non-empty. allowedOrigins: exact origins (https://app.example.com) browsers may call from; * allows any origin but is refused together with allowCredentials (CORS then stays off and an error is logged). allowedMethods: methods a cross-origin request may use (checked on preflights and on simple requests), default GET, HEAD, POST, PUT, PATCH, DELETE; * = any method. allowedHeaders: request headers a preflight may ask for, default Content-Type, Authorization, Accept, X-Requested-With (* = any well-formed header). exposedHeaders: response headers scripts may read, default none. allowCredentials: send Access-Control-Allow-Credentials: true, default false. maxAge: seconds a browser may cache a preflight, default 1800, capped at 86400. Lists may also be comma-separated strings. Documented in REST Controllers.
rest.timeout: overall RestTemplate request timeout in seconds. Default 10.0. Documented in RestTemplate.
rest.connect-timeout: RestTemplate connect timeout in seconds. Default 5.0. Documented in RestTemplate.
task.async.*: async worker pool size, queue capacity, argument size limit, per-worker concurrency, and queue storage. Documented in Async Tasks.
task.scheduling.*: scheduler pool size and capacity. Documented in Scheduling.
kv.*, queue.*: node-local KV and queue stores (port, address, token). Documented in Local Stores.
coroutine.db.*: database connection pool defaults (maxConnections per pool per worker, default 10; maxWaitMs, default 5000). Documented in Database.
telemetry.enabled: set false to switch OpenTelemetry off. Documented in Telemetry.
mcp.*: the MCP tools endpoint, active only when the application has a #[McpTool], #[McpResource] or #[McpPrompt]. path: endpoint path relative to server.context-path, default /mcp. serverName: name reported to MCP clients, default application.name. serverTitle: display title reported to MCP clients (serverInfo.title), not sent when empty (2.1.7+). instructions: text sent to clients on initialize, default empty. allowedOrigins: exact Origin values browsers may call from; any other request with an Origin header gets 403, default []. maxBodyBytes: request size limit, default 1048576. Documented in MCP Tools.
security.unserialize.allowedClasses: classes that may be rebuilt when session, shared-cache and shared-queue data is read back. Absent (default) = any class; a list (or comma-separated string) = only those; [] = none (objects become __PHP_Incomplete_Class). Documented in Request Sessions.

`datasource`

List of relational datasources. Each entry produces a named PdbcTemplate bean and a transaction manager bean.

datasource:
    -   name: defaultdb
        isPrimary: true
        url: "sqlite::memory:"
        username: myuser
        password: mypassword
        driverClass: dev\winterframework\pdbc\pdo\PdoDataSource
        validationQuery: SELECT 1
        connection:
            persistent: true
            errorMode: ERRMODE_EXCEPTION
            columnsCase: CASE_NATURAL
            idleTimeout: 300
            autoCommit: true

Documented in Database.

An optional migrations.enabled: true on a datasource entry opts the connection into SQL migrations.

`multitenant-datasource`

List of multi-tenant datasources, each with a name and a providerClass implementing TenantDataSourceProvider. Each entry registers a <name>-manager bean. Documented in Database.

`management`

Actuator endpoints: management.endpoints.enabled (global switch) and management.endpoint.<name>.enabled / .path per endpoint. Documented in Actuator.

`modules`

List of Winter modules (libraries) to load at startup.

modules:
    - module: 'dev\winterframework\kafka\KafkaModule'
      enabled: true
      configFile: kafka-config.yml

Modules are loaded in order. Documented in The Module System.

Logging (separate file)

Logging is not configured in application.yml; it lives in logger.yml in the same config directory. Documented in Logging.

`propertySources`

List of additional property sources (environment variables, INI files, custom sources) that values can reference with $name.key.

Documented in Configuration.

Custom application keys

Any additional top-level key you define can be injected with #[Value('${myApp.value1}')] or read through ApplicationContext::getProperty(). Convention is to nest your application config under a single namespace (for example myApp:).

Library-specific keys

Each Winter library reads its own top-level keys from the module config file referenced by its configFile entry under modules: (see each library’s page for the format).

`opensearch`

Used by OpenSearch and the framework’s OpenSearch migration runner.

opensearch:
    -   name: opensearch
        hosts:
            - https://localhost:9200
        username: admin
        password: secret
        ssl_verification: false
        migrations:
            enabled: true

`kafka`

Used by the Kafka library for consumer and producer definitions.

`sqs`

Used by the SQS library for connection and consumer definitions.

`s3`

Used by the S3 library for connection credentials.

`doctrine`

Used by the Doctrine library for ORM/DBAL datasources and multi-tenant configuration.

`memdb`

Used by the Memdb library for embedded server engine selection.

`dtce`

Used by the DTCE library for queue, store, and worker configuration.

`eureka`, `consul`

Used by the Service Discovery library.

`redis`, `memcache`

Used by the Redis and Memcache client libraries respectively.

`security`

Reserved for the planned Security module. Not yet implemented.

Module-config file convention

For libraries with substantial config, keep it in a dedicated file and reference it from modules::

modules:
    - module: 'dev\winterframework\kafka\KafkaModule'
      enabled: true
      configFile: kafka-config.yml

kafka:
    consumers:
        - name: my-consumer
          # ...

A relative configFile is looked up in your config directories. The module reads the file itself; its keys are not merged into application.yml properties, so #[Value] cannot see them.

application.yml Reference: Configuration Keys

Framework top-level keys

server

winter

datasource

multitenant-datasource

management

modules