Luminova Framework

PHP Luminova: Public Main Controller (index.php)

Last updated: 2026-10-27 22:09:41

Documentation for Luminova Entry Controller index.php

This documentation outlines the purpose of the index.php file and its key responsibilities in the Luminova framework.

Luminova uses the index.php and .htaccess file in public directory to serve the application entry point for handling incoming HTTP requests or controller routable CLI commands. It is responsible for autoloading and initializing framework modules, setting up method-based routing prefixes, and directing requests to the appropriate controllers. The index.php and .htaccess file must be located in the /public/ directory of your Luminova project, and its location and name cannot be changed or moved to another directory.

It recommend to use appropriate permission for public directory as project document root.The public is similar to public_html on most shared hosting.

For environment setup, htaccess examples and installation see Installation Guides


Responsibilities

  1. Bootstrapping the Framework: Initializes core components and loads necessary modules.
  2. Ensuring Correct Directory Context: Verifies that the application runs from the correct directory.
  3. Defining Routing Prefixes: Sets up routing prefixes to manage request paths effectively.
  4. Running the Application: Executes the application by dispatching requests to the proper controllers.

Implementations

Below are several examples of how index.php might be configured.


Using PHP Attribute Routing

Using PHP attribute #[Route()], #[Prefix()], #[Group()] and #[Command()], simplifies development making your routing closer to controller class/method.

When env(feature.route.attributes) is enable, your index.php stays clean, all routing prefix and error handling are done in controller classes when needed.

Example:

<?php
declare(strict_types=1);

use Luminova\Boot;

// Boot framework classes 
require_once __DIR__ . '/../system/Boot.php';

if (getcwd() . DIRECTORY_SEPARATOR !== DOCUMENT_ROOT) {
    chdir(DOCUMENT_ROOT);
}

Boot::http()->router->context()->run();

Method-Based Routing Setup

When env(feature.route.attributes) is disabled, you are required to configure custom URI prefixes and custom error handlers per prefix as needed while defining your routes logic in /routes/* directory using a custom prefix name as /routes/<filename>.php or /routes/web.php for default HTTP pages, /routes/api.php for APIs and /routes/cli.php for commands.

Examples:

Handle all URI prefixes if not default was define.

// /routes/web.php
declare(strict_types=1);

use \Luminova\Routing\Router;

Router::get('/', 'MainController::home');
Router::get('/about', 'MainController::about');

// Or using Closure 

Router::get('/', static function (): int {
    return \Luminova\Funcs\view('index')
        ->contents();
});

The URI prefix name web serves as a default handler for all incoming URLs if no other custom context prefix matches the request url prefix. This does not mean that only URLs starting with web are handled by this context. Instead, it is a generic way for Luminova to manage all web-related routes when no specific context prefix is defined or matched.

If other custom context prefixes are defined, they will be matched first, and the web context will serve as the fallback for any remaining URLs.

<?php
declare(strict_types=1);

use Luminova\Boot;
use Luminova\Routing\Prefix;
use App\Errors\Controllers\AppError;

// Boot framework classes 
require_once __DIR__ . '/../system/Boot.php';

/**
 * Ensure that we are in front controller while running script in cli mode
*/
if (getcwd() . DIRECTORY_SEPARATOR !== DOCUMENT_ROOT) {
    chdir(DOCUMENT_ROOT);
}

Boot::http()->router->context(
    [
        new Prefix(Prefix::WEB, [AppError::class, 'onWebError']),
        new Prefix(Prefix::API, [AppError::class, 'onApiError']),
        new Prefix('admin', [AppError::class, 'onAdminError']),
        new Prefix(Prefix::CLI)
    ]
)->run();

In this example, the router is configured with four contexts:

  • WEB: Handles web requests and uses the AppError::onWebError method for error handling.
  • API: Handles API requests and uses the AppError::onApiError method for error handling.
  • admin: A custom context that uses the AppError::onAdminError method for error handling.
  • CLI: Handles CLI requests without a specific error handler.

Using Callbacks

This example demonstrates using anonymous functions (callbacks) for error handling in the WEB and API contexts.

Boot::http()->router->context(
    [
        new Prefix(Prefix::WEB, fn(Application $app): int => AppError::onWebError($app)),
        new Prefix(Prefix::API, function(): never {
            throw new HttpException('Endpoint not found', 404);
        }),
        new Prefix(Prefix::CLI)
    ]
)->run();

Using Arrays

In this example, contexts are defined using arrays. Each array specifies a prefix and an error handler.

Boot::http()->router->context([
    Prefix::with(Prefix::WEB, [AppError::class, 'onWebError']),
    Prefix::with(Prefix::API, [AppError::class, 'onApiError']),
    Prefix::with('admin', [AppError::class, 'onAdminError']),
    Prefix::with(Prefix::CLI)
])->run();

Notes:

  • Ensure the context name should be unique based on your URLs to discover and load only the required files.
  • Mixing Prefix object instances with plain arrays within the same context list may produce unintended errors; prefer using either Prefix instances or Prefix::with() arrays consistently within a single context() call.

This documentation should provide a clear understanding of how to configure and use the index.php file as the entry point for a Luminova application.

See Also