Application Core

The Application Core is the central orchestration point of the Hypervel Foundation framework. The Application class (src/Application.php25) extends the dependency injection container and implements the framework's application contract. It manages the entire application lifecycle, including service provider registration, bootstrapping, environment detection, path resolution, and internationalization.

This document provides a high-level overview of the Application class and its core responsibilities. For detailed information about specific aspects:

• For dependency injection mechanics and service resolution, see Application Container and Dependency Injection
• For service provider registration and lifecycle callbacks, see Service Providers and Application Lifecycle
• For path management and environment detection details, see Application Paths and Environment Detection
• For convenient static access to application services, see Global Helper Functions
• For bootstrap pipeline mechanics, see Bootstrap Process and Service Registration

---

Application Class Structure

The Application class is the primary system in Hypervel Foundation, serving as both a dependency injection container and the central coordination point for all framework services.

Application Class Architecture

Sources: src/Application.php25-88 src/Contracts/Application.php13

---

Key Responsibilities

The Application class consolidates multiple framework concerns into a single, cohesive interface:

Responsibility	Methods	Description
Version Management	version()	Returns framework version (currently "0.3.18")
Container Operations	bind(), make(), get(), singleton()	Inherited from Container base class
Bootstrap Management	bootstrapWith(), hasBeenBootstrapped()	Executes bootstrap classes with event dispatching
Service Provider Management	register(), getProvider(), resolveProvider()	Registers and tracks service providers
Boot Lifecycle	boot(), isBooted(), booting(), booted()	Manages provider booting and callbacks
Path Resolution	basePath(), path(), configPath(), databasePath(), langPath(), publicPath(), resourcePath(), viewPath(), storagePath()	Resolves application directory paths
Environment Detection	environment(), isLocal(), isProduction(), detectEnvironment(), runningUnitTests(), hasDebugModeEnabled()	Determines execution environment
Internationalization	getLocale(), setLocale(), getFallbackLocale(), isLocale(), currentLocale()	Manages application locale
Namespace Detection	getNamespace()	Discovers app namespace from composer.json
HTTP Utilities	abort()	Throws HTTP exceptions

Sources: src/Application.php100-688 src/Contracts/Application.php15-207

---

Initialization and Core Bindings

Application Initialization Flow

The Application constructor (src/Application.php82-90) performs essential initialization:

1. Base Path Configuration: Sets the root installation directory (defaults to BASE_PATH constant)
2. Definition Source: Creates a DefinitionSourceFactory for dependency injection metadata
3. Container Initialization: Calls parent Container constructor with the definition source
4. Base Bindings: Registers ContainerInterface to resolve to the application instance itself
5. Core Aliases: Registers 60+ container aliases for convenient service access

Sources: src/Application.php82-112

---

Container Aliases Mapping

The Application registers extensive container aliases to provide multiple access patterns for the same service. This allows developers to reference services by interface, concrete class, or convenient short names.

Core Container Aliases (Excerpt)

Primary Binding	Aliases	Purpose
ContainerInterface	app, Container, Application	Application/Container access
Console\Contracts\Kernel	artisan	Console kernel
ConfigInterface	config, Config\Contracts\Repository	Configuration
EventDispatcherInterface	events, Event\Contracts\Dispatcher	Event system
DispatcherFactory	router	HTTP router
LoggerInterface	log, LogManager	Logging
Encrypter	encrypter	Encryption
Cache\Contracts\Factory	cache, CacheManager	Cache manager
Cache\Contracts\Store	cache.store, Repository	Cache store
Filesystem	files	File operations
ServerRequestInterface	request, RequestInterface	HTTP request
ResponseContract	response, ResponseInterface	HTTP response
Db	db	Database
Auth\Contracts\Factory	auth, AuthManager	Authentication
Hasher	hash	Password hashing
CookieManager	cookie	Cookie management
Redis	redis	Redis client
Router	router	Route registration
UrlGenerator	url	URL generation
FactoryInterface	view	View rendering
Session\Contracts\Factory	session, SessionManager	Session management
Mail\Contracts\Factory	mail.manager, MailManager	Mail manager
Queue\Contracts\Factory	queue, QueueManager	Queue manager
Validation\Contracts\Factory	validator	Validation

The complete alias registration occurs in src/Application.php546-664 These aliases enable multiple resolution patterns:

Sources: src/Application.php546-664

---

Application Lifecycle States

Lifecycle State Transitions

The Application maintains three key lifecycle state flags:

1. hasBeenBootstrapped (src/Application.php44): Set to true after bootstrapWith() completes. Indicates configuration loading and provider registration have occurred.

2. booted (src/Application.php49): Set to true after boot() completes. Indicates all service providers have been booted and the application is ready to handle requests.

3. Service Provider Tracking: The serviceProviders and loadedProviders arrays (src/Application.php68-75) track which providers have been registered.

Sources: src/Application.php44-76 src/Application.php118-153 src/Application.php398-416

---

Bootstrap Pipeline Integration

The Application supports a formal bootstrap pipeline through the bootstrapWith() method:

Bootstrap Execution Flow

The bootstrapWith() method (src/Application.php118-129):

• Marks the application as bootstrapped
• Dispatches bootstrapping: ClassName event before each bootstrapper
• Resolves the bootstrapper from the container and calls bootstrap($app)
• Dispatches bootstrapped: ClassName event after each bootstrapper

Developers can hook into the bootstrap process using beforeBootstrapping() and afterBootstrapping() (src/Application.php134-145).

Sources: src/Application.php118-153

---

Service Provider Registration

Service Provider Registration Flow

The register() method (src/Application.php311-345) handles provider registration:

1. Duplicate Check: Returns existing provider unless $force = true
2. Provider Resolution: If passed as string, instantiates via resolveProvider()
3. Registration: Calls provider's register() method
4. Property Bindings: Automatically binds any $bindings property
5. Tracking: Stores provider in serviceProviders and loadedProviders arrays
6. Late Booting: If application already booted, immediately boots the provider

Sources: src/Application.php311-385

---

Boot Process

Provider Boot Sequence

The boot() method (src/Application.php398-416) orchestrates provider booting:

1. Skip if Booted: Returns immediately if already booted
2. Pre-Boot Callbacks: Fires all registered bootingCallbacks
3. Provider Booting: Calls bootProvider() for each registered provider
4. Mark Complete: Sets booted = true
5. Post-Boot Callbacks: Fires all registered bootedCallbacks

The bootProvider() method (src/Application.php421-430) for each provider:

• Calls provider's booting callbacks
• Invokes provider's boot() method with dependency injection
• Calls provider's booted callbacks

Developers can register callbacks with booting() and booted() (src/Application.php435-450).

Sources: src/Application.php398-450

---

Path Resolution System

The Application provides a comprehensive set of path resolution methods that construct absolute paths relative to the base installation directory.

Application Path Methods

Path Method Reference

Method	Default Path	Configurable	Notes
basePath(string $path = '')	Base installation directory	No	Set via constructor or setBasePath()
path(string $path = '')	{base}/app	No	Application source code
configPath(string $path = '')	{base}/config	No	Configuration files
databasePath(string $path = '')	{base}/database	No	Migrations, seeds, factories
langPath(string $path = '')	{base}/lang	No	Translation files
publicPath(string $path = '')	{base}/public	No	Public web assets
resourcePath(string $path = '')	{base}/resources	No	Views, assets
viewPath(string $path = '')	Config: view.config.view_path or {base}/resources/views	Yes	View templates
storagePath(string $path = '')	{base}/storage	No	Logs, cache, sessions

All path methods use joinPaths() (src/Application.php249-252) internally, which delegates to the join_paths() helper function for cross-platform path concatenation.

The viewPath() method (src/Application.php228-236) is unique in that it respects the view.config.view_path configuration value, allowing the view directory to be customized.

Sources: src/Application.php160-252 src/Contracts/Application.php36-87

---

Environment Detection

The Application delegates environment detection to the Environment service, providing convenient wrapper methods:

Environment Detection Methods

Method	Return Type	Purpose
environment(...$environments)	bool|string	Check if environment matches any given value, or return current environment
detectEnvironment()	string	Get current environment name (e.g., "production", "local", "testing")
isLocal()	bool	Check if environment is "local"
isProduction()	bool	Check if environment is "production"
runningUnitTests()	bool	Check if environment is "testing"
hasDebugModeEnabled()	bool	Check if debug mode is enabled

Usage patterns:

All methods delegate to $this->get(Environment::class) (src/Application.php259-306).

Sources: src/Application.php259-306 src/Contracts/Application.php90-119

---

Locale Management

The Application provides internationalization support through locale management methods:

Locale Methods

Method	Purpose
getLocale()	Get current application locale from translator
currentLocale()	Alias for getLocale()
isLocale(string $locale)	Check if current locale matches given value
getFallbackLocale()	Get fallback locale from translator
setLocale(string $locale)	Set application locale and dispatch LocaleUpdated event

When setLocale() is called (src/Application.php536-541):

1. Updates the translator's locale
2. Dispatches a LocaleUpdated event (src/Events/LocaleUpdated.php7) with the new locale

This allows other parts of the application to react to locale changes through event listeners.

Sources: src/Application.php504-541 src/Events/LocaleUpdated.php1-15 src/Contracts/Application.php177-199

---

Namespace Detection

The getNamespace() method (src/Application.php671-687) dynamically detects the application's root namespace by parsing composer.json:

Namespace Detection Algorithm

The method:

1. Checks if namespace already cached in $this->namespace property
2. Reads and parses composer.json from base path
3. Iterates PSR-4 autoload mappings
4. Finds namespace where path matches $this->path() (the app directory)
5. Caches and returns the namespace
6. Throws RuntimeException if no match found

Sources: src/Application.php671-687 src/Contracts/Application.php201-206

---

HTTP Exception Utilities

The abort() method (src/Application.php474-481) provides a convenient way to throw HTTP exceptions:

The method automatically selects the appropriate exception type:

• 404 status code → NotFoundHttpException
• All other codes → HttpException

Both exception types are from the Hypervel\HttpMessage\Exceptions namespace.

Sources: src/Application.php474-481 src/Contracts/Application.php157-162

---

Version Management

The Application class defines a constant for the framework version:

This version is accessible via the version() method (src/Application.php100-103), which returns the string representation of the current Hypervel Foundation version.

Sources: src/Application.php34 src/Application.php100-103 src/Contracts/Application.php16-18