Application Layers
Introduction
In a long-running server (Swoole, the CLI server), the process handles many requests. An object created in one request can survive into the next and leak one user's state into another. Windwalker splits the container into layers, each with its own lifetime. Per-request services live in the request layer, and services that are safe to share live in the application layer.
Why Three Layers
A long-running server such as Swoole should register providers and configuration only once, when the application initializes. For each request, Windwalker creates only the request-level services. When the request ends, the request container and its state are discarded. This keeps memory leaks unlikely, because nothing from one request survives into the next by default.
The layers are built into Windwalker's container rather than added by a plugin. The design stays compact, and the layers work closely together.
The top layer, AppLayer::RUNTIME, ignores the execution environment. It performs only basic process initialization.
In theory, one process could run several HTTP and WebSocket servers at the same time. In practice, this is not recommended, because it makes development and debugging very difficult.
TIP
Run one server per process. This keeps logs, state, and debugging straightforward.
The Layers
Windwalker names three layers with the AppLayer constants:
AppLayer::RUNTIME(1): the process-wide container. It is created once when the process boots.AppLayer::APP(2): the application container, a child of the runtime container. It lives as long as the application does. In a long-running server, that means the whole server lifetime.AppLayer::REQUEST(3): the request container, a child of the application container. Windwalker creates one for each request and discards it when the request ends.
$app->getContainer()->getLevel(); // 2Minimal Setup: A Request-Scoped Service
A service declares its layers with the providedIn option of DIOptions. A shopping cart belongs to one visitor's request, so it is provided only at the request layer:
namespace App\Provider;
use App\Cart\ShoppingCart;
use Windwalker\Core\Application\AppLayer;
use Windwalker\DI\Container;
use Windwalker\DI\DIOptions;
use Windwalker\DI\ServiceProviderInterface;
class CartProvider implements ServiceProviderInterface
{
public function register(Container $container): void
{
$container->prepareSharedObject(
ShoppingCart::class,
null,
new DIOptions(providedIn: AppLayer::REQUEST),
);
}
}Each request gets its own cart. A controller receives it in the constructor:
namespace App\Controller;
use App\Cart\ShoppingCart;
class CartController
{
public function __construct(
protected ShoppingCart $cart,
) {}
public function add(int $productId): void
{
$this->cart->add($productId);
}
}The application layer cannot provide it, so this lookup fails:
// Throws: the service cannot be provided at level 2
$app->retrieve(ShoppingCart::class);The providedIn Values
providedIn accepts a level, a list of levels, or a closure:
- A single level, which the service is provided in only:
new DIOptions(providedIn: AppLayer::REQUEST);- A list of levels:
new DIOptions(providedIn: [AppLayer::APP, AppLayer::REQUEST]);- A closure receives the level and returns
truewhere the service may live:
new DIOptions(
providedIn: fn(int $level) => $level >= AppLayer::REQUEST,
);INFO
The level is checked at lookup time, not at registration. A wrong level does not fail on boot.
Isolation
Sometimes a service must be shared within one request but rebuilt for each request, even though it is declared once. The #[Isolation] attribute marks a class for that behavior:
namespace App\Database;
use Windwalker\DI\Attributes\Isolation;
#[Isolation]
class ConnectionPool
{
// Holds connections for the current request.
}Declare the class with prepareSharedObject() so Windwalker can build new instances from it:
$container->prepareSharedObject(ConnectionPool::class);Each child builds its own instance. A child that is not isolated reuses the parent's:
$child = $app->getContainer()->createChild();
$child->get(ConnectionPool::class);
// A new instance for this child, not the application's instance.new DIOptions(isolation: true) declares the same thing in code. Core uses it for some of its own services.
WARNING
Isolation works only for services that Windwalker can rebuild, such as those registered with prepareObject() or prepareSharedObject(). A service registered with an existing object through share() or set() stays the same instance in every child.
Long-Running Servers
In a long-running server, shared services in the application layer keep their state until the server stops. That suits stateless services, such as a configuration reader. It is wrong for per-request data, such as the current user or a shopping cart.
WARNING
Do not store per-request state in an application-layer service. The next request gets the old state silently. Use providedIn: AppLayer::REQUEST, or #[Isolation] with prepareSharedObject().
Request Hooks
Providers can run code at the start and end of each web request. Implement one or both interfaces:
namespace App\Provider;
use App\Request\RequestState;
use Windwalker\Core\Application\AppLayer;
use Windwalker\Core\DI\RequestBootableProviderInterface;
use Windwalker\Core\DI\RequestReleasableProviderInterface;
use Windwalker\DI\Container;
use Windwalker\DI\DIOptions;
use Windwalker\DI\ServiceProviderInterface;
class RequestStateProvider implements
ServiceProviderInterface,
RequestBootableProviderInterface,
RequestReleasableProviderInterface
{
public function register(Container $container): void
{
$container->prepareSharedObject(
RequestState::class,
null,
new DIOptions(providedIn: AppLayer::REQUEST),
);
}
public function bootBeforeRequest(Container $container): void
{
$container->get(RequestState::class)->start();
}
public function releaseAfterRequest(Container $container): void
{
$container->get(RequestState::class)->finish();
}
}bootBeforeRequest() runs after the request container is created. releaseAfterRequest() runs when the request ends, for cleanup.
Child Containers
A child container inherits its parent's definitions. When a child looks up a service that only the parent has, it takes a copy. Values set on the child stay there:
$child = $app->getContainer()->createChild();
$child->getLevel(); // 3
$child->share('request.id', 'req-42');
$app->getContainer()->has('request.id'); // falseFor details, see Multi Levels.