Luminova Framework

PHP Luminova: PHPVCI Shared Module Autoloading

Last updated: 2026-11-15 09:49:26

Luminova Shared Modules enable multiple projects to run on a single shared framework installation. Core paths are resolved via `.luminova.php`, with strict version enforcement and configurable shared-loading behavior across environments.

Luminova Version Controller Interface (PHPVCI) allows multiple projects to use a single Luminova framework installation on the same server.

Instead of installing the framework separately in each project, you maintain one central installation and configure applications to reference it.

This approach reduces duplication, enforces consistency, and simplifies maintenance in multi-project environments.

Benefits

  • Reduces duplicate framework files across projects
  • Ensures all projects use the same framework version
  • Simplifies updates by maintaining a single codebase
  • Update once, apply everywhere

How It Works

A standard Luminova project loads all framework components from its local /system and /bootstrap directories.

With Shared Modules, this changes:

  • The project only keeps minimal startup files
  • Core framework code is loaded from a shared installation
  • .phpvci.php defines where the shared framework is located

Start local, extend from a shared core.


Required Files (Always Local)

Even when using PHPVCI autoloading, these files must exist inside every project:

  • system/Boot.php → Core boot loader for the application
  • system/plugins/* → Project-specific Composer dependencies

These files and project-specific files are never shared. They are always loaded locally.


Project Structure

/www/example.com/
├── app/
├── bin/
├── node/
├── public/
├── resources/
├── routes/
├── bootstrap/
├── system/
│   ├── Boot.php
│   └── plugins/
└── .phpvci.php

You may safely remove other files inside /system/ and bootstrap/ because they are loaded from the phpvci packages directory.

Note: If Boot.php or system/plugins/* is missing, the application will not start.


Packages Directory Structure

Luminova PHPVCI files are stored in a central directory outside the project.

/opt/phpvci.packages/releases/3.8.0/
├── bootstrap/
│   ├── Funcs/
│   │    ├── functions.php
│   │    └── (Other Helpers)
│   └── constants.php
└── system/
    └── Luminova.php
    └── (Other Modules Except for plugins)

The following are loaded from the shared installation:

  • bootstrap/* Helper functions and constants
  • system/* Luminova components and modules (Except for system/plugins/ and system/Boot.php)

Everything else remains project-local.


Configurations

During autoload startup, Luminova checks for file .phpvci.php in project root, based on paths.target and version, it control how framework modules are resolved.

This file allows you to:

  • Define shared framework package location
  • Enable or disable shared loading
  • Enforce framework version consistency

Configuration Example:

Boot reads .phpvci.php from your application root:

// /.phpvci.php
return [
    'enabled' => true,
    'version' => '^1.0.0',
    'paths' => [
        'target' => '/var/www/phpvci.packages',
    ],
];
KeyDescription
enabledMust be truthy for Luminova autoload system to use the configuration.
versionVersion constraint checked against Luminova::VERSION. A non-empty value is required for PHPVCI resolution.
pathsContains the shared target path.
paths.targetDirectory containing the shared system/ and bootstrap/ directories. Must be non-empty for PHPVCI resolution.

The target path is normalized by converting backslashes to forward slashes and adding a trailing slash. It is not prefixed with APP_BASE_PATH, so configure the path to the shared package directory.


Version compatibility

When PHPVCI is active, Luminova compares the configured version with Luminova::VERSION. An exact match passes immediately. Otherwise:

  • Plain versions such as 1.2.3 are compared for an exact match.
  • Operators such as >, <, >=, <=, ==, !=, and <> use PHP's version_compare() behavior. <> is treated as !=.
  • Constraints containing a space or beginning with ^ or ~ are checked with Version::satisfies().

If the active PHPVCI version constraint is not satisfied, application autoload stops execution.

'version' => '1.2.3',   // Exact version
'version' => '>=1.2.0', // Comparison operator
'version' => '^1.2.0',  // Version constraint

Note:

PHPVCI is not considered active when the version or target path is empty, so the version check is skipped in that case.


Admin Management

Luminova provides PHPVCI admin tools for managing shared framework installations and switching Luminova versions for individual projects. These tools include a command-line package installer and a single-file admin panel.

They allow you to install Luminova in a dedicated shared location, reducing disk usage while allowing multiple projects to use the same or different framework versions.

Luminova CLI Package Installer

The PHPVCI CLI package installer allows you to install Luminova in a dedicated shared location using simple commands:

phpvci package --install
phpvci package --install=3.8.0

It also provides additional commands for managing framework packages and the PHPVCI binary.

For more details, see the PHPVCI CLI Package Installation Manager.


Admin Panel Version Switcher

The PHPVCI admin panel is a single-file tool, phpvci.php, that you can place in your project's /public/ directory. It includes security and authentication features to protect access when exposed publicly.

The panel allows you to switch the Luminova framework version used by a specific project, similar to switching PHP versions. It also optimizes Composer configuration, downloads composer.phar when needed, and supports reverting to local autoloading by copying the required framework modules back into the project directory. When reverting to local autoloading, it disables the PHPVCI shared module feature without disrupting the application's normal execution.

For more details, see the PHPVCI Admin Panel UI.