PHP Luminova: Public Main Controller (index.php)
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
publicdirectory as project document root.Thepublicis similar topublic_htmlon most shared hosting.
For environment setup, htaccess examples and installation see Installation Guides
Responsibilities
- Bootstrapping the Framework: Initializes core components and loads necessary modules.
- Ensuring Correct Directory Context: Verifies that the application runs from the correct directory.
- Defining Routing Prefixes: Sets up routing prefixes to manage request paths effectively.
- 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 theAppError::onWebErrormethod for error handling.API: Handles API requests and uses theAppError::onApiErrormethod for error handling.admin: A custom context that uses theAppError::onAdminErrormethod 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
URLsto discover and load only the required files.- Mixing
Prefixobject instances with plain arrays within the same context list may produce unintended errors; prefer using eitherPrefixinstances orPrefix::with()arrays consistently within a singlecontext()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
- Attribute Routing - Learn more about how PHP attribute routing and its usage.
- Method-Based Routing - Learn more about how method-based routing and prefixes works.
- Routing System - Learn more about how routing and their usage.
- Error Controller handler - Handing controller-level and URI-prefix level custom errors.