Feature Guide

A quick orientation block that answers the essential questions: what this feature does, how it works, why it matters, and the key concepts behind it.

What this does

#[ExecutionScoped] opts a class into a per-execution clone; #[InjectAsMutable] marks the properties re-injected on that clone.

Execution Scope

Fresh clone for every execution

Mutable services can safely accumulate transient state because the container clones them for each execution context.

Any state collected during one execution is discarded when that HTTP request, console command, or async job completes.

#[InjectAsMutable]
protected ExecutionBag $bag;

// Each execution gets a fresh clone:
// $this->bag !== <previous execution\'s bag>

Use mutable injection for execution-specific context objects, not for shared worker services.

InjectAsMutable ExecutionScoped execution-scoped Request

Verified against Semitexa Ultimate 2026.09.19.1020

Mutable Injection

Two attributes work together here, and mixing them up is the usual mistake:

#[ExecutionScoped] goes on the class. It says: build a prototype at boot, then clone it for every execution.
#[InjectAsMutable] goes on a property. It says: this dependency is re-injected on each clone, so it is safe to hold per-execution state.

#[AsService]
#[ExecutionScoped]
final class IriBuilder
{
    #[InjectAsReadonly]
    protected ResourceMetadataRegistry $registry;

    #[InjectAsMutable]
    protected Request $request;
}

That is Semitexa\Core\Resource\IriBuilder, and it shows both tiers in one class: the metadata registry is worker-shared because it has no per-execution state, while the request is re-injected on every clone.

The #[AsService] is not redundant here. #[ExecutionScoped] sets the tier; it does not make a class container-managed on its own. #[AsService] is what puts the class under the container in the first place — see declaring a service.

An execution is a request, a console run, or an async job

"Execution scope" is not "request scope". The same boundary applies to a console command run and to an async job, which is what makes it the right unit in a long-running worker.

Most classes never write `#[ExecutionScoped]`

It is implied by the three attributes that already mark per-execution work:

#[AsPayloadHandler]
#[AsEventListener]
#[AsPipelineListener]

So a handler is already execution-scoped and simply uses #[InjectAsMutable] for the things that change per request:

#[AsPayloadHandler(payload: ..., resource: ...)]
final class DefaultNotFoundPageHandler
{
    #[InjectAsMutable]
    protected Request $request;
}

Write #[ExecutionScoped] explicitly only for a class that needs per-execution state without being a handler or listener — IriBuilder above is exactly that case.

What goes wrong without it

A worker-scoped service that quietly accumulates per-request state is the classic long-running-runtime bug: the second request sees the first request's data, and only under load. PHPStan's ExecutionScopedWithoutAttributeRule flags per-execution state on a class that never opted in, which is why the failure usually shows up in analysis rather than in production.

The inverse mistake is cheaper but still real: marking something execution-scoped that has no state at all just buys a clone per request for nothing. Shared is the default for a reason — see readonly injection.

1<?php23declare(strict_types=1);45namespace App\Application\Handler\Container;67use App\Application\Payload\Container\MutableInjectionPayload;8use App\Application\Resource\Page\ExecutionBagResource;9use App\Domain\Execution\ExecutionBag;10use Semitexa\Core\Attribute\AsPayloadHandler;11use Semitexa\Core\Attribute\InjectAsMutable;12use Semitexa\Core\Contract\TypedHandlerInterface;1314#[AsPayloadHandler(payload: MutableInjectionPayload::class, resource: ExecutionBagResource::class)]15final class MutableInjectionHandler implements TypedHandlerInterface16{17    #[InjectAsMutable]18    protected ExecutionBag $bag;1920    public function handle(MutableInjectionPayload $payload, ExecutionBagResource $resource): ExecutionBagResource21    {22        $this->bag->put('request_id', uniqid('req_', true));2324        return $resource->fromBag($this->bag);25    }26}27

<?php

declare(strict_types=1);

namespace App\Application\Handler\Container;

use App\Application\Payload\Container\MutableInjectionPayload;
use App\Application\Resource\Page\ExecutionBagResource;
use App\Domain\Execution\ExecutionBag;
use Semitexa\Core\Attribute\AsPayloadHandler;
use Semitexa\Core\Attribute\InjectAsMutable;
use Semitexa\Core\Contract\TypedHandlerInterface;

#[AsPayloadHandler(payload: MutableInjectionPayload::class, resource: ExecutionBagResource::class)]
final class MutableInjectionHandler implements TypedHandlerInterface
{
    #[InjectAsMutable]
    protected ExecutionBag $bag;

    public function handle(MutableInjectionPayload $payload, ExecutionBagResource $resource): ExecutionBagResource
    {
        $this->bag->put('request_id', uniqid('req_', true));

        return $resource->fromBag($this->bag);
    }
}