Feature System Overview

Purpose and Scope

This document explains the feature system architecture used by the hypervel/sentry package. The feature system provides a modular approach to monitoring different aspects of the Hypervel framework, allowing each monitoring capability to be enabled, disabled, and configured independently.

This page covers:

• The Feature base class and its lifecycle methods
• How features are discovered, registered, and booted
• The Switcher class and its role in controlling feature behavior
• Configuration structure for enabling/disabling features and their telemetry types

For specific monitoring capabilities (cache, queue, Redis, console scheduling), see pages 3.2 through 3.5. For the service provider's overall orchestration role, see 2.1.

---

Feature Architecture

Feature Class Structure

All monitoring features extend from a common Feature base class and follow a consistent architectural pattern. Each feature is a self-contained unit responsible for monitoring a specific framework subsystem.

Class Hierarchy Diagram

Sources: src/Features/CacheFeature.php32-44

Feature Key Constants

Each feature defines a FEATURE_KEY constant that corresponds to its configuration namespace. This key is used throughout the feature's implementation to check applicability and configuration settings.

Feature Class	Feature Key	Configuration Base Path
CacheFeature	cache	sentry.breadcrumbs.cache, sentry.tracing.cache
QueueFeature	queue	sentry.breadcrumbs.queue, sentry.tracing.queue
RedisFeature	redis	sentry.breadcrumbs.redis, sentry.tracing.redis
ConsoleSchedulingFeature	console_scheduling	sentry.tracing.console_scheduling
LogFeature	logs	sentry.breadcrumbs.logs

Sources: src/Features/CacheFeature.php38

---

Feature Lifecycle

The feature system follows a two-phase initialization process coordinated by the SentryServiceProvider: registration and boot.

Feature Lifecycle Sequence

Sources: src/SentryServiceProvider.php110-142

Registration Phase

During the registration phase, the service provider reads the feature list from configuration and performs two critical operations:

1. Dependency Injection Binding - Each feature class is bound to the container, allowing it to be resolved with all dependencies injected.

2. Feature Registration - Each feature's register() method is called, allowing it to bind additional services or perform early setup.

This phase occurs during the service provider's register() method:

SentryServiceProvider::register()
 ├─> registerFeatures()
 ├─> Read config: sentry.features
 ├─> Bind each feature class to container
 └─> Call feature->register() for each feature

Sources: src/SentryServiceProvider.php110-127

Boot Phase

During the boot phase, features perform their primary initialization by registering event listeners and framework extensions. The boot process is conditional - each feature determines whether it should activate by implementing the isApplicable() method.

The boot sequence:

SentryServiceProvider::boot()
 ├─> bootFeatures()
 ├─> Resolve each feature from container
 ├─> Call feature->boot()
 │ ├─> Check feature->isApplicable()
 │ └─> If applicable, call feature->onBoot()
 └─> Features register event listeners

The boot() method in the Feature base class implements the applicability check:

public function boot(): void
{
 if ($this->isApplicable()) {
 $this->onBoot();
 }
}

Concrete features override onBoot() to perform their specific initialization:

Sources: src/SentryServiceProvider.php129-142 src/Features/CacheFeature.php46-81

Error Handling

Both registration and boot phases wrap feature processing in try-catch blocks to ensure that failures in one feature do not break the entire application:

This defensive approach allows the Sentry integration to degrade gracefully if individual features encounter errors.

Sources: src/SentryServiceProvider.php118-126 src/SentryServiceProvider.php134-141

---

Configuration and Switcher

The Switcher Class

The Switcher class provides a centralized API for checking feature configuration. It reads from the sentry configuration namespace and provides three levels of control:

Switcher Configuration Hierarchy

Sources: src/Switcher.php1-33

Switcher Methods

The Switcher class exposes three public methods:

Method	Purpose	Configuration Key	Default
isEnabled(string $key, bool $default = true)	Check if a feature is generally enabled	sentry.enable.{key}	true
isBreadcrumbEnable(string $key)	Check if breadcrumb capture is enabled	sentry.breadcrumbs.{key}	true
isTracingEnable(string $key)	Check if tracing spans are enabled	sentry.tracing.{key}	true

Important: The isTracingEnable() method first checks the global sentry.enable_tracing flag. If global tracing is disabled, it returns false regardless of the feature-specific setting.

Sources: src/Switcher.php15-32

Configuration Structure

Features are configured in config/sentry.php with the following structure:

config/sentry.php
├── features: [] # List of feature classes to load
├── enable_tracing: bool # Global tracing toggle
├── enable: [] # Feature-specific enable flags
│ ├── cache: bool
│ ├── queue: bool
│ └── redis: bool
├── breadcrumbs: [] # Feature-specific breadcrumb flags
│ ├── cache: bool
│ ├── queue: bool
│ ├── redis: bool
│ └── logs: bool
└── tracing: [] # Feature-specific tracing flags
 ├── cache: bool
 ├── queue: bool
 ├── redis: bool
 └── console_scheduling: bool

This three-level hierarchy allows fine-grained control:

1. Feature Level: Include/exclude entire features via the features array
2. Telemetry Type Level: Enable/disable breadcrumbs or tracing per feature
3. Global Level: Disable all tracing regardless of feature settings

Sources: src/Switcher.php15-32

Applicability Checks

Each feature implements isApplicable() to determine whether it should activate. This method typically checks the Switcher to see if breadcrumbs or tracing are enabled:

Example from CacheFeature:

This pattern ensures:

• Features only activate when at least one telemetry type is enabled
• Event listeners are not registered for disabled features
• Minimal performance overhead when features are disabled

Sources: src/Features/CacheFeature.php40-44

---

Feature Integration Pattern

Event-Driven Monitoring

Features integrate with the framework by listening to events dispatched by framework components. The typical pattern:

Feature Event Integration Flow

Sources: src/Features/CacheFeature.php46-81

Conditional Event Listeners

Features register different event listeners based on which telemetry types are enabled. This optimization prevents unnecessary event processing when features are partially disabled.

Example from CacheFeature:

The onBoot() method registers different event sets based on configuration:

if (breadcrumbs enabled for cache):
 Listen to: CacheHit, CacheMissed, KeyWritten, KeyForgotten
 Handler: handleCacheEventsForBreadcrumbs()

if (tracing enabled for cache):
 Listen to: RetrievingKey, CacheHit, CacheMissed, WritingKey, 
 KeyWritten, KeyWriteFailed, ForgettingKey, etc.
 Handler: handleCacheEventsForTracing()

This conditional registration ensures:

• No overhead when features are disabled
• Selective monitoring when only breadcrumbs or only tracing is needed
• Clean separation between breadcrumb and tracing logic

Sources: src/Features/CacheFeature.php55-80

Feature Dependencies

Features have access to core dependencies injected through the base Feature class:

Dependency	Type	Usage
$container	Container	Resolve additional services (config, event dispatcher, framework components)
$switcher	Switcher	Check feature configuration and applicability

Features can resolve additional dependencies from the container as needed during their lifecycle:

Sources: src/Features/CacheFeature.php46-54

---

Feature Discovery

Configuration-Driven Discovery

Features are discovered by reading the sentry.features configuration array, which contains fully-qualified class names of feature classes to load:

Feature Discovery and Resolution

Example configuration:

Users can enable or disable features by adding or removing entries from this array. Features not listed will not be loaded.

Sources: src/SentryServiceProvider.php112-127

Feature Loading Sequence

The complete feature loading sequence:

1. Configuration Read - SentryServiceProvider::registerFeatures() reads sentry.features from configuration
2. Container Binding - Each feature class is bound to itself in the container
3. Registration Call - Each feature's register() method is called (allows early service registration)
4. Boot Call - Each feature's boot() method is called (registers event listeners)
5. Applicability Check - Feature checks isApplicable() via the Switcher
6. Conditional Activation - If applicable, onBoot() executes and listeners are registered

This sequence ensures all features are available in the container before any feature attempts to boot, allowing features to potentially depend on each other if needed.

Sources: src/SentryServiceProvider.php110-142

---

Summary

The feature system provides a modular, configurable architecture for monitoring Hypervel framework components:

• Base Class Pattern: All features extend Feature and implement lifecycle hooks
• Two-Phase Initialization: Registration phase for dependency setup, boot phase for listener registration
• Conditional Activation: Features check Switcher configuration to determine if they should activate
• Granular Control: Three levels of configuration (feature, breadcrumb, tracing) for precise control
• Event-Driven: Features listen to framework events and create Sentry telemetry in response
• Error Isolation: Try-catch blocks ensure feature failures don't break the application
• Configuration-Driven Discovery: Features are loaded based on the sentry.features array

For implementation details of specific monitoring capabilities, see:

• 3.2 - Cache Monitoring
• 3.3 - Queue Monitoring
• 3.4 - Redis Monitoring
• 3.5 - Console Scheduling

Sources: src/SentryServiceProvider.php1-144 src/Features/CacheFeature.php1-289 src/Switcher.php1-33