Luminova Framework

Complete Changelog (v3.9.5 and Later)

PropertyValue
Version Code3.9.4
Version NameHermes
Published2025-10-21 05:31:38
Updated2026-10-21 05:31:38

Version 3.6.8 brings a major cleanup across Luminova’s core. Many parts were renamed, optimized, or fixed, and several new helper classes were added, including Password, String, and the improved error-handling system. The template view engine and the core exception layer also received substantial tuning.

Default HTTP error templates now support grouped pages using 4xx.php and 5xx.php, replacing the old 404.php and 500.php pattern.

To begin migrating to 3.6.8, see the Migration Guide.


Fixes

Fixed in Version 3.9.0

Fixed incorrect mixing of PHP 8.1 standards with PHP 8.0, which caused runtime errors.


Added in Version 3.6.8

Routing System

Fixed an issue where routes defined with HTTP HEAD method were incorrectly returning 404 errors.


New Features

Added in Version 3.6.9


PHP Layout Composition

Improved the PHP layout composition class and introduced new helper features.The layout object is now automatically available inside PHP template files when App\Config\Template->enableDefaultTemplateLayout is enabled.

Dynamic Template Placeholders

Placeholders defined within a layout section are now resolved automatically when extending or rendering the layout with options:

<?php $this->layout->begin('title'); ?>
<h1>{{ placeholder }}</h1>
<?php $this->layout->end('title'); ?>

Smarty Template Extension

Improved the Smarty extension to provide simpler access to functions and classes, giving it behavior in Luminova closer to Twig.

Object Method Access

You can now call object methods directly without assigning the object to a Smarty variable first:

{{ $self.app->doFoo()->getBar() }}

Smarty & Twig Template Extension

Improved both extensions with a single configuration point for managing custom extensions and modifiers.Template caching is now handled by Luminova for consistent behavior and integration with the static URL cache system.


Routing System

Optimized the routing system. All HTTP method helpers are now static. Dependency Injection in routing has been improved to honor default parameter values when a dependency cannot be resolved.

Added the Router::isPrefix(...) helper for checking URI prefixes.

Static HTTP Helpers:

  • get — HTTP GET
  • post — HTTP POST
  • put — HTTP PUT
  • patch — HTTP PATCH
  • delete — HTTP DELETE
  • head — HTTP HEAD
  • options — HTTP OPTIONS
  • any — Any valid HTTP method
  • middleware — Before-middleware handler
  • after — After-middleware handler
  • guard — CLI middleware handler
  • capture — Custom HTTP methods
  • command — CLI command
  • group — CLI command grouping
  • bind — HTTP URI group binding
  • onError — HTTP error handler

HTTP Message Stream

Optimized the message stream class, added a new buffer method, and moved the class namespace fromLuminova\Storage\Stream to Luminova\Http\Message\Stream.


Global Import Function

The global import() function now supports promise resolving:

use function \Luminova\Funcs\import;

import('view:template', promise: true)
  ->then(fn(string $html) => print($html))
  ->catch(fn(Throwable $e) => echo $e->getMessage());

Added in Version 3.6.8

Base HTTP Controller

Introduced a new protected $view property, giving controllers direct access to a lazily initialized instance of Luminova\Template\View for template management.

$this->view->view('home')->render();

// Or directly from the application class
$this->app->view->view('home')->render();

HTTP Controller Methods

HTTP controller routable methods can now return Psr\Http\Message\ResponseInterface, Luminova\Interface\ContentResponseInterface, or the traditional int.

Example

Using Luminova\Template\Response class.

use Luminova\Attributes\Route;
use Luminova\Interface\ContentResponseInterface;
use function Luminova\Funcs\response;

#[Route('/api/hello', methods: ['GET'])]
public function hello(): ContentResponseInterface
{
  return response()->content([
    'message' => 'Hello world'
  ]);
}

With middleware authentication:

If you want to return default content when middleware fails, otherwise return STATUS_ERROR:

use Luminova\Attributes\Route;
use Luminova\Interface\ContentResponseInterface;
use function Luminova\Funcs\response;

#[Route('/api/(:root)', methods: ['ANY'], middleware: Route::BEFORE_MIDDLEWARE)]
public function middleware(): ContentResponseInterface|int
{
  if (OK) {
    return STATUS_SUCCESS;
  }

  return response()->failed()->content(
    ['message' => 'Access denied'], 
    ['Content-Type' => 'application/json']
  );
}

Using Psr\Http\Message\ResponseInterface to return default content when middleware fails.

When middleware fails, set response status code to 401 or 500, this way the routing system will terminate execution immediately.

use Luminova\Attributes\Route;
use Luminova\Http\Message\Response;
use Psr\Http\Message\ResponseInterface;

#[Route('/api/(:root)', methods: ['ANY'], middleware: Route::BEFORE_MIDDLEWARE)]
public function middleware(): ResponseInterface|int
{
  if (OK) {
      return STATUS_SUCCESS;
  }

  return new Response(
    json_encode(['message' => 'Access denied']), 
    401, // Indicate that middleware has failed
    ['Content-Type' => 'application/json']
  );
}

Routing System

Added a new pattern method to define and manage custom URI segment placeholders.This allows you create reusable patterns for route parameters, improving maintainability and reducing repetition of patterns.

// In App\Application::onCreate()
Router::pattern('slug', '[a-z0-9-]+');  

// In App\Controllers
#[Luminova\Attributes\Route('/blog/(:slug)', methods: ['GET'])]
public function blog(string $slug): int 
{
  // Handle blog route using the slug value
}

Note: Once defined, the slug pattern can be reused across multiple routes, ensuring consistent validation.


Password Helper

A new Password helper has been added to handle all password-related operations in one place.

Now:

use Luminova\Security\Password;

$hash = Password::hash('pass');
Password::verify('pass', $hash);

// Additional utilities:
Password::rehash('pass', $hash);
Password::strength('pass');
Password::isCompromised('pass');

// and more...

Before:

Crypter::password('pass');
Crypter::isPassword('pass', 'hash');

Http Proxy Helper

A dedicated Proxy helper is now available for checking and validating HTTP/SOCKS proxies.

Now:

use Luminova\Components\Proxy;

$proxy = '';
Proxy::validate($proxy);
Proxy::ping($proxy);

// and more...

String Helper

A new Str helper provides object-based string manipulation features.

Now:

use Luminova\Components\String\Str;

$str = Str::of('peter');

echo $str->length();         // 5
echo $str->toUpperCase()
         ->trim();           // PETER

// and more...

Core Error Monitoring System

Added Luminova\Errors\Monitor for advanced error detection and Luminova\Errors\Message for structured error messages. This system improves how Luminova applications detect and respond to critical issues.


Exception Error Codes

Added Luminova\Exceptions\ErrorCode to centralize exception and error codes. Key methods include:

  • getName – Retrieve a descriptive name for an error code.
  • has – Check if an error or exception code is recognized.

Abstract Base Exception Class

Introduce new methods:

  • getDescription - Return a formatted exception message without any private file path included.
  • isCode method for conveniently checking if the current exception code matches one or more codes.
  • trace Get the file and line of a specific call depth where the method was called.

Example:

use Luminova\Exceptions\ErrorCode;
use Luminova\Exceptions\LuminovaException;
use Luminova\Exceptions\RuntimeException;

try {
    throw new RuntimeException('Error', ErrorCode::NOT_SUPPORTED);
} catch (LuminovaException $e) {
  if ($e->isCode(ErrorCode::DATABASE_ERROR)) {
    // Handle single code
  }

  if ($e->isCode([ErrorCode::NOT_ALLOWED, ErrorCode::NOT_SUPPORTED])) {
    // Handle multiple codes
  }
}

Template View Class

The Luminova\Template\View class now includes additional methods:

  • info – Get metadata about a template file without rendering.
  • exists – Check if a template file exists without rendering.
  • setUriPathDepth – Configure the relative URI parent directory depth.

These method can be used directly inside template files:

  • hasOption – Check if a context option is available in the view.
  • isExported – Check if a property is exported to the template scope.
  • getExports – Retrieve all exported properties available to the template.
  • getExport – Retrieve a specific property exported to the template scope.
  • getOptions – Get all context options for the view.
  • getOption – Retrieve a single context option by name.
  • getTemplate – Get the resolved or specified template filename.
  • getStatusCode – Get the HTTP status code used during rendering.

Backend Session Class

The Session class now supports role-based access control, with methods for finer-grained permission management:

  • roles(array $roles)Assign user roles to the session.

  • getRoles(): arrayRetrieve all roles currently stored in the session.

  • guard(array $roles, int $mode = Session::GUARD_ANY, ?callable $onDenied = null): boolValidate roles against access rules. Returns true if access is denied (fail-fast pattern), false if access is granted.

  • toSessionId(string $id, string $algo = 'sha256')Convert a string into a valid PHP session ID.

    Example:

    Convert a system identifier into a valid PHP session ID for persistent CLI logins.

    use Luminova\Command\Terminal;
    use Luminova\Sessions\Session;
    
    $sid = Session::toSessionId(Terminal::getSystemId());

    Supported Guard Modes:

    • Session::GUARD_ANY (default): Access granted if at least one role matches.
    • Session::GUARD_ALL: Access granted only if all roles match.
    • Session::GUARD_EXACT: Access granted only if all and only the specified roles match.
    • Session::GUARD_NONE: Access granted only if none of the roles are present.

Example:

$session->onRoleGuard(
  function(Session $session, array $roles, array $subscriptions){
    throw new HttpException('Insufficient privileges.');
  },
  ['admin', 'moderator'],
  Session::GUARD_ANY
);

// if ($session->guard(['admin', 'moderator'], Session::GUARD_ALL)) {
//     throw new AccessDenied('Insufficient privileges.');
// }

PHP Route Attribute

A new $aliases property has been added to the Route attribute to define multiple alternative URI patterns for the same controller method.

Before (using multiple attributes)

Previously, to map several URIs to the same method, you had to repeat the Route attribute:

// /app/Controllers/Http/ExampleController.php

use Luminova\Attributes\Route;

#[Route('/', methods: ['GET'])]
#[Route('/home', methods: ['GET'])]
#[Route('/default', methods: ['GET'])]
#[Route('/dashboard', methods: ['GET'])]
public function home(): int 
{
  return $this->view('index');
}

Now (using aliases)

You can achieve the same result with a single attribute, improving readability and reducing duplication:

// /app/Controllers/Http/ExampleController.php

use Luminova\Attributes\Route;

#[Route('/', methods: ['GET'], aliases: [
  '/home',
  '/default'
  '/dashboard'
])]
public function home(): int 
{
  return $this->view('index');
}

PHP Prefix Attribute

The Prefix attribute now supports a new $exclude property that allow you to specify URI prefixes to exclude from controller matching. This removes the need for complex negative-lookahead patterns.

Before (manual regex exclusions)

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

use Luminova\Attributes\Prefix;

#[Prefix(pattern: '/(?!api(?:/|$)|admin(?:/|$)).*')]
class MainController extends Controller
{
}

Now (using the built-in exclude list)

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

use Luminova\Attributes\Prefix;

#[Prefix(pattern: '/(:base)', exclude: [
    'api',
    'admin'
])]
class MainController extends Controller
{
}

Global Helper Functions

Added new global helper functions for improved response handling:

  • redirect – Sends an HTTP redirect using the current Response instance.Supports both Location and Refresh headers and automatically terminates execution after sending.

    Example:

    Luminova\Funcs\redirect(string $uri, ?string $method = null, int $status = 302);
  • abort – Terminates execution and sends an error response with the specified HTTP status code.Useful for rejecting invalid requests or handling unexpected conditions globally.

    Example:

    Luminova\Funcs\abort(int $status = 500, string $message = '', array $headers = []);
  • back – Redirects the client to the previous page using the HTTP_REFERER header,falling back to / if no referrer is available.

    Example:

    Luminova\Funcs\back(?string $method = null, int $status = 302);
  • array_first – Returns the first element of an array, or null when the array is empty.

    Example:

    use function Luminova\Funcs\array_first;
    
    $item = array_first(['a', 'b', 'c']); 
    // 'a'

  • array_last – Returns the last element of an array, or null when the array is empty.

    Example:

    use function Luminova\Funcs\array_last;
    
    $item = array_last(['a', 'b', 'c']); 
    // 'c'

Environment Variable

  • app.mb.encoding → Set the internal encoding for multibyte string functions.
  • page.cache.query.params → Determines whether query parameters are included in cache keys.

Optimization and Enhancements

Updated in Version 3.6.8

Template View Class

The Luminova\Template\View class has been improved to make template rendering faster, safer, and easier to use.

Key improvements:

  1. Lazy Loading – The View class is no longer a trait inside the Luminova\Foundation\Core\Application. It is now loaded only when needed, which improves performance.
  2. Protected Scope – Templates cannot directly access private properties or methods of the View class. This keeps your data safe and prevents accidental changes.
  3. Consistent Rendering – Isolated rendering is strictly enforced. When not isolated, $self behaves exactly like $this, making template code predictable and easier to read.

Tip for beginners:Think of the View class as a separate workspace for your templates. It only exposes what is meant to be used in templates and keeps everything else private. This prevents errors and keeps your code clean.


Session::login

The login() with role assignment at the time of authentication:

$session->setRoles(['admin', 'editor']);
$session->login();

Assign user to a new additional roles after login.

$session->assignRoles(['moderator']);

Revoke user roles.

$session->revokeRoles(['admin', 'editor', 'moderator']);

This eliminates the need for separate role setup after login and ensures consistent session initialization.


Schema Structured Data Generator

The Luminova\Components\Seo\Schema class has been optimized to improved performance and introduced new structure of schema definition, making it easier to extend and manager.


Luminova Functions Import

The global import() function now supports passing variables into the imported file’s scope:

Luminova\Funcs\import('path/to/file.php', scope: ['name' => 'Peter']);

// Inside path/to/file.php:
echo $name; // Peter

Outgoing HTTP Request Helper Class (Network)

  • Added support for static method calls (get(), post(), postAsync()) to simplify HTTP requests without manually creating client objects.

  • Introduced Network::config(...) for defining default settings (base_uri, headers, timeout). Configuration is locked after first setup to prevent changes.

  • Improved error handling:

    • Clear BadMethodCallException is thrown when a static method is called incorrectly (e.g., missing URL with no base_uri configured).

Example:

use Luminova\Http\Network;

// Configure default settings
Network::config([
  'base_uri' => 'https://api.example.com/',
  'timeout'  => 10,
  'headers'  => ['Accept' => 'application/json']
]);

// Static requests
$response = Network::get('user/42/profile');

// Async
Network::postAsync('users', ['json' => ['name' => 'Alice']])
  ->then(function(Response $response){
    //...
  });

Without Default Configuration:

Static methods also work without pre-configured defaults — simply pass the full URL and any request options directly:

use Luminova\Http\Network;

$response = Network::get('https://api.example.com/user/42/profile', [
  'timeout'  => 10,
  'headers'  => ['Accept' => 'application/json']
]);

Error Exception Class

The Luminova\Exceptions\ErrorException class has been updated to match PHP’s native ErrorException behavior.You can now pass the error severity, file, and line number directly when creating an instance:

new Luminova\Exceptions\ErrorException(
  $message,
  $code = ErrorCode::ERROR,
  $severity = 1,
  $file = null,
  $line = null,
  $previous = null
);

Error Controller Interface

The Luminova\Interface\ErrorHandlerInterface now requires an abstract method onTrigger() for custom HTTP status code handling. This method is called when:

  • no default error handler is defined, or
  • Luminova\Routing\Router::trigger(xxx) is explicitly invoked.

Example:

// /app/Errors/Controllers/AppError.php

public static function onTrigger(int $status, Segments $segment): int
{
  $template = match ($status) {
      500 => '5xx',
      // Add more custom templates per status code
      default => '4xx'
  };

  return view($template)->render(
    [
      'status' => $status,
      'uri'    => $segments->all()
    ],
    $status
  );
}

Dynamic URI Segment Placeholders

Improved placeholder matching and added new built-in types for cleaner route definitions:

  • (:uuid) – matches valid UUID values.
  • (:username) – matches usernames containing letters, numbers, dots, underscores, or hyphens.
  • (:version) – matches version numbers such as 1.0, 2.5.3, or similar.

These placeholders make your routes easier to read and automatically validate the expected format of each URI segment.


Renamed

Renamed in Version 3.6.8

Update all references to these namespaces:

  • Luminova\Storage\Stream → Luminova\Http\Message\Stream
  • Luminova\Components\IP → Luminova\Http\Network\IP

Renamed in Version 3.6.8

Update all references to these namespaces:

  • Luminova\Http\Client\Curl → Luminova\Http\Client\Novio
  • Luminova\Core\Core** → Luminova\Foundation\Core\*
  • Luminova\Base\BaseController → Luminova\Base\Controller
  • Luminova\Base\BaseCommand → Luminova\Base\Command
  • Luminova\Base\BaseConsole → Luminova\Base\Console
  • Luminova\Base\BaseConfig → Luminova\Base\Configuration
  • Luminova\Arrays\ArrayUtil → Luminova\Components\Collections\Arr
  • Luminova\Arrays\Listifier → Luminova\Components\String\Listifier

Routing System Error Handler

Setting error handler in routing system:

  • Luminova\Routing\Router::setErrorListener() → Use Luminova\Routing\Router::onError()

Exceptions

  • Luminova\Exceptions\*::getFilteredMessage() → Use Luminova\Exceptions\*::getDescription()

URI Parent Depth

Setting URL and assets parent directory depth:

  • Luminova\Template\View::setUriPathDepth(N) → Use Luminova\Template\View::setRelativeDepth(N)

Route Attribute Constants

Attribute Route class middleware constants renamed for clarity.

Under namespace: Luminova\Attributes\:

Http Route Attribute:

  • Route::HTTP_BEFORE_MIDDLEWARE → Use Route::BEFORE_MIDDLEWARE
  • Route::HTTP_AFTER_MIDDLEWARE → Use Route::AFTER_MIDDLEWARE

Command Attribute:

  • Route::CLI_GLOBAL_MIDDLEWARE → Use Command::GLOBAL_MIDDLEWARE
  • Route::CLI_GUARD_MIDDLEWARE → Use Command::GROUP_MIDDLEWARE

Structured Data Generator

Schema class methods renamed for consistency:

  • Luminova\Seo\Schema::setConfig() → Use Luminova\Components\Seo\Schema::setObject()
  • Luminova\Seo\Schema::getSchema() → Use Luminova\Components\Seo\Schema::toJsonLd()
  • Luminova\Seo\Schema::getMeta() → Use Luminova\Components\Seo\Schema::getHeadTags()
  • Luminova\Seo\Schema::getMutable() → Use Luminova\Components\Seo\Schema::getObject()
  • Luminova\Seo\Schema::getGraph() → Use Luminova\Components\Seo\Schema::getJsonLdString()
  • Luminova\Seo\Schema::getScript() → Use Luminova\Components\Seo\Schema::getJsonLdScript()

Deprecated

Deprecated in Version 3.6.8

Sitemap Generator Command

The sitemap command now allows passing arguments to override default configurations.You can also exclude URLs using patterns, built-in placeholders, or even custom defined placeholders.

  • Deprecated: php novakit generate:sitemap
  • Use instead: php novakit sitemap

Changes

Changed in Version 3.6.8

Exception Codes Reference

Exception codes are now centralized in a dedicated Code class.Update your exception constructors to reference codes from Luminova\Exception\Code instead of individual exception classes.

Before:

use Luminova\Exception\RuntimeException;

throw new RuntimeException('Message', RuntimeException::INVALID);

After:

use Luminova\Exception\Code;
use Luminova\Exception\RuntimeException;

throw new RuntimeException('Message', ErrorCode::INVALID);

Routing System Error Trigger

The routing error trigger method is now private.Replace calls to triggerError() with trigger().

Before:

$router->triggerError($code);

After:

$router->trigger($code);

Core Error Handling

The Luminova\Errors\ErrorHandler class has been replaced with Luminova\Errors\Monitor.Update references to use the new class and correct method names.

Before:

use Luminova\Errors\ErrorHandler;

ErrorHandler::*;

// Resolve error code to name
ErrorHandler::getErrorName(...);

// Deprecated error trigger
ErrorHandler::depreciate(...);

After:

use Luminova\Errors\Monitor;

Monitor::*;

// Resolve error code to name
Luminova\Exception\ErrorCode::getName(...);

// Deprecated error trigger (correct spelling)
Monitor::deprecate(...);

Note: The method is now correctly named deprecate, replacing the misspelled depreciate.


ToDo

Do in Version 3.6.9

Template Configuration

Add a new boolean property $enableDefaultTemplateLayout, in template configuration to enable or disable the default template layout object:

namespace App\Config;

final class Template 
{ 
  /**
   * Enable or disable the default template layout.
   *
   * @var bool $enableDefaultTemplateLayout (default: `false`)
   */
  public bool $enableDefaultTemplateLayout = false;
}