Introducing a new way to review your PRs.

Read the announcement

appwrite / appwrite

The open-source cloud for agents & devs. Including Auth, Databases, Storage, Functions, Messaging, Hosting, Realtime, WAF and more

View on GitHub

59 documents · Updated Nov 20, 2026

docs / dependency-injection-library

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 null values. 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

TriggerConsequenceGuard
A factory lists an ID that no owning scope definesResolution stops with NotFoundException before the factory runsRegister every declared dependency in the same scope or an ancestor that owns the factory
A child provides a dependency needed by a parent-owned factoryThe parent cannot see the child value and lookup failsRegister the dependency with the parent or register the dependent factory in the child
A service is re-registered after it was resolvedThe old local cached value is discarded and later lookup creates a new valueTreat set as a replacement boundary and register overrides before dependent work starts
A caller assumes ContainerException wraps factory errorsApplication errors are not converted to that typeHandle application factory errors at the application boundary and use PSR-11 not-found handling for missing IDs

Key files

FileWhy to read it
packages/…/Container.phpDefines registration, ordered dependency resolution, caching, parent lookup, and availability checks.
packages/…/NotFoundException.phpDefines the package-specific missing-service error and its PSR-11 contract.
packages/…/ContainerException.phpDefines the available general PSR-11 container error type.
packages/…/README.mdGives the package purpose and the intended parent-child scope model.
packages/…/ContainerTest.phpShows the supported lookup, caching, override, dependency-order, and scope guarantees.