README

PHP Luminova Framework

A modular PHP framework for building web applications, APIs, and command-line tools.

Documentation · Website · Source code · Tutorials

Overview

Luminova is a modular PHP framework for building maintainable web applications and command-line tools. It supports MVC and HMVC application structures, flexible routing, native PHP views, database access, request handling, and a set of built-in tools for common application tasks.

Configure the features your application needs, keep application code organized, and use the same project to build websites, APIs, and CLI commands.

This repository provides the Luminova project skeleton and application bootstrapping. For detailed usage and API references, see the official documentation.

Features
Requirements
Installation
Run the application
Project structure
Quick start
NovaKit commands
Configuration
Documentation and support
Contributing
License

Features

MVC and HMVC: Organize application code into controllers, models, views, and optional modules.
Flexible routing: Choose PHP attribute-based routes or register routes in route files.
HTTP and CLI applications: Handle web requests and build command-line commands with routing support.
Database tools: Use the database builder and ORM features for common data operations.
PHP templating: Render native PHP views, with support for optional template engines such as Twig and Smarty.
Request and response handling: Work with HTTP requests, responses, and application middleware.
Sessions and authentication support: Manage session state and application user flows.
Storage integrations: Work with local storage and supported cloud storage drivers.
File responses: Deliver files and use supported temporary or permanent file links.
Localization: Build applications that support multiple languages and locales.
Email and encryption: Use framework integrations for common application needs.
SEO utilities: Generate sitemaps and structured data with the available framework tools.
Caching and services: Share application services and use supported caching integrations.
AI integrations: Access supported AI model integrations when your application needs them.
Configurable features: Adjust framework behavior through application environment settings.

See the documentation for feature details, configuration options, and supported integrations.

Requirements

PHP 8.1 or later
Composer
PHP extensions:
- ext-json
- ext-mbstring
Required packages are installed by Composer, including the PSR logging and HTTP client interfaces.
Apache, Nginx, or the PHP built-in development server.

Some features require additional packages or PHP extensions. Check composer.json and the documentation for the requirements of each feature.

Installation

Create a new project with Composer:

composer create-project luminovang/luminova my-project
cd my-project

Composer installs the project dependencies and runs the configured project setup scripts, including application key generation.

If setup did not generate an application key, run:

php novakit generate:key

Run the application

Start the built-in development server:

php novakit server

Open http://localhost:8000 in your browser.

Use the built-in server for local development. Configure Apache or Nginx and your document root appropriately for deployment.

Project structure

The exact structure can vary as your application grows. The main directories include:

app/
├── Config/             # Application configuration
├── Controllers/        # HTTP and CLI controllers
├── Models/             # Application models
├── Views/              # Application view templates
└── Modules/            # Optional HMVC modules
bootstrap/              # Framework bootstrap and helper functions
bin/                    # Console entry points and commands
public/                 # Public web root and front controller
resources/              # Application resources and views
routes/                 # Method-based route definitions
writeable/              # Private storage, logs, cache, sessions, and temp files
system/                 # Framework system and installed packages

Keep private files and runtime data out of the public web root. In production, point your web server at the project's public/ directory.

Quick start

Attribute-based routing

Enable attribute routing in your environment configuration:

feature.route.attributes = true

Then define a controller and route:

// /app/Controllers/Http/MainController.php

<?php

namespace App\Controllers\Http;

use Luminova\Attributes\Prefix;
use Luminova\Attributes\Route;
use Luminova\Base\Controller;

#[Prefix('/(:base)', exclude: ['api'])]
class MainController extends Controller
{
    #[Route('/', methods: ['GET'])]
    public function index(): int
    {
        return $this->view('index');
    }
}

This maps a GET request to / to the controller's index() method. See the routing documentation for route patterns, middleware, and additional options.

Method-based routing

If you prefer defining routes in route files, disable attribute routing:

feature.route.attributes = false

Create a controller:

// /app/Controllers/Http/MainController.php

<?php
namespace App\Controllers\Http;

use Luminova\Base\Controller;

class MainController extends Controller
{
  public function index(): int
  {
    return $this->view('index');
  }
}

// /routes/web.php

$route->get('/', 'MainController::index');

You can also register callback handlers where appropriate. Use the router and helper APIs documented for your installed Luminova version.

Render a view

From a controller, return a view response:

return $this->view('index');

You can pass view options and configure the content type or HTTP status when needed:

return $this->view(
    'index',
    [],             // View options
    View::HTML,     // Content type
    200             // HTTP status
);

The view name refers to a template in your application's configured view paths. Refer to the official documentation for view locations, rendering modes, and template options.

Novakit commands

Novakit provides commands for common project tasks. Examples:

Command	Purpose
`php novakit list`	List all available command.
`php novakit server`	Start the local development server.
`php novakit generate:key`	Generate an application encryption key.
`php novakit sitemap`	Generate the site's XML sitemap.

Run the relevant command from your project root. Check the documentation for the full command list and any command-specific options.

Configuration

Application settings are managed through the project's environment configuration and config files. Review the generated project configuration before deployment.

Keep production secrets and credentials out of source control.
Ensure writeable/ is writable by the application process, with permissions limited to what the application needs.
Configure session and cookie settings for your production domain.
Set the appropriate production environment mode so assets and runtime behavior use production settings.
Install optional packages and PHP extensions only for the features your application uses.

For configuration keys and deployment guidance, use the Luminova documentation.

Documentation and support

Documentation: luminova.ng/docs
Website: luminova.ng
Source code: github.com/luminovang/luminova
Framework package: luminovang/framework on Packagist
Issues and bug reports: GitHub Issues
Tutorials: Luminova on YouTube
Contact: peter@luminova.ng

When reporting a problem, include your PHP version, Luminova version, a clear description of the issue, and steps to reproduce it. Remove credentials and other private data from logs before sharing them.

Contributing

Contributions to the project skeleton are welcome, especially improvements to project structure, default configuration, setup, and developer experience.

Open an issue to discuss a significant change or bug.
Keep changes focused and consistent with the existing project.
Test your changes before opening a pull request.
Describe what changed and how you tested it.

For changes to the core framework or its documentation, use the relevant repositories:

License

Luminova is open-source software released under the MIT License.

luminovang / luminova

Package info

Security

Fund package maintenance!

Statistics