PHP Luminova: v3.3.0 Full Changelog

Luminova 3.5+ Update Overview

Starting from Luminova 3.5, deprecated classes and methods will trigger warnings:

• In development, a warning will be displayed.
• In production, the warning will be logged at the warning level.

New Features

Added Since 3.5.5

Core Framework Initialization

• Added support for caching .env variables in production. This improves performance by loading environment variables only once.

• Introduced a CLI helper to generate or refresh the environment cache:

  Copy

  php novakit env:cache --ignore "app.name,foo,bar"

Database Query Builder

• bind — Added support for binding placeholders to values when using table joins and on method.

Logger Class

• Enhanced logging with automatic inclusion of specific field values and headers in the context, improving debugging in production.
• Added support for minified log messages in production environments, while retaining human-readable format in development. This makes logs easier to parse using tools like ELK, Fluentd, or standard CLI tools like cat and tail.

Request Rate Limiter

New methods introduced:

• throttle() — Delays the response when the request limit is exceeded.
• getTimestamps() — Retrieves an array of request timestamps, with optional filtering of active (non-expired) timestamps.

Terminal Commands Class

New method:

• readInput() — Reads multi-line input from a pipe or redirected stream.
  Example:

  Copy

  echo "Foo from Pipe" | php index.php create-foo

Added Since 3.5.4

Core Application Class

Introduced support for early application termination and lifecycle hooks:

• onPreCreate - Invoked before the application and routing system are initialized.
• terminate - Allows early termination of the application before full initialization.
• onTerminate - Called before termination to determine whether the application should proceed with termination. Return true to allow or false to cancel.
• onTerminated - Executed after the application has been terminated.

Request Rate Limiter

Added a lightweight request rate limiter class supporting:

• Memcached, Redis, FileCache, or any PSR-6 CacheItemPoolInterface and andCacheInterface compatible implementations.
• Dynamic message formats and retry-after calculation.
• Custom headers and response formatting.

Global Helper Functions

New helper functions introduced:

• set_function - Safely invokes a native PHP function only if it's not disabled.
• set_max_execution_time - A custom wrapper for set_time_limit() that only sets the time limit if the current limit is lower and the function is not disabled.

HTTP Upload File Object

New method added:

• getMimeFromFile - Detects MIME type from a temporary file path or binary data.

Sitemap Generator Configuration

New configuration option:

• public int $maxExecutionTime = 300 - Specifies the maximum execution time in seconds. Set to 0 for unlimited execution time.

Added Since 3.5.3

Database Query Builder

The Database ORM class introduces new methods to support a wider range of use cases, enhancing flexibility and control over query building and execution.

• raw - Allows passing raw SQL expressions using the Luminova\Database\RawExpression class.
• strict - Enables or disables strict mode for WHERE clauses in DELETE or UPDATE queries.
• having - Adds filtering for grouped results using aggregate functions.
• isNull - Adds a condition to filter results where the specified column is NULL.
• isNotNull - Adds a condition to filter results where the specified column is not NULL.
• notIn - Adds a NOT IN (...) condition to exclude values from the result.
• conjoin - Groups multiple conditions using AND or OR (e.g., WHERE (a OR b)).
• nested - Nests multiple grouped conditions using AND/OR logic (e.g., WHERE ((a OR b) AND (c OR d))).
• column - A helper to create structured column conditions for conjoin and nested, improving readability.
• onDuplicate - Defines behavior for handling duplicate keys during INSERT operations.
• ignoreDuplicate - Allows skipping duplicate key errors when inserting records.
• inTransaction - Returns whether a transaction is currently active.
• getDebug - Retrieves debug information if debug() was called before executing the query.
• closeAfter - Enables or disables automatic connection closure after query execution (default: false).

Mailer Helper Class

• options - Set custom stream context options for the SMTP connection (e.g., SSL/TLS settings).
• addresses - Add multiple recipients using a comma-separated string, a simple array of emails, or an associative array with name => email format.
• notification - Specify an email address to receive delivery and read receipt notifications.
• addHeader - Add custom headers to the outgoing email (e.g., X-Priority, List-Unsubscribe).
• isHtml - Toggle the email format between HTML and plain text.
• isMail - Set the transport method to either native mail or SMTP.

Raw SQL Expression

The Luminova\Database\RawExpression class provides a way to include raw SQL expressions without quoting or escaping.

Predefined helper methods are available:

• now, year, month, day, time - Common time-based SQL functions.
• count, sum, average - Aggregate functions for grouped data.
• increment, decrement - SQL math expressions for numeric operations.
• currents - Returns an array with: currentDate, currentYear, currentMonth, currentDay, currentHour, currentMinute, and currentSecond.

Input Validation Class

• is_value - Validates that an input field exactly matches the specified value.

Added Since 3.5.2

• Database Query Builder

  • copy - Prepares column names for copying to another table.
  • to - Inserts copied column names from the copy method into another table.
  • replace - Similar to insert, but replaces existing data.

• HTTP Request Class

  • getAny - Retrieves a field from any HTTP method.
  • removeField - Removes a specific field from request data.

• Input Validation Class

  • not_equal - Validates that fields do not contain the same value.
  • float - Validates that a field contains a valid float value.

• Array Util Class

  • mergeIntervals - Merges an array into the current array at specified intervals (e.g., inserting ads within a post).
  • getArray - Retrieves the processed array after modifications.

Added Since 3.5.1

• Application Logger Class: Added support for Telegram logging, allowing log messages to be sent directly to a Telegram bot chat, ensuring that no errors go unnoticed. Once configured your telegram bot token and chatId, on production critical log levels will be sent to Telegram instead of logging to file.

  • telegram - method to explicitly sends log messages to a Telegram bot.

• Novakit Setup Command: Introduced support for setting up application environment variables through a command. This guides users in configuring required variables for supported environments.

  Example
  The following command walks you through the database configuration setup:

  Copy

  php novakit env:setup --t=database

• Command Utilities (Terminal Class): Added new methods for command-line operations:

  • tablist - Creates a selectable option list using key events (e.g., Tab, Arrow Up, Arrow Down, and Enter to select). Supports Escape and Ctrl+C to close.
  • keyEvent - Captures key events and returns an array containing the ANSI sequence code and human-readable key name.
  • cursorVisibility - Toggles cursor visibility.

• Command Text Utils Class: Added support for handling text with emojis.

  • emojiStrlen - Calculates the total character length of emojis in a string.
  • countEmojis - Counts the total number of emojis in a string.
  • stripEmojis - Removes all emojis from a given string.
  • hasEmoji - Determines whether the given text contains emojis.

Added Since 3.5.0

• Session & Cookie Class:
  Introduced several new methods for improved session and cookie management:

  • put - Queue data for storage.
  • save - Persist all queued data.
  • dequeue - Remove queued data.
  • commit - Lock storage to prevent further modifications.
  • is - Check session or cookie status.
  • attempt / attempts - Manage login attempts.
  • regenerate - Regenerate session/cookie ID.
  • login - Alias for synchronize, initiates login and metadata storage.
  • logout - Alias for terminate, ends session and clears metadata.
  • isOnline - Alias for online, checks login status.
  • Getters - Retrieve session metadata (e.g., getToken, getUserAgent, getId).

• Database Query Builder:
  Added support for database locking:

  • lock - Lock the database for the current session.
  • unlock - Unlock the database.
  • isLocked - Check if the database is locked.

• Error Handling:
  Added depreciate method in Luminova\Errors\ErrorHandler:

  • Triggers an error in development.
  • Logs the error in production.

• Session Save Handlers:
  Added Luminova\Session\Handlers\ArrayHandler for temporary session storage, useful for debugging or short-lived sessions.

Optimizations

Optimized Since 3.5.5

HTTP Request Object

• getQuery() — Optimized method with added support for retrieving a query parameter by name. Introduced $name and $default arguments to simplify value access with fallback.

Fiber Async

• await() — Improved performance and flexibility by introducing optional $delay and $maxWait arguments for fine-grained control over async execution.

Private File Delivery Handler

• Enhanced file delivery logic for improved browser caching and more efficient handling of large files.

File Uploader Class

• Optimized handling of blob (raw binary) content when uploading via the Luminova\Http\File object.
• Added user-friendly feedback messages based on upload status and error codes for better developer experience.

Optimized Since 3.5.4

Sitemap Generator Configuration

• Added support for global pattern matching using @(pattern) in the ignoreUrls and skipStaticHtml config properties.
• Improved performance and memory usage.
• Enhanced skipped-page reporting and better handling of execution time limits.

Optimized Since 3.5.3

Database Query Builder

The query builder received significant performance improvements, including optimized driver initialization and connection management.

• exec - Method signature changed to static.
• on - Supports lateral values like '"value"' or raw expressions when joining; any non-expression is treated as a column name.
• where - Improved to accept arrays for IN (...) and optional NOT for NOT IN (...).
• datetime - Now supports timezone-aware formatting.
• returns - Can now return the raw prepared statement using stmt().
• printDebug - Enhanced to output debug info conditionally based on the environment.
• insert - Updated to support automatic handling of duplicate key behavior (update or ignore).

Optimized Since 3.5.2

• Database Query Builder

  • on - Now supports multiple join conditions.
  • update - Allows updating tables with join conditions.
  • query - Method signature changed to static.

• HTTP Request Class

  • getFile - Optimized multipart handling for multiple file uploads, including support for field names like file[].
  • constants - Replaced HTTP method literal strings with constants (Request::GET, etc.).

Optimized Since 3.5.1

• Command Utilities (Terminal Class): Optimized existing methods and introduced additional parameters where necessary.
  • chooser - Added a new boolean parameter $multiChoice to determine whether multiple options can be selected.
  • input - Added a new string parameter $default to specify a default return value for user input.
  • clear - Added a new string parameter $mode to control the clearing behavior:
  • default (default): Clears the entire screen.
  • partial: Clears from the cursor position downward.
  • full: Clears the entire screen and scrollback buffer.

Optimized Since 3.5.0

• Session & Cookie Class:

  • Unified handling of session and cookie storage.
  • Improved session ID regeneration.
  • Automatic login metadata creation on synchronize or login.
  • Optimized start method for session-cookie management and error handling.

• Database Drivers:

  • Improved error handling for Luminova\Database\Drivers\MysqliDriver and Luminova\Database\Drivers\PdoDriver.

Bug Fixes

Fixed Since 3.5.5

System Routing Class

Fixed an issue caused by getFirst() where accessing a document-root URI like https://example.com/public in production incorrectly triggers an error. It now correctly returns a 404 Not Found.

Fixed Since 3.5.4

Database ORM Builder

• Fixed a memory exhaustion issue in the Builder::exec(...) method caused by a recent update.

Fixed Since 3.5.1

• Command Text Utils Class: Fixed an issue where text containing emojis would overlap when using the block and card methods to create CLI output layouts.

• Input Validation Class: Fixed an issue where the keys_exists and keys_exist validation rules incorrectly failed when the value was 0, even if it existed.

Renamed

Renamed Since 3.5.3

HTTP Request Class

• isAJAX → isAjax

Database Query Builder

• andGroup → andConjoin
• orGroup → orConjoin
• andBind → andNested
• orBind → orNested

Deprecated

Deprecated Since 3.5.4

HTTP Upload File Object

• getMimeFromTemp - Deprecated. Use getMimeFromFile instead.

Deprecated Since 3.5.1

• Deprecated PHP Constant: Removed the deprecated E_STRICT constant to prevent unnecessary warnings.

Deprecated Since 3.5.0

• Session & Cookie Class:
  The following methods are deprecated from Luminova\Sessions\Session:

  • toExport → Use getResult.
  • ssid → Use getToken.
  • ssDate → Use getDatetime.

• Command Line Helper (Terminal Class):

  • color is deprecated.
  • Use Luminova\Command\Utils\Color::apply(...) or Luminova\Command\Utils\Color::style(...) for CLI text formatting.

• Encryption Helper Class:

  • verify is deprecated.
  • Use Luminova\Security\Crypter::isPassword(...) instead for password hash verification.

• Routing System:

  • before is deprecated.
  • Use Luminova\Routing\Router->guard(...) instead for CLI middleware authentication.

To-Do List

To-Do Since 3.5.5

Update the Logger Configuration Class to support automatic context enrichment by adding the following properties:

• $contextHeaderName — The name of the HTTP request header to automatically include in the log context.
• $contextFieldName — The name of the request body field to automatically include in the log context (Any HTTP method is supported).

These properties allow you to globally configure which values should be captured from requests and included in log entries, improving traceability and debugging—especially in production environments.

// /app/Config/Logger.php

namespace App\Config;

use Luminova\Base\BaseConfig;

final class Logger extends BaseConfig
{
  /**
   * Header name to extract and include in log context.
   * 
   * @var string|null
   */
  public static ?string $contextHeaderName = null;

  /**
   * Field name from request body to include in log context.
   * 
   * @var string|null
   */
  public static ?string $contextFieldName = null;
}

To-Do Since 3.5.4

Update sitemap generator configuration class to include property $maxExecutionTime:

// /app/Config/Sitemap.php

namespace App\Config;

use Luminova\Base\BaseConfig;

final class Sitemap extends BaseConfig
{
  /**
   * @var int $maxExecutionTime
   */
  public int $maxExecutionTime = 300;
}

To-Do Since 3.5.0

• Session Namespace Update:
  Renamed session namespaces for clarity:

  • Luminova\Sessions\Handler\* → Luminova\Sessions\Handlers\*.
  • Luminova\Sessions\Manager\* → Luminova\Sessions\Managers\*.

• Session Configuration:
  Introduced a new property to enable or disable cookie data encryption:

// /app/Config/Session.php

namespace App\Config;

use Luminova\Base\BaseConfig;

final class Session extends BaseConfig
{
  /**
   * Enable cookie data encryption when managing sessions via `Luminova\Session\Managers\Cookie`.
   * If set to true, cookie data will be encrypted using the application encryption key and algorithm.
   *
   * @var bool $encryptCookieData
   */
  public bool $encryptCookieData = true;
}