Package Structure and Dependencies

This document describes the hypervel/telescope package structure defined in composer.json1-53 including PSR-4 autoloading configuration, dependency specifications, and dual framework integration points. The package uses both Hyperf's ConfigProvider and Hypervel's ServiceProvider patterns for registration.

For service provider bootstrapping details, see page 2.1.2. For configuration options, see page 4.

---

Package Metadata

Property	Value	Reference
Package Name	hypervel/telescope	composer.json2
Description	"The telescope package for Hypervel."	composer.json3
License	MIT	composer.json4
Keywords	php, hyperf, telescope, swoole, hypervel	composer.json5-10
PHP Requirement	^8.2	composer.json23
Root Namespace	Hypervel\Telescope\	composer.json33
Source Directory	src/	composer.json33
Author	Albert Chen (albert@hypervel.org)	composer.json18-19
Issues	https://github.com/hypervel/components/issues	composer.json13
Source Repository	https://github.com/hypervel/components	composer.json14

Sources: composer.json1-21

---

PSR-4 Autoloading

The package defines a single PSR-4 autoload mapping composer.json31-34:

Class Resolution Examples

PSR-4 Autoload Resolution

Fully Qualified Class Name	File Path
Hypervel\Telescope\Telescope	src/Telescope.php
Hypervel\Telescope\TelescopeServiceProvider	src/TelescopeServiceProvider.php
Hypervel\Telescope\ConfigProvider	src/ConfigProvider.php
Hypervel\Telescope\Watchers\RequestWatcher	src/Watchers/RequestWatcher.php
Hypervel\Telescope\Storage\DatabaseEntriesRepository	src/Storage/DatabaseEntriesRepository.php
Hypervel\Telescope\Contracts\EntriesRepository	src/Contracts/EntriesRepository.php
Hypervel\Telescope\Console\ClearCommand	src/Console/ClearCommand.php
Hypervel\Telescope\Aspects\GuzzleHttpClientAspect	src/Aspects/GuzzleHttpClientAspect.php

Sources: composer.json31-34

---

Dependencies

Telescope Dependency Graph

Dependency Details

Package	Version	Usage in Telescope
php	^8.2	Readonly properties in IncomingEntry, EntryResult; enums for entry types; improved type system
hyperf/context	~3.1.0	Context::get(), Context::set(), Context::override() for request-scoped flags: SHOULD_RECORD, IS_RECORDING, ENTRIES_QUEUE, UPDATES_QUEUE, BATCH_ID, HAS_STORED
hyperf/support	~3.1.0	Arr::get(), Arr::only(), Arr::except(), Str::limit() in watchers and entry formatting
hyperf/stringable	~3.1.0	Stringable class for fluent string manipulation in entry content formatting
hyperf/tappable	~3.1.0	tap() method for fluent configuration in Telescope::tag(), Telescope::filter() chains
hyperf/collection	~3.1.0	Collection class for managing entry arrays, tags, and batch operations in storage layer
hypervel/core	^0.3	Base ServiceProvider class, application instance access, configuration publishing

Version Constraints

Constraint	Meaning	Applied To
^8.2	>= 8.2.0, < 9.0.0	PHP runtime
~3.1.0	>= 3.1.0, < 3.2.0	Hyperf packages
^0.3	>= 0.3.0, < 0.4.0	Hypervel core

The ~3.1.0 constraint ensures compatibility within Hyperf 3.1's minor version range while preventing breaking changes from 3.2.

Sources: composer.json22-29

---

Framework Integration

Telescope uses a dual-provider pattern for integration with both Hyperf and Hypervel, declared in composer.json36-47:

Integration Architecture

Dual Provider Integration Pattern

ConfigProvider (Hyperf Integration)

The extra.hyperf.config key composer.json40-42 points to Hypervel\Telescope\ConfigProvider. This class provides low-level Hyperf integration:

Responsibilities:

• Returns dependencies array for DI container bindings
• Returns commands array for console command registration
• Returns publish array for configuration file publishing
• Discovered and invoked by Hyperf's config scanner during framework initialization

Example Structure:

TelescopeServiceProvider (Hypervel Integration)

The extra.hypervel.providers array composer.json43-46 declares Hypervel\Telescope\TelescopeServiceProvider. This is the main entry point:

Responsibilities:

• register() method: Merges configuration, registers storage drivers, binds repositories
• boot() method: Registers routes, publishes resources, initializes watchers, attaches storage listeners
• Extends Hypervel's ServiceProvider base class
• Loaded by Hypervel's service provider discovery system

Key Methods:

• registerRoutes(): Registers /telescope routes
• registerWatchers(): Instantiates and registers all 18+ watchers
• listenForStorageOpportunities(): Attaches RequestReceived/RequestHandled listeners
• configureQueue(): Sets up coroutine context propagation for queue jobs

Sources: composer.json36-47

---

Discovery and Initialization

Package Discovery and Initialization Sequence

Initialization Phases

Phase	Trigger	Actions	Key Classes
Autoloading	Application startup	Load vendor/autoload.php, parse composer.json, register PSR-4 mapping	Composer autoloader
Hyperf Config	Hyperf framework boot	Scan extra.hyperf.config, invoke ConfigProvider::__invoke(), register DI bindings and commands	ConfigProvider
Hypervel Register	Hypervel framework boot	Scan extra.hypervel.providers, call register(), merge config, bind repositories	TelescopeServiceProvider::register()
Hypervel Boot	After all providers registered	Call boot(), register routes/watchers/listeners, start recording	TelescopeServiceProvider::boot()

Method Call Chain

1. ConfigProvider::__invoke() → Returns configuration array
2. TelescopeServiceProvider::register() → Merges config, binds repositories
3. TelescopeServiceProvider::boot() → Initializes monitoring system
   • registerRoutes() → Registers /telescope routes
   • Telescope::start() → Enables recording system
   • registerWatchers() → Instantiates all watchers
   • listenForStorageOpportunities() → Attaches event listeners

Sources: composer.json31-47

---

Directory Structure

Package Directory Structure

Directory Organization

Directory	Namespace Segment	Contents	Purpose
composer.json	N/A	Package metadata, dependencies, autoload config	Package definition composer.json1-53
config/	N/A	telescope.php	Default configuration file
src/	Hypervel\Telescope\	PHP source files	PSR-4 autoload root composer.json33
src/Watchers/	Hypervel\Telescope\Watchers\	18 watcher classes	Application monitoring implementations
src/Storage/	Hypervel\Telescope\Storage\	DatabaseEntriesRepository	Data persistence layer
src/Contracts/	Hypervel\Telescope\Contracts\	Repository interfaces	Storage abstraction contracts
src/Console/	Hypervel\Telescope\Console\	5 command classes	Console commands for management
src/Aspects/	Hypervel\Telescope\Aspects\	GuzzleHttpClientAspect	AOP method interception
public/	N/A	app.js, mix-manifest.json	Compiled frontend assets
resources/js/	N/A	Vue.js components	Frontend source code
database/migrations/	N/A	Migration files	Database schema definitions

Key Files by Namespace

File Path	Fully Qualified Class Name	Role
src/Telescope.php	Hypervel\Telescope\Telescope	Static facade for entry recording
src/TelescopeServiceProvider.php	Hypervel\Telescope\TelescopeServiceProvider	Framework integration and bootstrapping
src/ConfigProvider.php	Hypervel\Telescope\ConfigProvider	Hyperf DI container integration
src/IncomingEntry.php	Hypervel\Telescope\IncomingEntry	Entry data model during collection
src/EntryResult.php	Hypervel\Telescope\EntryResult	Entry data model after retrieval
src/ListensForStorageOpportunities.php	Hypervel\Telescope\ListensForStorageOpportunities	Trait for storage lifecycle management

Sources: composer.json31-34

---

Additional Metadata

Branch Aliasing and Stability

The package includes additional composer configuration composer.json37-52:

Branch Alias:

This maps the dev-main branch to version 0.3-dev, allowing composer require hypervel/telescope:0.3.x-dev to track the main branch.

Minimum Stability:

Allows installation of development versions of dependencies. This is set to "dev" composer.json52

Package Sorting:

Ensures dependencies are alphabetically sorted when running composer update composer.json50

Sources: composer.json37-52

---

Integration Summary Table

Integration Aspect	Mechanism	File Reference
Package Name	hypervel/telescope	composer.json2
Namespace	Hypervel\Telescope\	composer.json33
Autoloading	PSR-4 mapping to src/	composer.json31-34
Hyperf Integration	ConfigProvider via extra.hyperf.config	composer.json40-42
Hypervel Integration	TelescopeServiceProvider via extra.hypervel.providers	composer.json43-46
PHP Version	^8.2	composer.json23
Framework Version	Hyperf ~3.1.0	composer.json24-28
Core Dependency	Hypervel Core ^0.3	composer.json29

Sources: composer.json1-53