Application Container

Namespace: VelvetCMS\Core\Application

Definition #

class Application
{
    public function __construct(string $basePath);
    
    // Static instance management
    public static function setInstance(Application $app): void;
    public static function getInstance(): Application;
    public static function hasInstance(): bool;
    public static function clearInstance(): void;
    
    // Service registration
    public function bind(string $name, callable $factory): void;
    public function singleton(string $name, callable $factory): void;
    public function instance(string $name, mixed $instance): void;
    public function alias(string $key, string $alias): void;
    
    // Service resolution
    public function get(string $name): mixed;
    public function make(string $name): mixed;
    public function has(string $name): bool;
    
    // Provider management
    public function register(string|ServiceProvider $provider): ServiceProvider;
    public function boot(): void;
    
    // Path helpers
    public function basePath(string $path = ''): string;
    public function environment(): string;
    public function isDebug(): bool;
}

Methods #

bind() #

Register a factory that creates a new instance on each resolution.

public function bind(string $name, callable $factory): void

Example:

$app->bind('mailer', fn() => new Mailer(config('mail')));

// Each call creates a new instance
$mailer1 = $app->make('mailer');
$mailer2 = $app->make('mailer'); // Different instance

singleton() #

Register a factory that creates a single shared instance.

public function singleton(string $name, callable $factory): void

Example:

$app->singleton('cache', fn() => new FileCache([
    'path' => storage_path('cache'),
    'prefix' => 'velvet'
]));

// Always returns the same instance
$cache1 = $app->make('cache');
$cache2 = $app->make('cache'); // Same instance

instance() #

Register an existing object instance directly.

public function instance(string $name, mixed $instance): void

Example:

$config = new ConfigRepository();
$config->load(['app', 'database', 'cache']);

$app->instance('config', $config);

alias() #

Create an alias for an existing service binding.

public function alias(string $key, string $alias): void

Example:

$app->singleton('cache', fn() => new FileCache($config));
$app->alias('cache', CacheDriver::class);

// Both resolve to the same instance
$app->make('cache');
$app->make(CacheDriver::class);

make() #

Resolve a service by name or class. Supports autowiring for unbound classes.

public function make(string $name): mixed

Returns: The resolved service instance.

Throws: RuntimeException if service not found and cannot be autowired.

Example:

// Resolve bound service
$cache = $app->make('cache');

// Resolve by interface (via alias)
$cache = $app->make(CacheDriver::class);

// Autowire unbound class
$service = $app->make(MyService::class);

get() #

Resolve a service only if explicitly bound (no autowiring).

public function get(string $name): mixed

Throws: RuntimeException if service not found.

has() #

Check if a service is bound.

public function has(string $name): bool

Example:

if ($app->has('cache')) {
    $cache = $app->make('cache');
}

register() #

Register a service provider.

public function register(string|ServiceProvider $provider): ServiceProvider

Example:

// By class name
$app->register(DatabaseServiceProvider::class);

// By instance
$app->register(new MyCustomProvider($app));

boot() #

Boot the application and all registered providers.

public function boot(): void

Dispatches app.booting and app.booted events. Called automatically during HTTP request lifecycle.

basePath() #

Get the application base path.

public function basePath(string $path = ''): string

Example:

$app->basePath();           // /var/www/velvet
$app->basePath('config');   // /var/www/velvet/config

environment() #

Get the current environment name.

public function environment(): string

Returns: Environment from config('app.env'), defaults to 'production'.

isDebug() #

Check if debug mode is enabled.

public function isDebug(): bool

Returns: Debug status from config('app.debug').

Autowiring #

The container automatically resolves class dependencies when:

1. The class is not explicitly bound
2. The class is instantiable (not abstract/interface)
3. Constructor parameters have type hints or default values

class UserService
{
    public function __construct(
        private CacheDriver $cache,    // Resolved from container
        private int $ttl = 3600        // Uses default value
    ) {}
}

// Automatically injects CacheDriver
$service = $app->make(UserService::class);

Warning: Scalar parameters without defaults will throw a RuntimeException.

Static Access #

// Set the global instance (done in bootstrap)
Application::setInstance($app);

// Access from anywhere
$app = Application::getInstance();

// Check if set
if (Application::hasInstance()) {
    $app = Application::getInstance();
}

// Clear (for testing)
Application::clearInstance();

Magic Property Access #

Services can be accessed as properties:

$events = $app->events;  // Same as $app->get('events')
$cache = $app->cache;    // Same as $app->get('cache')

Helper Function #

The app() helper provides convenient access:

// Get application instance
$app = app();

// Resolve a service
$cache = app('cache');
$router = app('router');