Download the PHP package sirix/container-resolver without Composer

Container Resolver

Strict PSR-11 container service resolver and typed configuration reader for reusable PHP packages.

Stability

This package is currently pre-stable.

Until the first stable release, public contracts and behavior may change between releases based on real usage in Sirix packages. Semantic Versioning guarantees are not applied during this early iteration phase.

Use exact version constraints or review changelogs carefully when upgrading pre-stable versions.

Installation

Why

Package factories often need to read services and configuration from framework containers. Manual checks tend to repeat the same code, silently coerce invalid values, or fail with messages that do not explain which factory needs which value.

ContainerResolver and ConfigReader keep factory code small while preserving explicit failures:

• missing container services throw package-level not-found exceptions;
• invalid service types throw package-level container exceptions;
• missing required config values throw package-level config exceptions;
• existing invalid config values always throw;
• optional missing config values can use defaults;
• scalar config values are not coerced.

The package is framework-agnostic and only requires PHP and psr/container at runtime.

Container services

Use ContainerResolver when a service id is the expected class or interface:

Use getAs() when the service id is a custom string but the expected type is known:

Use getExisting() when you want the raw service value and will validate it yourself:

Use optional() for optional services:

Use optionalArray() for array services such as config:

If the service is missing, optionalArray() returns []. If the service exists but is not an array, it throws InvalidContainerServiceException.

Typed configuration

ConfigReader reads nested arrays with dot paths:

Available methods:

Strictness rules

Missing optional values return the supplied default:

Existing invalid values always throw InvalidConfigValueException:

Valid scalar values must already have the expected type:

String readers trim leading and trailing whitespace from configured string values:

This applies to string values, non-empty strings, string lists, string enums, and PHP enum case names/string-backed values. Trimming is normalization of strings only; scalar coercion is still not performed.

optionalNonEmptyString() is useful for optional values where an empty string should be treated as not configured:

Behavior:

list() requires a sequential list array:

entities may be absent; in that case the default [] is returned. If entities exists, it must be a list of non-empty strings.

enum() returns real PHP enum instances:

Accepted configured values:

Numeric strings are not coerced for int-backed enums:

For string-backed enums, the string backed value is accepted:

map() requires all keys to be strings:

Lists are rejected by map() because they do not describe named configuration entries. String-keyed maps are rejected by list() because they are not sequential lists.

Long-running process safety

The package is safe to use in long-running processes such as RoadRunner, Swoole, ReactPHP, queue workers, and persistent Mezzio/Laminas applications.

It does not use:

• global mutable state;
• static runtime caches;
• request-specific static properties;
• singleton resolver instances.

Resolver and reader instances are cheap to create per factory invocation:

Exceptions do not retain service instances or full config arrays.

Exceptions

All package exceptions implement:

Container-related exceptions also implement:

Config-related exceptions also implement:

Concrete exceptions:

MissingContainerServiceException implements Psr\Container\NotFoundExceptionInterface. InvalidContainerServiceException implements Psr\Container\ContainerExceptionInterface.

ContainerResolver wraps missing-service and invalid-type failures into package exceptions. Other container resolution failures from the underlying PSR-11 container are propagated unchanged.

That means:

• missing service or NotFoundExceptionInterface from the container becomes MissingContainerServiceException;
• wrong resolved service type becomes InvalidContainerServiceException;
• other ContainerExceptionInterface failures from the container remain the original container exception.

Public methods document their expected failure modes with @throws annotations.

Consumers can catch and wrap package exceptions:

Examples

Factory with configured service ids:

Design notes

This package intentionally does not provide:

• a DI container;
• autowiring;
• service definitions;
• framework adapters;
• config schema compilation;
• deep config merging;
• environment variable processors;
• secret resolution;
• runtime caching;
• scalar coercion.