Dependency injection library
The dependency injection library is a small PSR-11 service container for PHP applications. It lets startup code register named factories, resolve their declared dependencies, and create child scopes that reuse or replace services for a request, worker, or test. It is one of the reusable platform packages described in reusable platform packages.
Container role
The container is a composition boundary between application setup and the code that uses services. The application chooses the service names and factory rules, while the library controls lookup order, dependency passing, caching, and the parent-child scope relationship.
Service registration
Registration associates a string ID with a factory and an ordered list of IDs that the factory needs. The container does not inspect constructor types or discover services by class name. When a service is requested, it resolves the listed IDs in order and passes their values to the factory in the same order.
A later registration with the same ID replaces the local factory and clears its cached value. This makes registration suitable for startup setup and for deliberate local replacement in a child scope.
References: packages/…/Container.php• L41-57 packages/…/README.md• L42-62 packages/…/ContainerTest.php• L96-123 packages/…/ContainerTest.php• L124-141
Service lifetime
Each container caches a service after its factory runs. Later lookups return the same value, including a cached null, so a factory runs at most once for that container unless a new local registration replaces it. The cache belongs to the container that owns the factory.
This lifetime is local to the container graph. A parent-owned service remains shared by children that inherit it, while a child-owned replacement has its own value and does not change the parent.
References: packages/…/Container.php• L27-31 packages/…/Container.php• L59-69 packages/…/ContainerTest.php• L37-51 packages/…/ContainerTest.php• L163-176 packages/…/ContainerTest.php• L230-246
Lookup semantics
Lookup starts in the container that receives the request. The container first uses a local cached value, then builds a local factory, and only then asks its parent. A missing ID reaches the end of the parent chain and becomes a PSR-11 not-found error.
The following flow shows how a request moves through a child and its parent.
flowchart TD
A[Request service ID] --> B{Cached locally?}
B -- Yes --> C[Return local value]
B -- No --> D{Factory registered locally?}
D -- Yes --> E[Resolve declared IDs in this container]
E --> F[Run factory and cache result]
F --> C
D -- No --> G{Parent container exists?}
G -- Yes --> H[Ask parent to resolve ID]
G -- No --> I[Raise not-found exception]
Parent-child scopes
A child scope inherits services from its parent without copying them. A child can add a service that exists only in that scope or override a parent ID without mutating the parent. Parent and grandparent lookup therefore supports shared application services with narrow request or test replacements.
The parent resolves its own factories in its own scope. A child-provided ID is available to a child factory, but it does not satisfy a dependency while the child is resolving a factory owned by the parent. This keeps ownership and lifetime aligned with the container that registered the factory.
References: packages/…/Container.php• L34-39 packages/…/Container.php• L59-76 packages/…/ContainerTest.php• L178-228 packages/…/ContainerTest.php• L248-272
Availability checks
The has check reports whether a factory is registered in the current container or any parent. It does not build the service, so a positive result means that lookup is defined rather than that the service has already been created.
References: packages/…/Container.php• L78-85 packages/…/ContainerTest.php• L63-94 packages/…/ContainerTest.php• L285-294
Exception boundaries
The library follows PSR-11 exception contracts at the lookup boundary. It gives callers a specific not-found signal for an ID that no container in the parent chain defines, while the package also exposes a general container exception type for PSR-11-compatible integrations.
Missing services
An unknown ID raises Utopia\DI\Exceptions\NotFoundException, which implements Psr\Container\NotFoundExceptionInterface. Callers can catch the PSR-11 interface instead of coupling error handling to this package. The error occurs only after local and parent lookup fail.
References: packages/…/Container.php• L71-76 packages/…/NotFoundException.php• L5-10 packages/…/ContainerTest.php• L53-61 packages/…/ContainerTest.php• L221-228
Factory failures
The container does not catch or translate errors raised while it resolves dependencies or runs a factory. A missing dependency therefore raises the same not-found error from the nested lookup, while an error from application factory code crosses the boundary as that error. The defined ContainerException type is a PSR-11-compatible exception class, but the current container does not use it for its normal lookup path.
References: packages/…/Container.php• L87-101 packages/…/ContainerException.php• L5-10 packages/…/NotFoundException.php• L5-10 packages/…/ContainerTest.php• L248-272
Package relationships
The dependency injection package supplies service composition, not resource lookup or application startup policy. Application bootstrap can use it to assemble shared services and child scopes. Registry library is a related but separate package for named resource creation and context management; choose the boundary that matches whether the caller is composing services or managing resources.
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the dependency ID list and factory argument order aligned. A mismatch can produce valid PHP calls with the wrong service values.
- When changing parent-child lookup, preserve the rule that parent-owned factories resolve from the parent scope. Otherwise child overrides can change the lifetime or meaning of shared services.
- When changing cache invalidation, review both replacement behavior and cached
nullvalues. Both affect whether a factory runs again. - When changing exception classes, preserve the PSR-11 interfaces so callers can handle missing services and other container errors through stable contracts.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A factory lists an ID that no owning scope defines | Resolution stops with NotFoundException before the factory runs | Register every declared dependency in the same scope or an ancestor that owns the factory |
| A child provides a dependency needed by a parent-owned factory | The parent cannot see the child value and lookup fails | Register the dependency with the parent or register the dependent factory in the child |
| A service is re-registered after it was resolved | The old local cached value is discarded and later lookup creates a new value | Treat set as a replacement boundary and register overrides before dependent work starts |
A caller assumes ContainerException wraps factory errors | Application errors are not converted to that type | Handle application factory errors at the application boundary and use PSR-11 not-found handling for missing IDs |
Key files
| File | Why to read it |
|---|---|
| packages/…/Container.php | Defines registration, ordered dependency resolution, caching, parent lookup, and availability checks. |
| packages/…/NotFoundException.php | Defines the package-specific missing-service error and its PSR-11 contract. |
| packages/…/ContainerException.php | Defines the available general PSR-11 container error type. |
| packages/…/README.md | Gives the package purpose and the intended parent-child scope model. |
| packages/…/ContainerTest.php | Shows the supported lookup, caching, override, dependency-order, and scope guarantees. |