 |
VOOZH | about |
|
VOOZH | about |
The Foundation Layer provides the core bootstrapping and lifecycle management infrastructure for Hypervel applications. It establishes the dependency injection container, manages service provider registration and booting, provides application path helpers, and sets up enhanced debugging tools. This layer serves as the integration point between Hyperf's coroutine architecture and Laravel-style application development patterns.
This document covers the overall architecture and key components of the Foundation Layer. For detailed information about specific subsystems:
The Foundation Layer is centered around the Application class, which extends Hypervel's Container implementation and serves as the central registry for all framework services. The application instance manages the entire lifecycle from bootstrapping through service provider registration to final booting.
Sources: src/foundation/src/Application.php1-688 src/foundation/src/Contracts/Application.php1-207 src/foundation/src/Providers/FoundationServiceProvider.php1-202
The Application class is the framework's main entry point and container. It implements the ApplicationContract interface and provides:
| Responsibility | Methods | Description |
|---|---|---|
| Version Management | version() | Returns framework version (currently 0.3.18) |
| Path Management | basePath(), path(), configPath(), storagePath(), etc. | Provides standardized directory path helpers |
| Environment Detection | environment(), isLocal(), isProduction(), runningUnitTests(), hasDebugModeEnabled() | Determines runtime environment |
| Service Provider Management | register(), boot(), getProvider(), getProviders() | Manages service provider lifecycle |
| Bootstrapping | bootstrapWith(), hasBeenBootstrapped() | Coordinates bootstrap phases |
| Locale Management | getLocale(), setLocale(), getFallbackLocale() | Manages application internationalization |
The Application constructor initializes the base path, creates the definition source for dependency injection, registers base container bindings, and establishes core container aliases for over 50 framework interfaces.
Sources: src/foundation/src/Application.php25-688 src/foundation/src/Contracts/Application.php13-207
Sources: src/foundation/src/Application.php118-129 src/foundation/src/Application.php398-416
The Application class registers comprehensive container aliases in registerCoreContainerAliases(). This enables flexible service resolution through multiple interface and class names. The method maps canonical service names to their aliases:
This pattern is repeated for all major framework services including config, events, router, cache, auth, queue, and many others. The aliases enable developers to resolve services by interface, implementation, or shorthand name.
Sources: src/foundation/src/Application.php546-664
The Application class provides a comprehensive set of path helper methods that return standardized directory paths relative to the application's base path:
| Method | Default Path | Purpose |
|---|---|---|
basePath($path) | BASE_PATH | Root application directory |
path($path) | app/ | Application code directory |
configPath($path) | config/ | Configuration files |
databasePath($path) | database/ | Database migrations and seeds |
langPath($path) | lang/ | Translation files |
publicPath($path) | public/ | Web-accessible files |
resourcePath($path) | resources/ | Views, assets, raw files |
viewPath($path) | resources/views/ or configured | Blade template files |
storagePath($path) | storage/ | Generated files, logs, cache |
All paths are constructed using the joinPaths() helper which properly handles path separators across operating systems.
Sources: src/foundation/src/Application.php156-252 src/foundation/src/Contracts/Application.php35-87
The FoundationServiceProvider is automatically registered and bootstraps critical framework infrastructure:
Sources: src/foundation/src/Providers/FoundationServiceProvider.php33-202
The overrideHyperfConfigs() method bridges Hypervel's Laravel-style configuration with Hyperf's native configuration system. It maps configuration keys from Hypervel's config/app.php, config/database.php, and other files to Hyperf's expected configuration structure:
The Redis configuration receives special handling to merge connection-specific options with global Redis options. Middleware configurations are sorted using MiddlewareManager::sortMiddlewares() and merged with kernel-defined global middleware.
Sources: src/foundation/src/Providers/FoundationServiceProvider.php108-162
The FoundationServiceProvider registers a user resolver callback on the RequestContract after it's resolved from the container. This enables the $request->user() method to retrieve the authenticated user through the Auth system:
Sources: src/foundation/src/Providers/FoundationServiceProvider.php67-74
The Foundation Layer provides enhanced variable dumping capabilities through custom CliDumper and HtmlDumper implementations that extend Symfony's VarDumper component.
Both dumpers use the ResolvesDumpSource trait to automatically determine and display the file and line number where a dump() or dd() call originated. The trait:
Sources: src/foundation/src/Concerns/ResolvesDumpSource.php1-191
The resolveSourceHref() method supports multiple editor protocols for direct source navigation:
| Editor | Protocol Format |
|---|---|
| PHPStorm | phpstorm://open?file={file}&line={line} |
| VSCode | vscode://file/{file}:{line} |
| VSCode Remote | vscode://vscode-remote/{file}:{line} |
| Sublime Text | subl://open?url=file://{file}&line={line} |
| Atom | atom://core/open/file?filename={file}&line={line} |
| Cursor | cursor://file/{file}:{line} |
| Nova | nova://core/open/file?filename={file}&line={line} |
Configuration is read from config('app.editor') and supports both simple string names and complex configurations with custom hrefs and base path mappings for Docker environments.
Sources: src/foundation/src/Concerns/ResolvesDumpSource.php16-171
The CliDumper class outputs dumps to the console with ANSI color codes when supported. It registers custom casters to reduce noise from internal framework objects and appends source information as gray text:
"string value" // app/routes/web.php:42
For complex objects and arrays, the source appears on the last line with appropriate indentation.
Sources: src/foundation/src/Console/CliDumper.php1-104
The HtmlDumper class generates styled HTML output for web responses. It injects source information into Symfony's HTML dump structure by detecting and replacing specific separator strings:
class=sf-dump-expanded></pre><script>The source is rendered as gray text with optional clickable links for editor integration:
Sources: src/foundation/src/Http/HtmlDumper.php1-115
The FoundationServiceProvider registers the appropriate dumper based on the execution context:
The dumper also registers custom casters for common framework classes to prevent excessive internal detail in dumps:
ConnectionInterface → StubCaster::cutInternalsContainer → StubCaster::cutInternalsDispatcher → StubCaster::cutInternalsGrammar → StubCaster::cutInternalsSources: src/foundation/src/Providers/FoundationServiceProvider.php181-201
The Application class provides methods to detect the current runtime environment and application namespace:
Environment detection delegates to the Environment service, which reads from the APP_ENV environment variable:
Debug mode is determined by the APP_DEBUG environment variable parsed by the Environment service.
Sources: src/foundation/src/Application.php259-306
The getNamespace() method determines the application's root namespace by parsing composer.json and finding the PSR-4 autoload entry that maps to the app/ directory:
This enables dynamic namespace resolution for command generation and other tooling that needs to reference application classes.
Sources: src/foundation/src/Application.php671-687
While the full HTTP layer is documented in HTTP Layer, the Foundation Layer provides key integration points:
The RequestContract interface extends Hyperf's RequestInterface with Laravel-style convenience methods. The Foundation Service Provider registers a user resolver on each request instance to enable authentication integration.
Sources: src/http/src/Contracts/RequestContract.php1-442 src/foundation/src/Providers/FoundationServiceProvider.php67-74
The Application class provides an abort() method for throwing HTTP exceptions:
Sources: src/foundation/src/Application.php474-481
The application provides locale management methods that delegate to the translator service:
When setLocale() is called, it updates the translator and dispatches a LocaleUpdated event for observers.
Sources: src/foundation/src/Application.php503-541
The application maintains registries of all registered service providers and their loading status:
The getProvider() and getProviders() methods enable querying registered providers by class name or instance. The providerIsLoaded() method checks the loadedProviders array.
Refresh this wiki