Hub Factory and Custom Integrations

Purpose and Scope

This document details the initialization process of the Sentry client through the ClientBuilderFactory and HubFactory classes, which configure the Sentry SDK for the Hyperf framework. It covers how the factory pattern is used to create and configure the Sentry Hub, how default SDK integrations are selectively replaced with Hyperf-specific implementations, and how applications can register custom integrations to extend Sentry's functionality.

For information about the overall Sentry configuration file structure, see Configuration and Initialization. For details about how traces are created and propagated, see Distributed Tracing Architecture.

Factory Architecture and Initialization Flow

The Sentry integration uses a two-stage factory pattern to construct the Hub instance, which is the central coordination point for all Sentry operations. The ClientBuilderFactory creates a configured ClientBuilder, and the HubFactory uses that builder to create the Hub with appropriate integrations.

Factory Initialization Flow

Sources: src/sentry/src/ConfigProvider.php57-60 src/sentry/src/Factory/ClientBuilderFactory.php30-75 src/sentry/src/Factory/HubFactory.php32-94

The dependency injection container resolves the HubInterface by invoking HubFactory, which in turn depends on ClientBuilder resolved through ClientBuilderFactory. This creates a clean separation between configuration concerns (handled by ClientBuilderFactory) and integration management (handled by HubFactory).

ClientBuilderFactory: Configuration and Options

The ClientBuilderFactory is responsible for creating a properly configured ClientBuilder instance by merging user configuration with framework defaults and resolving container-bound services.

Configuration Resolution Process

Configuration Validation and Merging

Sources: src/sentry/src/Factory/ClientBuilderFactory.php30-75

The factory performs several key operations:

1. Options Validation: Uses the SDK's internal OptionsResolver to filter user configuration, keeping only valid options defined by the Sentry PHP SDK src/sentry/src/Factory/ClientBuilderFactory.php35-37

2. Logger Resolution: If logger is specified as a string (typically a container reference like Hyperf\Contract\StdoutLoggerInterface::class), it resolves the logger from the container src/sentry/src/Factory/ClientBuilderFactory.php39-45

3. Framework Defaults: Applies sensible defaults for Hyperf applications:

   • Sets prefixes to [BASE_PATH] for stack trace filtering
   • Excludes vendor directory from stack traces: [BASE_PATH . '/vendor']
   • Defaults environment to APP_ENV if not configured src/sentry/src/Factory/ClientBuilderFactory.php48-59

4. Transport Override: If no transport is explicitly configured, uses the container-bound CoHttpTransport instead of Guzzle's default src/sentry/src/Factory/ClientBuilderFactory.php64-69

5. SDK Identification: Sets SDK identifier and version for proper client identification in Sentry src/sentry/src/Factory/ClientBuilderFactory.php71-73

Key Configuration Options

Configuration Key	Type	Purpose	Source Line
dsn	string	Sentry project DSN	publish/sentry.php14
environment	string	Application environment	publish/sentry.php21
release	string	Application version/release	publish/sentry.php18
sample_rate	float	Error sampling rate	publish/sentry.php27
traces_sample_rate	float	Performance sampling rate	publish/sentry.php30
logger	string|LoggerInterface	PSR-3 logger for SDK	publish/sentry.php76
transport	TransportInterface	Event transport mechanism	ClientBuilderFactory.php65

Sources: src/sentry/publish/sentry.php13-76 src/sentry/src/Factory/ClientBuilderFactory.php39-69

HubFactory: Integration Management and Filtering

The HubFactory is responsible for constructing the Hub instance and managing the complete set of integrations that process Sentry events. It implements a sophisticated filtering strategy to replace default SDK integrations with Hyperf-specific implementations.

Integration Lifecycle and Registration

Integration Registration Process

Sources: src/sentry/src/Factory/HubFactory.php32-94

Default SDK Integration Filtering

The HubFactory removes specific default SDK integrations that are incompatible with Hyperf's coroutine-based architecture or handled differently by the framework:

Filtered Default Integrations

Integration Class	Reason for Removal	Source
ErrorListenerIntegration	PHP error handling delegated to Hyperf's exception handler	HubFactory.php51-52
ExceptionListenerIntegration	Exception handling delegated to Hyperf's exception handler	HubFactory.php55-56
FatalErrorListenerIntegration	Fatal errors handled by framework	HubFactory.php59-60
RequestIntegration	Replaced with coroutine-aware implementation	HubFactory.php66-67

Sources: src/sentry/src/Factory/HubFactory.php45-74

The filtering logic uses array_filter with a callback that checks each integration's type and excludes those listed above. After filtering, a new RequestIntegration is added with a Hyperf-specific RequestFetcher that retrieves the PSR-7 ServerRequestInterface from the coroutine context src/sentry/src/Factory/HubFactory.php73-74

Built-in Custom Integrations

The framework provides three custom integrations that are automatically added to every Sentry hub:

Integration Structure

Built-in Integration Functionality

Sources: src/sentry/src/Factory/HubFactory.php77-84

1. Integration (Main Framework Integration)

The primary Integration class provides the flushEvents() static method used throughout the codebase to ensure events are sent to Sentry before coroutine completion src/sentry/src/Integration.php

2. ExceptionContextIntegration

Enhances exception reporting by extracting additional context from exceptions that implement a context() method. This integration uses Sentry's global event processor system to inspect each exception and add its context data as event extras.

Implementation Flow:

1. Registers a global event processor via Scope::addGlobalEventProcessor()
2. For each event, checks if the exception hint exists and has an exception
3. If the exception has a context() method, calls it
4. If the result is an array, adds it to the event as exception_context in extras

Sources: src/sentry/src/Integration/ExceptionContextIntegration.php22-44

3. RequestIntegration

Provides user identification based on client IP addresses from HTTP requests. Unlike the SDK's default RequestIntegration, this implementation is coroutine-aware and retrieves the request from Hyperf's context system.

IP Resolution Priority:

1. Checks x-real-ip header (common behind proxies)
2. Falls back to remote_addr from server params
3. Defaults to 127.0.0.1 if no request context exists

This integration only activates when the send_default_pii option is enabled src/sentry/src/Integration/RequestIntegration.php30

Sources: src/sentry/src/Integration/RequestIntegration.php22-58

Adding User-Defined Integrations

Applications can register custom integrations through the integrations configuration key, which accepts either an array of integration class names/instances or a callable that receives and modifies the integration array.

Configuration Methods

Method 1: Array of Integration Classes/Instances

Method 2: Callable for Advanced Control

Sources: src/sentry/publish/sentry.php121-122 src/sentry/src/Factory/HubFactory.php38-42 src/sentry/src/Factory/HubFactory.php87-89

Integration Resolution Process

The resolveIntegrationsFromUserConfig() method handles three types of integration definitions:

Integration Type Handling

Sources: src/sentry/src/Factory/HubFactory.php100-120

The resolver processes three scenarios:

1. Direct Integration Instance: If the item already implements IntegrationInterface, it's added directly src/sentry/src/Factory/HubFactory.php105-106

2. Class Name String: If the item is a string, it's resolved from the container using make(), then validated to ensure it implements IntegrationInterface src/sentry/src/Factory/HubFactory.php107-114

3. Invalid Type: Any other type throws a RuntimeException with a descriptive error message src/sentry/src/Factory/HubFactory.php116

Integration Execution Order and Priority

The final integration array is constructed in a specific order to ensure proper precedence:

Integration Execution Order

Priority	Integration Source	Examples	Insertion Point
1	Filtered SDK defaults	EnvironmentIntegration, FrameContextifierIntegration	Start of array
2	Custom RequestIntegration	With RequestFetcher	After filtering
3	Framework integrations	Integration, ExceptionContextIntegration, RequestIntegration	Middle of array
4	User-defined integrations	From integrations config	End of array

Sources: src/sentry/src/Factory/HubFactory.php77-91

This ordering ensures that:

• SDK integrations that should remain active execute first
• Framework-specific implementations override SDK defaults
• User customizations have the final say in integration behavior

If the user provides a callable in the integrations configuration, it receives the complete array after all merging is done and can perform final modifications before the Hub is created src/sentry/src/Factory/HubFactory.php87-89

Complete Factory Registration

The factories are registered in the dependency injection container through the ConfigProvider:

Sources: src/sentry/src/ConfigProvider.php57-61

This registration enables constructor injection of HubInterface throughout the application, with the Hub automatically configured with all appropriate integrations and settings based on the configuration file.