README

Shared execution scope contracts and value objects for Componenta packages.

Use this package when a framework component must declare or check where it is allowed to run: HTTP, CLI, WebSocket, queue worker, or a package-specific scope.

Installation

composer require componenta/scope

What It Provides

• ScopeInterface: a scope marker with a string value and matches() comparison.
• ScopedInterface: implemented by objects that expose a Scopes collection.
• Scopes: non-empty immutable collection of ScopeInterface values.
• ScopeName: final value object for custom string scopes when a package-specific enum is not needed.

Concrete enums should live in the package that owns the execution mode. For example, componenta/app provides Componenta\App\Scope, and componenta/interceptor provides Componenta\Interceptor\Scope.

Defining Scopes

use Componenta\Scope\ScopeInterface;

enum AppScope: string implements ScopeInterface
{
    case HTTP = 'http';
    case CLI = 'cli';

    public function matches(ScopeInterface $scope): bool
    {
        return $this->value === $scope->value;
    }
}

For ad-hoc scopes:

use Componenta\Scope\ScopeName;

$scope = new ScopeName('worker');

Declaring Scoped Objects

use Componenta\Scope\ScopedInterface;
use Componenta\Scope\Scopes;

final class HttpOnlyService implements ScopedInterface
{
    public Scopes $scopes {
        get => Scopes::of(AppScope::HTTP);
    }
}

Matching

$scopes = Scopes::of(AppScope::HTTP, AppScope::CLI);

$scopes->contains(new ScopeName('http')); // true
$scopes->contains(new ScopeName('queue')); // false

$other = Scopes::of(new ScopeName('worker'), new ScopeName('cli'));
$scopes->containsAny($other); // true

Scopes::from() accepts any iterable of ScopeInterface values and rejects empty iterables.

Errors

• InvalidScopeException: thrown when ScopeName receives an empty value or Scopes::from() receives a non-scope value.
• EmptyScopesException: thrown when Scopes::from() receives an empty iterable.