Framework Integration

Purpose and Scope

This document explains how Telescope integrates with the Hyperf and Hypervel framework ecosystems. It covers the package structure, dependency requirements, and the dual-provider pattern that enables Telescope to hook into both Hyperf's dependency injection container and Hypervel's service registration system.

For information about Telescope's internal architecture, see Architecture. For configuration options, see Configuration.

---

Package Structure and Dependencies

Telescope is distributed as a Composer package named hypervel/telescope. The package follows PSR-4 autoloading standards and declares dependencies on both Hyperf and Hypervel framework components.

Composer Package Metadata

The package is identified by the following metadata:

Property	Value
Package Name	hypervel/telescope
Description	The telescope package for Hypervel
License	MIT
Namespace	Hypervel\Telescope\
Source Directory	src/
Branch Alias	0.3-dev for dev-main

Sources: composer.json1-11 composer.json31-38

Required Dependencies

Telescope requires PHP 8.2 or higher and depends on six framework packages:

Dependency	Version	Purpose
php	^8.2	Language runtime with modern features
hyperf/context	~3.1.0	Request-scoped state management
hyperf/support	~3.1.0	Framework utilities and helpers
hyperf/stringable	~3.1.0	Fluent string manipulation
hyperf/tappable	~3.1.0	Tap method pattern support
hyperf/collection	~3.1.0	Enhanced array/collection operations
hypervel/core	^0.3	Hypervel framework extensions

The version constraint ~3.1.0 for Hyperf packages allows minor version updates within the 3.1.x series, while ^0.3 for hypervel/core allows minor and patch updates within the 0.x series until version 1.0.

Sources: composer.json22-29

PSR-4 Autoloading Configuration

The package uses PSR-4 autoloading with a single namespace-to-directory mapping:

Namespace: Hypervel\Telescope\
Directory: src/

This means that the class Hypervel\Telescope\Telescope is located at src/Telescope.php, and Hypervel\Telescope\Watchers\RequestWatcher is located at src/Watchers/RequestWatcher.php.

Sources: composer.json31-34

---

Hyperf and Hypervel Integration

Telescope uses a dual-provider pattern to integrate with both the Hyperf and Hypervel frameworks. This pattern enables Telescope to leverage Hyperf's low-level dependency injection container while also participating in Hypervel's high-level service registration and bootstrapping.

Dual-Provider Registration

The composer.json file registers two providers in different framework integration points:

Sources: composer.json36-47

Provider Responsibilities

The following diagram shows how the two providers divide responsibilities and when they execute in the framework lifecycle:

Framework Integration Lifecycle

Sources: composer.json40-46 src/TelescopeServiceProvider.php18-180

ConfigProvider (Hyperf Integration)

The ConfigProvider class is registered in the extra.hyperf.config section of composer.json. Hyperf's auto-discovery system instantiates this class during container initialization and calls its __invoke() method to retrieve dependency injection configuration.

Role: Low-level dependency injection container configuration

Execution Phase: Container initialization (before service providers)

Responsibilities:

• Define DI container bindings
• Register AOP aspects
• Configure published resources
• Declare configuration files

The ConfigProvider class is not shown in the provided files, but based on standard Hyperf patterns, it would be located at src/ConfigProvider.php and would return an array with keys like dependencies, aspects, annotations, and publish.

Sources: composer.json40-42

TelescopeServiceProvider (Hypervel Integration)

The TelescopeServiceProvider class is registered in the extra.hypervel.providers array. Hypervel instantiates this provider and calls its register() and boot() methods during application bootstrapping.

Role: High-level service registration and application bootstrapping

Execution Phase: After container initialization, during application boot

Class: Hypervel\Telescope\TelescopeServiceProvider

Location: src/TelescopeServiceProvider.php18-180

Provider Structure

Sources: src/TelescopeServiceProvider.php18-180

register() Method

The register() method executes before boot() and is responsible for container-level service registration:

Method Signature: public function register(): void

Location: src/TelescopeServiceProvider.php112-122

Operations:

1. Configuration Merging src/TelescopeServiceProvider.php114-117

   • Merges config/telescope.php from the package into the application configuration
   • Application configuration takes precedence

2. Storage Driver Registration src/TelescopeServiceProvider.php119

   • Calls registerStorageDriver(), which dynamically invokes driver-specific registration methods
   • For the database driver, calls registerDatabaseDriver() src/TelescopeServiceProvider.php163-178
   • Binds three repository contracts to DatabaseEntriesRepository:
     • EntriesRepository::class - Basic entry storage
     • ClearableRepository::class - Entry clearing operations
     • PrunableRepository::class - Entry pruning operations

3. Redis Event Registration src/TelescopeServiceProvider.php120

   • Conditionally enables Redis command monitoring if RedisWatcher is enabled
   • Calls RedisWatcher::enableRedisEvents($this->app) src/TelescopeServiceProvider.php127-134

4. Cache Event Registration src/TelescopeServiceProvider.php121

   • Conditionally enables cache event monitoring if CacheWatcher is enabled
   • Calls CacheWatcher::enableCacheEvents($this->app) src/TelescopeServiceProvider.php139-146

boot() Method

The boot() method executes after all service providers have been registered and is responsible for application-level bootstrapping:

Method Signature: public function boot(): void

Location: src/TelescopeServiceProvider.php23-48

Operations:

1. Command Registration src/TelescopeServiceProvider.php25

   • Registers five console commands:
     • Console\ClearCommand::class - Clear all entries
     • Console\PauseCommand::class - Pause recording
     • Console\PruneCommand::class - Prune old entries
     • Console\PublishCommand::class - Publish assets
     • Console\ResumeCommand::class - Resume recording
   • Implementation: src/TelescopeServiceProvider.php98-107

2. Publishable Resource Configuration src/TelescopeServiceProvider.php26

   • Configures four publishable resource groups:
     • telescope-migrations - Database migration file
     • telescope-assets - Public JavaScript and CSS files
     • telescope-config - Configuration file
     • telescope-provider - Stub service provider
   • Implementation: src/TelescopeServiceProvider.php76-93

3. Enabled Check src/TelescopeServiceProvider.php28-30

   • Reads config('telescope.enabled')
   • If false, skips all remaining initialization
   • This provides a quick way to disable Telescope without uninstalling

4. Route Registration src/TelescopeServiceProvider.php32

   • Mounts web UI routes under the configured path (default: /telescope)
   • Applies configured middleware
   • Routes file: routes/web.php
   • Implementation: src/TelescopeServiceProvider.php53-63

5. View Resource Registration src/TelescopeServiceProvider.php33

   • Loads view templates from resources/views with namespace telescope
   • Views can be referenced as telescope::view-name
   • Implementation: src/TelescopeServiceProvider.php68-71

6. Telescope Core Initialization src/TelescopeServiceProvider.php35

   • Calls Telescope::start($this->app) to initialize the core monitoring system
   • Registers all configured watchers
   • Sets up internal recording state

7. Storage Opportunity Listener Registration src/TelescopeServiceProvider.php36

   • Calls Telescope::listenForStorageOpportunities($this->app)
   • Registers event listeners for request/command lifecycle events
   • Determines when to start/stop recording

8. Coroutine Context Propagation src/TelescopeServiceProvider.php38-47

   • Registers a callback with Coroutine::afterCreated()
   • Propagates three context keys from parent to child coroutines:
     • Telescope::SHOULD_RECORD - Whether recording is enabled
     • Telescope::IS_RECORDING - Re-entrancy guard flag
     • Telescope::BATCH_ID - Current batch identifier
   • Ensures child coroutines inherit the parent's recording state

Storage Driver Registration Pattern

The storage driver registration uses a dynamic method dispatch pattern:

Location: src/TelescopeServiceProvider.php151-158

This pattern allows for extensibility. If config('telescope.driver') is set to "database", it calls registerDatabaseDriver(). Custom drivers can be supported by adding corresponding register{Driver}Driver() methods.

Database Driver Binding

The database driver binds three repository contracts to a single implementation:

Location: src/TelescopeServiceProvider.php163-178

This pattern allows for interface segregation—different parts of Telescope can depend on only the repository capabilities they need, while all three interfaces are satisfied by the same implementation.

Integration Points Summary

The following table summarizes the integration points between Telescope and the frameworks:

Integration Point	Provider	Phase	Key Operations
DI Container Bindings	ConfigProvider	Container initialization	Aspect registration, dependency resolution
Repository Contracts	TelescopeServiceProvider::register()	Service registration	Bind EntriesRepository, ClearableRepository, PrunableRepository
Watcher-Specific Events	TelescopeServiceProvider::register()	Service registration	Enable Redis/Cache events if watchers configured
Console Commands	TelescopeServiceProvider::boot()	Application bootstrap	Register management commands
Web UI Routes	TelescopeServiceProvider::boot()	Application bootstrap	Mount routes with middleware
Core System	TelescopeServiceProvider::boot()	Application bootstrap	Initialize Telescope::start()
Lifecycle Hooks	TelescopeServiceProvider::boot()	Application bootstrap	Register listenForStorageOpportunities()
Coroutine Propagation	TelescopeServiceProvider::boot()	Application bootstrap	Propagate context to child coroutines

Sources: composer.json40-47 src/TelescopeServiceProvider.php18-180

Framework Dependency Usage

Telescope makes extensive use of Hyperf framework components throughout its codebase:

Core Dependencies Used

Sources: composer.json22-28 src/TelescopeServiceProvider.php1-180

The hyperf/context dependency is particularly critical, as Telescope relies on Hyperf's context system to maintain request-scoped state in a coroutine-safe manner. Without this, Telescope could not track which entries belong to which request in Swoole's concurrent environment.