The Module System: Extending Winter with Libraries

Modules package infrastructure integrations — Redis, Kafka, Doctrine ORM, service discovery, and more — as reusable units. Each module can register its own beans, add namespaces to the scan, and run its own setup without any changes to your application code. The contract is small: implement the two WinterModule hooks and annotate the class with #[Module].

The WinterModule Interface

Every module must implement the WinterModule interface. The framework calls its two lifecycle methods during startup in a predictable order.

use dev\winterframework\core\app\WinterModule;
use dev\winterframework\core\context\ApplicationContext;
use dev\winterframework\core\context\ApplicationContextData;

class MyCustomModule implements WinterModule {

    /**
     * Called during the module loading phase.
     * Register beans, validate configuration, check required extensions here.
     */
    public function init(ApplicationContext $ctx, ApplicationContextData $ctxData): void {
        // set up resources
    }

    /**
     * Called after all modules are loaded and the application context is ready.
     * Start background processes, connect to external services, etc.
     */
    public function begin(ApplicationContext $ctx, ApplicationContextData $ctxData): void {
        // begin operations
    }
}

• init() void Called during the module loading phase. Use this hook to register beans, validate configuration, and verify required PHP extensions are present.

• begin() void Called after all modules are loaded and the application context is fully ready. Use this hook to open connections, start background processes, or subscribe to events.

The #[Module] Attribute

Annotate every module class with #[Module]. This tells the framework how to scan the module’s namespaces and provides metadata used in log output.

use dev\winterframework\stereotype\Module;

#[Module(
    title: 'My Custom Module',      // human-readable name shown in logs
    initMethod: 'init',             // method called on load (default: 'init')
    destroyMethod: '',              // method called on shutdown (optional)
    namespaces: [],                 // extra PSR-4 namespaces to scan
)]
class MyCustomModule implements WinterModule {
    // ...
}

Note

When namespaces is left empty, the framework automatically registers the namespace derived from the module file’s location. Only provide explicit [namespace, directory] pairs when your module ships classes in directories outside its own file path.

Enabling Modules in application.yml

Declare modules in your application.yml under the top-level modules key. Each entry requires a module class name and an enabled flag. Most modules also need a configFile: a relative name is looked up in your config directories (so kafka-config.yml, not config/kafka-config.yml), and an absolute path is used as is. The file is read by the module itself; its keys are not added to application.yml properties.

application.yml

modules:
  - module: 'dev\winterframework\telemetry\OpenTelemetryModule'
    enabled: true
    configFile: telemetry.yml   # module config file, looked up in the config directory

  - module: 'dev\winterframework\data\redis\RedisModule'
    enabled: true

  - module: 'dev\winterframework\kafka\KafkaModule'
    enabled: false   # set to false to temporarily disable

Caution

Modules are loaded in the order they appear in application.yml. If one module depends on beans registered by another, place the dependency first in the list.

First-Party Modules

All official modules live in the suvera/winter-modules monorepo. Install the entire collection as described in the Installation guide.

See the Modules overview for a full catalog with guidance on which module to pick for which use case.

DoctrineDoctrine ORM and DBAL for entity management and multi-tenant datasources.

RedisPhpRedis client templates for singles, clusters, arrays, sentinels, and token rings.

MemcacheMemcached and Memcache client templates for lightweight caching.

KafkaApache Kafka producer and consumer integration for event streaming pipelines.

SQSAmazon SQS producer and consumer with IAM role and IRSA support.

S3Amazon S3 and S3-compatible object storage from any bean.

OpenSearchOpenSearch indexing, querying, and AWS SigV4-signed access.

DTCEDistributed Task Computing Engine for cross-node background task orchestration.

EurekaService discovery via Consul and Netflix Eureka.

MemdbEmbedded in-memory servers (Redis, Ignite, Memcached, Hazelcast) managed by the app lifecycle (experimental).

Security (planned)Reserved for a future application security module; no code ships yet.

Building a Custom Module

Package any infrastructure concern — a third-party SDK, a custom cache layer, an internal service client — as a reusable, injectable module by following these steps.

1. Create the module class

   src/Module/AcmeMyModule.php

   <?php
   declare(strict_types=1);
   
   namespace Acme\MyModule;
   
   use dev\winterframework\core\app\WinterModule;
   use dev\winterframework\core\context\ApplicationContext;
   use dev\winterframework\core\context\ApplicationContextData;
   use dev\winterframework\stereotype\Module;
   
   #[Module(title: 'Acme My Module')]
   class AcmeMyModule implements WinterModule {
   
       public function init(ApplicationContext $ctx, ApplicationContextData $ctxData): void {
           // Validate required config, register beans
       }
   
       public function begin(ApplicationContext $ctx, ApplicationContextData $ctxData): void {
           // Start connections or background processes
       }
   }

2. Register beans inside init()

   Use ApplicationContextData::getBeanProvider() to register beans that consumers can inject with #[Autowired]:

   public function init(ApplicationContext $ctx, ApplicationContextData $ctxData): void {
       $client = new AcmeClient(/* config */);
   
       $ctxData->getBeanProvider()->registerInternalBean(
           $client,
           AcmeClient::class,
           true          // replace any bean already registered for this class
       );
   }

3. Read module configuration

   The framework passes the module’s application.yml entry (including any configFile) to your #[Module] attribute. Use the ModuleTrait helper to load it:

   use dev\winterframework\util\ModuleTrait;
   
   #[Module(title: 'Acme My Module')]
   class AcmeMyModule implements WinterModule {
       use ModuleTrait;
   
       public function begin(ApplicationContext $ctx, ApplicationContextData $ctxData): void {
           $moduleDef = $ctx->getModule(static::class);
           $config    = $this->retrieveConfiguration($ctx, $ctxData, $moduleDef);
   
           $host = $config['acme']['host'] ?? 'localhost';
       }
   }

4. Enable the module in application.yml

   application.yml

   modules:
     - module: 'Acme\MyModule\AcmeMyModule'
       enabled: true
       configFile: acme.yml

5. Publish it as a Composer package

   Publish the module as its own package so applications can add it with a single command:

   composer require acme/my-winter-module

Tip

See the suvera/winter-modules repository for real-world examples of how first-party modules are structured and tested — it is the best reference when building your own.