Object Manager

Most of the objects and dependencies in the Lightna codebase are managed by the internal Object Manager (OM). You don’t need to handle object creation manually — just declare dependencies as class properties with their types.

Key benefits

• Dependencies are lazy-initialized — instances are created only on first access, keeping the code optimized and clean without the need for custom lazy implementations.
• Classes don’t need a __construct method for dependency injection, improving extendability, version compatibility, and allowing proper lazy initialization.
• Simple runtime caching — store method results in properties to avoid redundant calculations. Lightna OM simplifies this by allowing you to declare a define[PropertyName] method, ensuring lazy initialization only once.
• OM handles additional routines, simplifying development. For example, accessing configuration values requires only an @AppConfig(path/to/value) PHPDoc annotation instead of extra code.

Example:

<?php
 
declare(strict_types=1);
 
namespace Lightna\Magento\Backend\Index\Provider;
 
use Lightna\Engine\App\ObjectA;
use Lightna\Magento\Backend\App\Query\Cms\Page as MagentoCmsPage;
use Lightna\Magento\Backend\App\Query\Config as MagentoConfig;
 
class Config extends ObjectA
{
    protected MagentoConfig $magentoConfig;
    protected MagentoCmsPage $magentoCmsPage;
    /** @AppConfig(backend:magento/configuration/list) */
    protected array $list;
    /** @AppConfig(backend:logo/default) */
    protected array $defaultLogo;
    /** @AppConfig(backend:favicon/default) */
    protected array $defaultFavicon;
 
    // ...
}

All properties in the class above are managed by OM and are lazy-loaded.

ObjectA	A base Lightna class that enables OM management. To exclude a class from OM, implement the Lightna\Engine\App\ObjectManagerIgnore interface.
@AppConfig	Specifies the path to a Lightna configuration value. If the config is specific to frontend or backend, it must be defined, or the compiler will fail if the value is undefined globally.

Object initialization

The __construct method is reserved by Lightna and cannot be overridden. Instead, use the protected init method for any setup needed after object creation. Avoid running code at instantiation unless necessary.

<?php
 
declare(strict_types=1);
 
namespace Vendor\Module;
 
use Lightna\Engine\App\ObjectA;
 
class MyClass extends ObjectA
{
    protected function init(array $data = []): void
    {
        // Your code here
 
        parent::init($data);
    }
}

External dependencies

OM does not automatically create external (non-Lightna) dependencies. Use the define method to initialize them:

<?php
 
declare(strict_types=1);
 
namespace Vendor\Module;
 
use Lightna\Engine\App\ObjectA;
use ThirdParty\Module\ExternalClass;
 
class MyClass extends ObjectA
{
    protected ExternalClass $externalClass;
 
    /** @noinspection PhpUnused */
    protected function defineExternalClass(): void
    {
        $this->externalClass = new ExternalClass([...]);
    }
 
    // ...
}

Transient Objects

By default, instances of the same class are shared. Use the define method with newobj when you need a new instance:

<?php
 
declare(strict_types=1);
 
namespace Vendor\Module;
 
use Lightna\Engine\App\ObjectA;
 
class MyClass extends ObjectA
{
    protected MySafeClass $mySafeClass;
 
    /** @noinspection PhpUnused */
    protected function defineMySafeClass(): void
    {
        $this->mySafeClass = newobj(MySafeClass::class, [...]);
    }
 
    // ...
}

Factory

Example of a factory implementation for StoragePool using newobj:

<?php
 
declare(strict_types=1);
 
namespace Lightna\Engine\App;
 
use Exception;
use Lightna\Engine\App\Storage\StorageInterface;
 
class StoragePool extends ObjectA
{
    protected array $adapters;
    /** @AppConfig(storage) */
    protected array $storages;
 
    public function get(string $code): StorageInterface
    {
 ...
        if (isset($this->adapters[$code])) {
            return $this->adapters[$code];
        }
 
        if (!isset($this->storages[$code])) {
            throw new Exception("Storage \"$code\" not found.");
        }
 
        $this->adapters[$code] = newobj(
            $this->storages[$code]['adapter'],
            $this->storages[$code]['options'],
        );
 
        return $this->adapters[$code];
    }
}

Accessing Lightna class externally

When building a Lightna frontend for a platform, you may need to reuse Lightna classes inside the platform, especially in Lightna Lane mode. To create an instance of a Lightna class, use the getobj function:

$myObject = getobj(MyClass::class, [...]);

Boot Lightna Object Manager externally

define('LIGHTNA_ENTRY', 'lightna/entry/path');
require LIGHTNA_ENTRY . 'vendor/lightna/engine/App/boot.php';

Register external Object Manager into Lightna

Lightna dependencies can be used alongside custom ones by registering a custom OM. This is not intended for frontend use during page rendering, but rather for better integration of Lightna classes within an external platform. Example of adding a custom OM into Lightna:

Lightna\Engine\App\ObjectManager::setProducer(
    'ExternalPlatform',
    function ($class) {
        return ExternalObjectManager::get($class);
    },
);

Applying changes

Object Manager requires an up-to-date compiled schema. In dev mode, when modifying class schemas, run make compile to apply changes.

Planned

The next release will improve development mode by enabling automatic schema updates, eliminating the need for manual compilation after each change.