Package Structure and Monorepo Organization

Purpose and Scope

This page documents the monorepo structure of the Hypervel components repository, explaining how 23+ packages are organized, versioned, and integrated into both Hyperf and Hypervel frameworks. It covers the directory layout, autoloading configuration, package naming conventions, and the dual integration pattern using ConfigProvider and ServiceProvider classes.

For information about how the Application bootstraps and loads these packages, see Application Container and Lifecycle. For Hyperf-specific integration details, see Hyperf Integration and Swoole Foundation.

---

Monorepo Overview

The Hypervel framework is distributed as a single monorepo at hypervel/components, containing 23+ modular packages that provide framework functionality. This architecture allows unified versioning, simplified dependency management, and coordinated releases while maintaining logical separation between components.

Monorepo Directory Structure

hypervel/components/
├── composer.json # Root monorepo manifest
├── src/
│ ├── api-client/ # HTTP API client utilities
│ ├── auth/ # Authentication system
│ ├── broadcasting/ # Real-time event broadcasting
│ ├── bus/ # Command bus and job dispatching
│ ├── cache/ # Multi-driver cache system
│ ├── config/ # Configuration management
│ ├── console/ # Console command infrastructure
│ ├── container/ # Dependency injection container
│ ├── cookie/ # Cookie handling
│ ├── core/ # Core framework classes
│ ├── coroutine/ # Coroutine utilities
│ ├── devtool/ # Development tooling
│ ├── dispatcher/ # Middleware dispatcher
│ ├── encryption/ # Encryption services
│ ├── event/ # Event system
│ ├── filesystem/ # Filesystem abstraction
│ ├── foundation/ # Application foundation
│ ├── hashing/ # Password hashing
│ ├── horizon/ # Queue monitoring (Horizon)
│ ├── http/ # HTTP request/response
│ ├── http-client/ # External HTTP client
│ ├── jwt/ # JSON Web Token support
│ ├── log/ # Logging system
│ ├── mail/ # Email sending
│ ├── nested-set/ # Nested set model pattern
│ ├── notifications/ # Multi-channel notifications
│ ├── object-pool/ # Object pooling
│ ├── permission/ # Permission management
│ ├── process/ # Process management
│ ├── prompts/ # Interactive CLI prompts
│ ├── queue/ # Queue and job system
│ ├── redis/ # Redis integration
│ ├── router/ # HTTP routing
│ ├── sanctum/ # API token authentication
│ ├── scout/ # Full-text search
│ ├── sentry/ # Sentry error tracking
│ ├── session/ # Session management
│ ├── socialite/ # OAuth provider integration
│ ├── support/ # Support utilities and helpers
│ ├── telescope/ # Debugging and monitoring
│ ├── testbench/ # Testing utilities
│ ├── translation/ # Internationalization
│ └── validation/ # Input validation
└── tests/ # Framework test suites

Sources: composer.json1-89

---

Unified Versioning Strategy

The monorepo uses a unified versioning strategy where all packages share the same version number. This is declared in the replace section of the root composer.json, which tells Composer that installing hypervel/components provides all individual packages.

Replace Section Configuration

Package Name	Version Strategy
hypervel/foundation	self.version
hypervel/router	self.version
hypervel/cache	self.version
hypervel/auth	self.version
hypervel/queue	self.version
(all 23+ packages)	self.version

The self.version placeholder indicates that each package version matches the monorepo version. The branch alias "dev-main": "0.3-dev" maps the main branch to the 0.3 development version.

Sources: composer.json145-188 composer.json280-282

---

PSR-4 Autoloading Structure

Namespace to Directory Mapping

The monorepo configures PSR-4 autoloading to map each package's namespace to its source directory:

Autoloading Pattern

Each package follows a consistent directory structure:

src/{package-name}/
├── composer.json # Package-specific manifest
├── src/ # Source code directory
│ ├── ConfigProvider.php # Hyperf integration
│ ├── {Classes}.php # Package classes
│ └── Functions.php # Global helper functions (optional)
└── tests/ # Package-specific tests (in monorepo)

The PSR-4 mapping "Hypervel\\PackageName\\": "src/package-name/src/" ensures that:

• Hypervel\PackageName\ClassName resolves to src/package-name/src/ClassName.php
• Nested namespaces follow subdirectories: Hypervel\PackageName\Sub\Class → src/package-name/src/Sub/Class.php

Sources: composer.json24-71

---

Helper Functions Autoloading

Many packages provide global helper functions that are auto-loaded via the files section:

These files contain functions like app(), config(), cache(), auth(), route(), session(), event(), and trans() that provide convenient access to framework services without requiring explicit container resolution.

Sources: composer.json72-88

---

Dual Integration Pattern

ConfigProvider Pattern (Hyperf Integration)

Each package registers a ConfigProvider class in the root composer.json extra section. This integrates with Hyperf's dependency injection and service discovery system:

ConfigProvider Responsibilities:

Responsibility	Description
Dependency Definitions	Binds interfaces to implementations in Hyperf's DI container
Aspect Registration	Registers AOP aspects for cross-cutting concerns
Command Registration	Declares console commands for discovery
Listener Registration	Registers event listeners with Hyperf's event system
Middleware Registration	Defines HTTP middleware for server processing

Sources: composer.json239-270

ServiceProvider Pattern (Hypervel Integration)

Some packages also register ServiceProvider classes for Laravel-style bootstrapping:

ServiceProviders provide:

• Two-phase lifecycle (register + boot)
• Access to Laravel-style service registration APIs
• Integration with Hypervel's Application container
• Deferred loading capabilities

Sources: composer.json272-279

---

Integration Pattern Architecture

ConfigProvider Flow:

1. Hyperf scans extra.hyperf.config in all installed packages
2. Instantiates each ConfigProvider class
3. Merges configuration via __invoke() method
4. Registers dependencies, aspects, listeners, and commands

ServiceProvider Flow:

1. Application reads extra.hypervel.providers from package manifests
2. Instantiates ServiceProvider instances
3. Calls register() method on all providers (registration phase)
4. Calls boot() method on all providers (boot phase)

Sources: src/foundation/composer.json60-72 composer.json239-279

---

Package Dependency Graph

Packages within the monorepo have interdependencies. Core packages are foundational, while feature packages depend on them:

Core Dependencies:

Package	Key Dependencies (within monorepo)
hypervel/support	(none - foundational)
hypervel/core	(none - foundational)
hypervel/foundation	core, support, http, validation, filesystem
hypervel/auth	hashing, jwt
hypervel/cache	(minimal dependencies)
hypervel/queue	core, support, encryption
hypervel/notifications	broadcasting, mail, queue, support, object-pool

Sources: src/foundation/composer.json22-47 src/auth/composer.json22-34 src/queue/composer.json22-37 src/notifications/composer.json28-42

---

Individual Package Structure

Package Composer Manifest Pattern

Each package has its own composer.json following this template:

Key Elements:

Field	Purpose
name	Package identifier for Composer
require	Lists Hyperf dependencies (~3.1.0) and other Hypervel packages (^0.3)
autoload.psr-4	Maps namespace to local src/ directory
autoload.files	Optional helper functions file
extra.hyperf.config	ConfigProvider class for Hyperf integration
extra.hypervel.providers	Optional ServiceProvider classes
branch-alias	Maps branch to development version

Sources: src/foundation/composer.json1-77 src/router/composer.json1-54 src/cache/composer.json1-53

---

ConfigProvider Implementation Pattern

Each package's ConfigProvider class follows this structure:

src/package-name/src/ConfigProvider.php

Typical ConfigProvider responsibilities:

Example from authentication package:

Sources: Based on pattern visible in src/auth/composer.json46-53 src/router/composer.json46-53 src/cache/composer.json45-52

---

ServiceProvider Implementation Pattern

ServiceProviders are optional and used for Laravel-style integration:

src/package-name/src/PackageNameServiceProvider.php

Lifecycle methods:

Method	Phase	Purpose
register()	Registration	Bind services to container
boot()	Boot	Configure services, register routes, publish assets

Packages with ServiceProviders:

Only packages requiring Laravel-specific bootstrapping (beyond Hyperf's DI) use ServiceProviders. Most packages only need ConfigProviders.

Sources: composer.json272-279 src/telescope/composer.json43-47 src/notifications/composer.json50-54

---

Package Categories and Responsibilities

Core Infrastructure

Package	Responsibility
hypervel/core	Base application classes, contracts
hypervel/support	Collections, utilities, helper functions
hypervel/container	Dependency injection container extensions
hypervel/foundation	Application bootstrap, service providers

HTTP Layer

Package	Responsibility
hypervel/http	Request/response objects, middleware
hypervel/router	Route registration, dispatching, URL generation
hypervel/http-client	External HTTP requests, testing fakes
hypervel/session	Session management, drivers
hypervel/cookie	Cookie handling utilities

Data & Persistence

Package	Responsibility
hypervel/cache	Multi-driver caching, rate limiting, locks
hypervel/queue	Job queue, queue drivers, job dispatching
hypervel/redis	Redis client integration

Authentication & Security

Package	Responsibility
hypervel/auth	Authentication guards, user providers
hypervel/hashing	Password hashing algorithms
hypervel/jwt	JWT token generation and validation
hypervel/sanctum	API token authentication
hypervel/encryption	Data encryption/decryption
hypervel/permission	Role and permission management

Communication

Package	Responsibility
hypervel/broadcasting	WebSocket event broadcasting
hypervel/notifications	Multi-channel notifications
hypervel/mail	Email sending, mailable classes

Developer Tools

Package	Responsibility
hypervel/console	Console command infrastructure
hypervel/devtool	Code generation, scaffolding
hypervel/telescope	Debugging and monitoring
hypervel/testbench	Testing utilities
hypervel/sentry	Error tracking integration

Feature Packages

Package	Responsibility
hypervel/scout	Full-text search integration
hypervel/socialite	OAuth authentication
hypervel/horizon	Queue monitoring dashboard
hypervel/filesystem	File storage abstraction
hypervel/translation	Internationalization
hypervel/validation	Input validation

Sources: composer.json24-71 composer.json145-188

---

Package Discovery and Loading

Composer Autoload Generation

When composer install or composer dump-autoload runs:

1. PSR-4 Mapping: Composer generates vendor/autoload.php with PSR-4 namespace mappings
2. Files Loading: All files from autoload.files are included in vendor/composer/autoload_files.php
3. Class Map: Class locations are cached in vendor/composer/autoload_classmap.php

Hyperf ConfigProvider Discovery

Hyperf's config scanner:

1. Scans all installed packages for extra.hyperf.config entries
2. Loads each ConfigProvider class
3. Invokes __invoke() method
4. Merges returned configuration into application config

Hypervel ServiceProvider Discovery

The Application class:

1. Reads extra.hypervel.providers from all package manifests
2. Instantiates each ServiceProvider
3. Executes registration phase (register() on all providers)
4. Executes boot phase (boot() on all providers)

Sources: Based on patterns in composer.json239-279 src/foundation/composer.json60-72

---

Summary

The Hypervel monorepo provides a clean, modular architecture:

• Single Repository: All 23+ packages in one repository for coordinated development
• Unified Versioning: All packages share version numbers via replace declarations
• PSR-4 Autoloading: Consistent namespace-to-directory mapping pattern
• Helper Functions: Global helper files auto-loaded via files section
• Dual Integration: ConfigProvider for Hyperf + ServiceProvider for Hypervel
• Package Independence: Each package has its own composer.json with dependencies
• Hierarchical Dependencies: Core packages support feature packages

This structure enables Laravel-style developer experience while maintaining compatibility with Hyperf's coroutine-based runtime and dependency injection system.