Configuration and Bootstrapping

Purpose and Scope

This document explains how the Hypervel Foundation application initializes and configures itself during startup. The bootstrap process encompasses configuration loading from multiple sources, automatic discovery and registration of service providers from Composer packages, facade alias registration, and integration with Hyperf's configuration system.

The bootstrap pipeline establishes the foundational infrastructure that all other framework components depend on. This page provides an overview of the entire initialization sequence. For detailed information about specific aspects:

• For the ConfigProvider class and Hyperf integration points, see Configuration System and Config Provider
• For service provider discovery mechanisms and registration logic, see Bootstrap Process and Service Registration
• For the FoundationServiceProvider and its core service setup, see Foundation Service Provider
• For information about the application container itself, see Application Container and Dependency Injection

---

Bootstrap Pipeline Overview

The bootstrap process follows a defined sequence of operations that transform a raw application container into a fully initialized framework instance. The pipeline consists of distinct phases, each responsible for a specific aspect of initialization.

Bootstrap Pipeline Sequence

Sources: src/Bootstrap/RegisterProviders.php19-54 src/Bootstrap/RegisterFacades.php19-35 src/ConfigProvider.php20-46

---

Configuration Sources

The application aggregates configuration from multiple sources, allowing both package authors and application developers to influence application behavior.

Configuration Source Hierarchy

Sources: src/Bootstrap/RegisterProviders.php22-42 src/Bootstrap/RegisterFacades.php23-32

Configuration Precedence

Source	Priority	Use Case
config/autoload/app.php	Highest	Application-specific overrides
Project composer.json extra.hypervel	High	Project-level package configuration
Package composer.json extra.hypervel	Medium	Package-provided defaults
Hyperf Configuration System	Base	Framework defaults

---

Service Provider Discovery

The RegisterProviders bootstrap class discovers service providers from Composer packages and application configuration, then registers them with the container.

Discovery Process

Service Provider Discovery Flow

Sources: src/Bootstrap/RegisterProviders.php19-54

Provider Discovery Logic

The discovery process extracts providers from the extra.hypervel.providers key in each Composer package's metadata:

Key Discovery Behaviors:

Behavior	Implementation
Package Scanning	Uses Composer::getMergedExtra() to read all composer.json files
Provider Extraction	Reads extra.hypervel.providers arrays from packages
Filtering	Excludes packages listed in dont-discover configuration
Wildcard Support	If dont-discover contains '*', skips package discovery entirely
Config Merging	Merges package providers with config('app.providers')
Deduplication	Uses array_unique() to remove duplicate provider classes

Sources: src/Bootstrap/RegisterProviders.php24-42

dont-discover Filtering

Applications can exclude packages from automatic provider discovery using the dont-discover configuration:

The filtering mechanism combines package-level and project-level exclusions:

Sources: src/Bootstrap/RegisterProviders.php56-67

FoundationServiceProvider Priority

The FoundationServiceProvider is always registered first, regardless of discovery order, to ensure core infrastructure is available to all other providers:

Sources: src/Bootstrap/RegisterProviders.php44-49

---

Facade Registration

The RegisterFacades bootstrap class creates class aliases that enable static access to framework services through facade classes.

Facade Registration Process

Sources: src/Bootstrap/RegisterFacades.php19-46

Alias Sources

Facades can be defined in two locations:

1. Composer metadata - extra.hypervel.aliases in any composer.json
2. Application configuration - config('app.aliases') array

The registration process merges aliases from both sources, with application configuration taking precedence for duplicate keys.

Alias Registration Safety

The system prevents redefinition of existing classes:

Sources: src/Bootstrap/RegisterFacades.php37-46

---

Hyperf Integration via ConfigProvider

The ConfigProvider class serves as the primary integration point between Hypervel Foundation and the Hyperf framework. It defines dependencies, listeners, commands, and publishable assets that Hyperf's configuration system will automatically discover.

ConfigProvider Structure

Sources: src/ConfigProvider.php20-46

Configuration Keys

Key	Purpose	Example Entries
dependencies	Dependency injection bindings	ApplicationInterface::class => ApplicationFactory::class
listeners	Event listeners to register	ErrorExceptionHandler::class, ReloadDotenvAndConfig::class
commands	Console commands to register	AboutCommand::class, ServerReloadCommand::class
publish	Publishable configuration files	app.php configuration template

Dependency Bindings

The ConfigProvider overrides default Hyperf bindings with Hypervel-specific implementations:

Sources: src/ConfigProvider.php23-26

Registered Listeners

Two critical event listeners are registered automatically:

1. ErrorExceptionHandler - Converts PHP errors to exceptions
2. ReloadDotenvAndConfig - Reloads environment and configuration on server reload

Sources: src/ConfigProvider.php27-30

Registered Commands

Four foundation commands are registered for console usage:

Command Class	Signature	Purpose
AboutCommand	about	Display application information
ConfigShowCommand	config:show	Display configuration values
ServerReloadCommand	server:reload	Gracefully reload workers
VendorPublishCommand	vendor:publish	Publish package assets

Sources: src/ConfigProvider.php31-36 src/Console/Commands/ServerReloadCommand.php16-18

Publishable Assets

The ConfigProvider defines assets that can be published to the application using vendor:publish:

Sources: src/ConfigProvider.php37-44

---

Complete Bootstrap Sequence

The following diagram shows the complete initialization sequence from application instantiation to ready state, including all bootstrap classes and their interactions.

Complete Bootstrap Execution Flow

Sources: src/ConfigProvider.php20-46 src/Bootstrap/RegisterProviders.php19-54 src/Bootstrap/RegisterFacades.php19-46

Bootstrap Phase Summary

Phase	Class	Key Operations
Configuration	ConfigProvider	Define dependencies, listeners, commands, publishable assets
Provider Discovery	RegisterProviders	Discover from Composer, filter, merge with config, prioritize Foundation
Provider Registration	RegisterProviders	Call app->register() for each provider
Facade Setup	RegisterFacades	Create class aliases for static facade access
Provider Boot	Application	Call boot() on all registered providers

---

Bootstrap Class Reference

RegisterProviders

Location: src/Bootstrap/RegisterProviders.php14-68

Primary Method: bootstrap(ApplicationContract $app): void

Responsibilities:

• Discover service providers from Composer package metadata
• Load service providers from application configuration
• Filter packages using dont-discover rules
• Ensure FoundationServiceProvider is registered first
• Register all discovered providers with the application container

Helper Method: packagesToIgnore(): array

Aggregates dont-discover rules from all Composer packages and the project configuration.

RegisterFacades

Location: src/Bootstrap/RegisterFacades.php14-47

Primary Method: bootstrap(ApplicationContract $app): void

Responsibilities:

• Clear previously resolved facade instances
• Load facade aliases from Composer packages
• Load facade aliases from application configuration
• Merge alias arrays with application config taking precedence
• Create PHP class aliases using class_alias()

Helper Method: registerAliases(array $aliases): void

Creates class aliases while preventing redefinition of existing classes.

ConfigProvider

Location: src/ConfigProvider.php18-47

Primary Method: __invoke(): array

Responsibilities:

• Define dependency injection bindings for Hyperf
• Register event listeners for framework events
• Register console commands
• Define publishable configuration assets

Returns: Configuration array consumed by Hyperf's configuration system

---

Configuration File Structure

The published app.php configuration file (from publish/app.php) defines application-level settings that control the bootstrap process:

Expected Configuration Keys

Configuration Key	Type	Purpose
app.providers	array	List of service provider class names to register
app.aliases	array	Associative array of facade aliases (alias => class)
app.dont_discover	array	Package names to exclude from auto-discovery

These configuration values are merged with Composer-defined values during the bootstrap process, with configuration file values taking precedence.

Sources: src/ConfigProvider.php37-44 src/Bootstrap/RegisterProviders.php39-42 src/Bootstrap/RegisterFacades.php30-32

---

Bootstrap Extension Points

Developers can extend the bootstrap process through several mechanisms:

Custom Service Providers

Create service providers and register them in config/autoload/app.php:

Package-Level Providers

Package authors can auto-register providers via composer.json:

Custom Facades

Register custom facade aliases in configuration:

Bootstrap Disabling

Disable auto-discovery of specific packages:

Sources: src/Bootstrap/RegisterProviders.php39-42 src/Bootstrap/RegisterFacades.php30-34 src/Bootstrap/RegisterProviders.php56-67