PHP Luminova: Application Service Kernel

The Service Kernel is responsible for bootstrapping core services in a Luminova application.

It does not handle requests, routing, middleware, or application flow.Its only responsibility is to define which core services are used at boot time.

If a service is not defined, Luminova falls back to its default implementation.

Purpose

The Kernel exists to centralize system-level configuration:

• Define core services (logger, cache, session, mailer, HTTP client)
• Replace default implementations when needed
• Support environment-specific service configuration

Kernel Contract

Every Luminova application must define exactly one Kernel class.

Requirements:

• Location: /app/Kernel.php
• Class name: Kernel (fixed, cannot be changed)
• Must implement: Luminova\Interface\ServiceKernelInterface
• Abide with request for shared or new object instance.

namespace App;

use Luminova\Interface\ServiceKernelInterface;

class Kernel implements ServiceKernelInterface
{
    // Define services here
}

Examples

Basic Kernel Class

A minimal Kernel implementation defines how core services are resolved during application boot.

// /app/Kernel.php

namespace App;

use Monolog\Level;
use Monolog\Logger;
use Psr\Log\LoggerInterface;
use Monolog\Handler\StreamHandler;
use Luminova\Interface\ServiceKernelInterface;

final class Kernel implements ServiceKernelInterface
{
    private static ?ServiceKernelInterface $instance = null;

    /**
     * Create kernel instance.
     */
    public static function create(bool $shared): static
    {
        if (!$shared) {
            return new self();
        }

        return self::$instance ??= new self();
    }

    /**
     * Indicate if kernel should be shared.
     */
    public static function shouldShareObject(): bool
    {
        return true;
    }

    /**
     * Resolve application logger.
     */
    public function getLogger(): ?LoggerInterface
    {
        $logger = new Logger('my_app_channel');
        $logger->pushHandler(
            new StreamHandler(
                root('/writeable/logs/', 'app.log'),
                Level::Debug
            )
        );

        return $logger;
    }

    // Other service resolvers...
}

Define only what you need—everything else falls back to framework defaults.

Dynamic Application Resolving

The Kernel can dynamically resolve which application class to use based on the runtime context.

This allows you to switch application behavior depending on environment (CLI vs HTTP) or architecture (MVC vs HMVC), without touching the core boot process.

HTTP vs CLI

// Kernel::getApplication

use App\CliApplication;
use App\HttpApplication;

public function getApplication(): ?Application
{
    if (Luminova::isCommand()) {
       return new CliApplication();
    }

    return new HttpApplication();
}

HMVC vs MVC

// Kernel::getApplication

use App\MvcApplication;
use App\HmvcApplication;

public function getApplication(): ?Application
{
    if (Luminova::isHmvc()) {
        return new HmvcApplication();
    }

    return new MvcApplication();
}

Return null to fall back to the default App\Application

Accessing Kernel Methods

The Kernel is automatically resolved during the framework boot process.

Manual Initialization

use App\Kernel;

$kernel = Kernel::create(shared: true);

$application = $kernel->getApplication();

Using Service Class (Recommended)

The preferred way is via the Luminova\Luminova Class, which automatically resolves the Kernel and handles shared instances.

use Luminova\Luminova;

// Get application logger
$logger = Luminova::kernel(shared: true)->getLogger();
$logger->info('User logged in successfully');

// Get application HTTP client
$client = Luminova::kernel(shared: true)->getHttpClient([...]);
$response = $client->request('GET', 'https://example.com', [...]);

Class Definition

• Class namespace: \App\Kernel
• This class implements: \Luminova\Interface\ServiceKernelInterface,

Methods

create

Create a kernel instance.

This static factory method is called by Luminova to create the kernel instance.

• When $shared is true, the kernel may return a shared instance
• When $shared is false, the kernel must return a new instance

This gives the application full control over kernel reuse.

Typical use cases for shared kernels:

• Shared configuration
• Shared service instances
• Reduced initialization cost

public static create(bool $shared): ServiceKernelInterface;

Parameters:

Return Value:

Luminova\Interface\ServiceKernelInterface - Returns shared or new kernel instance.

Note:This method is used by Luminova to initialize and create kernel object.

shouldShareObject

Defines whether the kernel should share a single application object.

• Returning true allows Luminova to reuse the same kernel instance
• Returning false forces a new kernel instance on each request or context

Default behavior is to share the kernel.

public static shouldShareObject(): bool

Return Value:

bool - Returns true to share object, false otherwise.

getRoutingSystem

Get the routing system instance.

Override this method if your application provides a custom router.Returning null instructs the framework to use the default router.

public getRoutingSystem(Luminova\Foundation\Core\Application $app): ?Luminova\Interface\RouterInterface

Return Value:

Luminova\Interface\RouterInterface|null - Returns the routing system instance, or null for the default.

getApplication

Allows using a custom Application class.

Override this method to using a custom Application class.Or null to allow Luminova create use the default.

public getApplication(): ?Luminova\Foundation\Core\Application

Return Value:

Luminova\Foundation\Core\Application|null - Returns the application instance, or null for the default.

Use this only if you really need to change application behavior or use different application based on environment or HMVC module

getLogger

Get the preferred logger instance.

The returned logger must implement PSR's LoggerInterface.Returning null instructs the framework to fall back to its default logger.

public getLogger(): ?Psr\Log\LoggerInterface

Return Value:

Psr\Log\LoggerInterface|null - Returns the logger instance, or null for the default.

getMailer

Get the mail client to use for the application.

The mailer must implement Psr\Mail\MailerInterface.

You may return either:

• an instance of the mailer,

• a class name implementing the mailer,

• or null to use the default mailer.

• You can use built-in clients like:

  • Luminova\Components\Email\Clients\PHPMailer
  • Luminova\Components\Email\Clients\SwiftMailer

public getMailer(): Luminova\Interface\MailerInterface|class-string<Luminova\Interface\MailerInterface>|null

Return Value:

Luminova\Interface\MailerInterface|class-string<\Luminova\Interface\MailerInterface>|null - Returns a mailer, instance, a mailer fully qualified name, or null for the default mailer.

getHttpClient

Return the HTTP client used for outbound requests.

If null is returned, the default Luminova Novio client is used.Custom clients must implement the PSR ClientInterface.

Luminova clients:

• \Luminova\Http\Client\Novio (default)
• \Luminova\Http\Client\Guzzle

public getHttpClient(array $config = []): Psr\Http\Client\ClientInterface|string|null

Parameters:

Return Value:

Psr\Http\Client\ClientInterface|string|null - Returns a client instance, a client class name, or null to use the default.

getCacheProvider

Get the cache provider for the application.

The cache provider must extend Luminova\Base\Cache.You may return either:

• an instance of the cache provider,
• a class name implementing the cache provider,
• or null to use the default cache provider.

public getCacheProvider(): Luminova\Base\Cache|class-string<Luminova\Base\Cache>|null

Return Value:

Luminova\Base\Cache|class-string<\Luminova\Base\Cache>|null - Returns a cache provider instance, a cache provider fully qualified name, or null for the default cache provider.

getSessionHandler

Get the session handler for the application.

The session handler must extend Luminova\Base\SessionHandler.You may return either:

• an instance of the session handler,
• a class name implementing the session handler,
• or null to use the default session handler.

public getSessionHandler(): Luminova\Base\SessionHandler|class-string<Luminova\Base\SessionHandler>|null

Return Value:

\Luminova\Base\SessionHandler|class-string<Luminova\Base\SessionHandler>|null - Returns a session handler instance, a session handler fully qualified name, or null for the default session handler.