Last indexed: 14 February 2026 (fb2a0f)

Core Architecture

Purpose and Scope

This document provides a comprehensive overview of the foundational architectural patterns that power the hypervel/support package. It explains the layered structure, core design patterns, and how these components interact to create a cohesive framework. For detailed documentation of specific patterns:

For facade implementation details, see Facade System
For service provider lifecycle and extension points, see Service Provider System
For driver-based service management, see Manager Pattern
For auto-casting DTOs, see Data Object System

Architectural Layers

The hypervel/support package follows a multi-layered architecture where each layer has distinct responsibilities. The layers are designed to provide progressive levels of abstraction from low-level infrastructure to high-level application APIs.

Layer Structure

Sources: src/Facades/Facade.php1-264 src/ServiceProvider.php1-339 src/Manager.php1-157 src/DataObject.php1-588

Layer Responsibilities

Layer	Purpose	Key Classes	Primary Interactions
Application Layer	Business logic and controllers	User-defined classes	Calls facades, uses data objects
Static API Layer	Convenient static access to services	`Facade` subclasses in `src/Facades/`	Resolves from container
Pattern Implementation	Reusable architectural patterns	`ServiceProvider`, `Manager`, `DataObject`, `Reflector`	Manages lifecycle, creates drivers, casts data
Service Container	Dependency injection and resolution	`ApplicationContext`	Binds and resolves services
Concrete Implementation	Actual service implementations	Framework-specific classes	Implements business capabilities

Sources: src/Facades/Facade.php1-264 src/ServiceProvider.php1-339 src/Manager.php1-157 src/DataObject.php1-588

Core Patterns Overview

The support package implements four primary architectural patterns that form the foundation of the framework.

Pattern Summary

Sources: src/Facades/Facade.php144-192 src/ServiceProvider.php54-174 src/Manager.php49-104 src/DataObject.php62-569

Facade Pattern

The Facade class provides static access to services registered in the container. Each facade subclass implements getFacadeAccessor() to specify which service to resolve.

Key Methods:

getFacadeAccessor() - Returns the container binding key src/Facades/Facade.php260-263
getFacadeRoot() - Resolves and returns the actual service instance src/Facades/Facade.php169-172
__callStatic() - Forwards static calls to the resolved instance src/Facades/Facade.php144-153
swap() - Replaces the resolved instance (useful for testing) src/Facades/Facade.php131-136

Sources: src/Facades/Facade.php15-264

ServiceProvider Pattern

The ServiceProvider abstract class enables packages to register services, load resources, and publish assets. Providers follow a two-phase lifecycle: register() for binding services, then boot() for initialization after all services are registered.

Key Methods:

register() - Bind services to the container src/ServiceProvider.php54-56
boot() - Initialize services after registration (implicit)
loadRoutesFrom() - Register route files src/ServiceProvider.php109-113
loadViewsFrom() - Register view namespaces src/ServiceProvider.php118-130
loadTranslationsFrom() - Register translation namespaces src/ServiceProvider.php147-152
publishes() - Define publishable assets src/ServiceProvider.php206-215

Sources: src/ServiceProvider.php17-339

Manager Pattern

The Manager abstract class provides a driver-based architecture for services that support multiple implementations (e.g., cache drivers, queue drivers). Drivers are created lazily and cached.

Key Methods:

driver() - Get or create a driver instance src/Manager.php49-61
createDriver() - Factory method for driver creation src/Manager.php68-84
extend() - Register custom driver creators src/Manager.php99-104
getDefaultDriver() - Must be implemented by subclasses src/Manager.php42

Sources: src/Manager.php13-157

DataObject Pattern

The DataObject abstract class provides auto-casting DTOs with property mapping, type conversion, and dependency resolution. It uses reflection to determine constructor parameters and automatically converts data arrays to strongly-typed objects.

Key Methods:

make() / from() - Create instance from array src/DataObject.php62-102
convertValueToType() - Cast values to parameter types src/DataObject.php411-432
toArray() - Convert object back to array src/DataObject.php544-569
resolveDependenciesMap() - Build dependency tree for nested objects src/DataObject.php254-313

Sources: src/DataObject.php22-588

Pattern Interaction

The architectural patterns work together to create a cohesive system. This section illustrates how the patterns interact during common operations.

Design Principles

The architecture embodies several key design principles that guide implementation decisions throughout the package.

Separation of Concerns

Each architectural pattern has a single, well-defined responsibility:

Pattern	Primary Concern	Secondary Concerns
Facade	Static API surface	Service resolution, testing support
ServiceProvider	Service registration	Resource loading, asset publishing
Manager	Driver management	Lazy instantiation, extensibility
DataObject	Data transformation	Type safety, serialization

Sources: src/Facades/Facade.php1-264 src/ServiceProvider.php1-339 src/Manager.php1-157 src/DataObject.php1-588

Lazy Initialization

Services and drivers are created only when first accessed, minimizing overhead:

Facades resolve services on first call via resolveFacadeInstance() src/Facades/Facade.php177-192
Managers cache drivers after first creation via driver() src/Manager.php49-61
DataObjects cache array representation via toArray() src/DataObject.php544-569

Extensibility

Multiple extension points allow customization without modifying core code:

ServiceProviders via register() and boot() methods src/ServiceProvider.php54-56
Managers via extend() for custom drivers src/Manager.php99-104
DataObjects via getCustomizedDependencies() src/DataObject.php109-118
Facades via swap() for test doubles src/Facades/Facade.php131-136

Sources: src/ServiceProvider.php54-56 src/Manager.php99-104 src/DataObject.php109-118 src/Facades/Facade.php131-136

Convention Over Configuration

The architecture uses sensible defaults that can be overridden:

Property Mapping: camelCase properties automatically map to snake_case array keys src/DataObject.php376-388
Driver Creation: Follows create{Driver}Driver() naming convention src/Manager.php77
Auto-Casting: Enabled by default, convertible via $autoCasting flag src/DataObject.php42-370

Sources: src/DataObject.php42-388 src/Manager.php77

Reflection-Based Automation

The Reflector utility class provides type introspection capabilities used throughout the architecture:

Parameter Type Detection: getParameterClassName() and getParameterClassNames() extract type information src/Reflector.php62-97
Callable Validation: isCallable() provides PHP 7.4 compatible callable checking src/Reflector.php18-55
Type Resolution: getTypeName() resolves self and parent references src/Reflector.php105-120

These methods enable DataObject to perform automatic type casting src/DataObject.php411-432 and dependency resolution src/DataObject.php254-313 without explicit configuration.

Sources: src/Reflector.php14-136 src/DataObject.php254-432