Definition Sources

Purpose and Scope

This document covers the definition source subsystem responsible for aggregating service definitions from multiple configuration sources and providing them to the container during initialization. The subsystem consists of two primary classes: DefinitionSourceFactory and DefinitionSource.

For information about how these definitions are loaded and merged during initialization, see Configuration Loading & Merging. For information about how the container uses these definitions, see Container Implementation.

---

Overview

The definition source subsystem aggregates service dependency definitions from three distinct sources:

1. Provider Configuration: Definitions from ProviderConfig (if available)
2. Autoload Configuration: Definitions from config/autoload/dependencies.php
3. Explicit Configuration: Definitions from config/dependencies.php

These sources are merged with a specific priority order where later sources override earlier ones, and the result is stored in a DefinitionSource instance that the container uses during dependency resolution.

Sources: src/DefinitionSourceFactory.php1-39

---

DefinitionSourceFactory

The DefinitionSourceFactory class is an invokable factory responsible for creating DefinitionSource instances. It implements the aggregation logic that combines definitions from multiple sources.

Class Structure

Sources: src/DefinitionSourceFactory.php10-11 src/DefinitionSource.php9

Invocation Process

The factory is invoked as a callable, executing the aggregation process and returning a fully configured DefinitionSource. The method signature is:

Sources: src/DefinitionSourceFactory.php12

Aggregation Flow

The following diagram shows the complete aggregation process from initialization through final DefinitionSource creation:

Sources: src/DefinitionSourceFactory.php12-38

Validation

The factory performs a critical validation check before any aggregation occurs:

Validation	Condition	Exception
BASE_PATH Constant	Must be defined	Hyperf\Di\Exception\Exception with message "BASE_PATH is not defined."

Sources: src/DefinitionSourceFactory.php14-16

Source Priority and Merging

Definitions are merged using array_replace(), which means later sources override earlier sources. The priority order is:

The specific merge order is:

1. Base: $configFromProviders['dependencies'] ?? [] from src/DefinitionSourceFactory.php23
2. First Override: config/autoload/dependencies.php applied at src/DefinitionSourceFactory.php33
3. Final Override: config/dependencies.php applied at src/DefinitionSourceFactory.php33

This allows explicit configuration files to override provider defaults, providing flexibility in deployment-specific customization.

Sources: src/DefinitionSourceFactory.php23-35

File Path Resolution

The factory looks for dependency configuration files at two specific locations:

Priority	Path	Purpose
1	BASE_PATH/config/autoload/dependencies.php	Auto-loaded dependency configuration
2	BASE_PATH/config/dependencies.php	Explicit dependency configuration

Both paths are optional. If a file does not exist, it is silently skipped with no error.

Sources: src/DefinitionSourceFactory.php26-35

---

DefinitionSource

The DefinitionSource class extends Hyperf's base DefinitionSource and serves as the storage container for all aggregated service definitions.

Inheritance Hierarchy

The class inherits all functionality from Hyperf\Di\Definition\DefinitionSource, including the internal $source array that stores definitions.

Sources: src/DefinitionSource.php7-9

Constructor

The DefinitionSource is instantiated by DefinitionSourceFactory with the merged definitions array:

This array is passed to the parent constructor, which stores it in the protected $source property inherited from Hyperf's base class.

Sources: src/DefinitionSourceFactory.php37

Additional Methods

removeDefinition()

The primary enhancement over Hyperf's base class is the removeDefinition() method:

This method removes a specific service definition from the internal $source array:

This capability is useful for:

• Dynamic service reconfiguration
• Removing deprecated service bindings
• Testing scenarios requiring clean state

Sources: src/DefinitionSource.php14-17

---

Integration Points

The following diagram shows how DefinitionSourceFactory and DefinitionSource integrate with the broader container system:

Key Integration Points:

Integration	Component	Method/Property	Purpose
Creation	Bootstrap	Invokes DefinitionSourceFactory	Initialize definition aggregation
Configuration	ProviderConfig	load() static method	Provide provider-based definitions
File Loading	Filesystem	include statements	Load array-based definitions
Container Usage	Container	Inherits from Hyperf container	Uses definitions for service resolution

Sources: src/DefinitionSourceFactory.php12-38 src/DefinitionSource.php9

---

Definition Array Format

Both configuration files and ProviderConfig must return an associative array mapping service identifiers to their implementations:

The exact format follows Hyperf's definition specification, supporting:

• Interface-to-class mappings
• Alias-to-class mappings
• Factory definitions
• Instance definitions

Sources: src/DefinitionSourceFactory.php23-35

---

Error Handling

The subsystem has minimal error handling by design:

Condition	Behavior
BASE_PATH not defined	Throws Hyperf\Di\Exception\Exception
ProviderConfig class missing	Silent skip, continues with empty array
Configuration file missing	Silent skip, continues without that source
Invalid array format in config file	Undefined behavior (relies on PHP's array handling)

This design prioritizes flexibility, allowing the container to operate with partial configuration when some sources are unavailable.

Sources: src/DefinitionSourceFactory.php14-16 src/DefinitionSourceFactory.php19-21 src/DefinitionSourceFactory.php30-35