 |
VOOZH | about |
|
VOOZH | about |
This document explains the bootstrap pipeline that initializes the Hypervel application, focusing on two critical bootstrappers: RegisterProviders and RegisterFacades. It covers how service providers are discovered from Composer packages and application configuration, how packages can be filtered from discovery, and how facades (class aliases) are registered to provide convenient static access to framework services.
For information about the Application container and its lifecycle, see Application Container and Dependency Injection. For details on the FoundationServiceProvider's role in establishing core services, see Foundation Service Provider. For configuration system details, see Configuration System and Config Provider.
The application bootstrap process consists of a sequence of bootstrappers that configure and initialize the framework. Two key bootstrappers in this sequence are responsible for service registration and facade setup:
| Bootstrapper | Purpose | Primary Responsibility |
|---|---|---|
RegisterProviders | Service Provider Registration | Discovers providers from Composer packages and configuration, filters based on dont-discover rules, registers them with the application container |
RegisterFacades | Facade/Alias Registration | Creates class aliases from Composer and configuration sources, enabling static facade access |
These bootstrappers are invoked during application initialization, before the application is fully booted. They populate the service container with providers and establish the facade system that developers use throughout the application.
Diagram: Bootstrap Pipeline and Bootstrapper Sequence
Sources: src/Bootstrap/RegisterProviders.php19-54 src/Bootstrap/RegisterFacades.php19-35
The RegisterProviders bootstrapper implements a sophisticated discovery mechanism that aggregates service providers from multiple sources and applies filtering rules before registering them with the application container.
The discovery process begins by examining Composer package metadata. Each installed package can declare service providers in its composer.json file under extra.hypervel.providers:
The RegisterProviders::bootstrap() method uses Composer::getMergedExtra() to aggregate all provider declarations across all installed packages. This returns an array where each key is a package name and each value contains the package's extra configuration.
Diagram: Provider Discovery Flow
Sources: src/Bootstrap/RegisterProviders.php25-28
The framework supports a dont-discover mechanism that allows packages and applications to exclude specific packages from automatic provider registration. This is useful when you want to manually register a provider or when a package's automatic registration conflicts with application requirements.
The filtering process aggregates dont-discover rules from two sources:
composer.json under extra.hypervel.dont-discovercomposer.json under extra.hypervel.dont-discoverThe special value ['*'] in the dont-discover array disables all automatic provider discovery from packages, requiring manual provider registration.
Code Mapping: dont-discover Implementation
| Method | Location | Responsibility |
|---|---|---|
packagesToIgnore() | src/Bootstrap/RegisterProviders.php56-67 | Aggregates dont-discover rules from packages and project |
| Provider filtering | src/Bootstrap/RegisterProviders.php24-35 | Checks each package against ignore list, excludes matching providers |
The filtering logic at src/Bootstrap/RegisterProviders.php29-33 uses array_filter() with ARRAY_FILTER_USE_KEY to exclude packages whose names appear in the packagesToIgnore() array.
Sources: src/Bootstrap/RegisterProviders.php22-35 src/Bootstrap/RegisterProviders.php56-67
In addition to Composer-based discovery, the application can explicitly declare providers in its configuration file. The config/app.php file (or its published equivalent) contains a providers array:
These configuration-based providers are merged with Composer-discovered providers at src/Bootstrap/RegisterProviders.php37-42 The array_unique() call ensures that if a provider appears in both Composer metadata and configuration, it's only registered once.
Sources: src/Bootstrap/RegisterProviders.php37-42
The FoundationServiceProvider is a critical infrastructure provider that must be registered before other providers to ensure core services are available. The RegisterProviders bootstrapper enforces this priority by searching for FoundationServiceProvider in the provider list and moving it to the first position if found:
This prioritization happens at src/Bootstrap/RegisterProviders.php44-49 after all providers have been discovered and deduplicated but before registration occurs.
Sources: src/Bootstrap/RegisterProviders.php44-49
After discovery, filtering, merging, and prioritization, the final provider list is registered with the application container. The registration loop at src/Bootstrap/RegisterProviders.php51-53 calls $app->register() for each provider class:
The register() method on the Application container instantiates the provider and calls its register() method, allowing it to bind services into the container. Provider booting occurs later in the application lifecycle.
Diagram: Complete Provider Registration Pipeline
Sources: src/Bootstrap/RegisterProviders.php19-54
The RegisterFacades bootstrapper establishes the facade system by creating class aliases that map short, convenient names to actual facade classes. This enables static access to framework services through a clean API.
Before registering any aliases, the bootstrapper clears all resolved facade instances by calling Facade::clearResolvedInstances() at src/Bootstrap/RegisterFacades.php21 This ensures that facades resolve fresh instances from the newly bootstrapped container, preventing stale references from previous bootstrap cycles (relevant in testing contexts or when refreshing the application).
Sources: src/Bootstrap/RegisterFacades.php21
Class aliases are aggregated from two sources, similar to provider discovery:
composer.json under extra.hypervel.aliasesconfig/app.php under the aliases keyThe bootstrapper attempts to load Composer aliases at src/Bootstrap/RegisterFacades.php24-28 wrapping the operation in a try-catch to gracefully handle missing configuration. Configuration aliases are loaded at src/Bootstrap/RegisterFacades.php30-31
The two sources are merged at src/Bootstrap/RegisterFacades.php32 with configuration aliases taking precedence if there are conflicts (since they appear later in the merge).
Example Configuration Structures:
Composer aliases (composer.json):
Configuration aliases (config/app.php):
Sources: src/Bootstrap/RegisterFacades.php23-32
The registerAliases() method at src/Bootstrap/RegisterFacades.php37-46 performs the actual alias registration using PHP's class_alias() function:
Key Implementation Details:
| Aspect | Implementation | Location |
|---|---|---|
| Pre-check | Skip if alias already exists as a class | src/Bootstrap/RegisterFacades.php40-42 |
| Registration | Use class_alias($class, $alias) | src/Bootstrap/RegisterFacades.php44 |
| Order | Process all Composer aliases, then all config aliases | src/Bootstrap/RegisterFacades.php32 |
The pre-check at src/Bootstrap/RegisterFacades.php40-42 prevents attempting to alias over existing classes, which would cause a fatal error. This allows the application to define custom implementations that take precedence over framework-provided facades.
Diagram: Facade Registration Flow
Sources: src/Bootstrap/RegisterFacades.php19-46
The bootstrap process integrates with the broader application lifecycle as follows:
RegisterProviders and RegisterFacades are invokedThe separation between provider registration (during bootstrap) and provider booting (after bootstrap) allows providers to assume that all services have been registered before any are booted, enabling proper dependency resolution.
Key Classes and Methods:
| Class | Method | Purpose |
|---|---|---|
RegisterProviders | bootstrap(ApplicationContract) | Discovers and registers service providers |
RegisterProviders | packagesToIgnore() | Determines which packages to exclude from discovery |
RegisterFacades | bootstrap(ApplicationContract) | Registers class aliases for facades |
RegisterFacades | registerAliases(array) | Creates individual class aliases using class_alias() |
Composer | getMergedExtra() | Aggregates extra configuration from all packages |
Composer | getJsonContent() | Retrieves root composer.json content |
Sources: src/Bootstrap/RegisterProviders.php14-68 src/Bootstrap/RegisterFacades.php14-47
Refresh this wiki