Integrating Lightna with a Magento Project

System Requirements

Ubuntu or macOS
PHP 8.1, 8.2, or 8.3
Required PHP extensions: pdo, yaml, redis, ctype

Setup Magento Project

You need to have a working Magento project before plugging Lightna into it.

Create Lightna Entry Folder

If the Magento entry is in the root of your repository, create lightna folder there:


├── app
├── bin
├── lightna
├── pub
└── var

Otherwise, create lightna folder outside of Magento:


├── lightna
└── magento

Alternatively, you can make Lightna a separate repository if it suits your needs, for example, to set up an independent deployment flow for Lightna.

Create New Composer Project

Go to lightna folder and create a new composer project:

composer init --no-interaction --name="internal/lightna-project" --type="project"

Add Required Composer Packages

composer require lightna/magento-pack
composer require --dev phpunit/phpunit

Make Entry Files

cp -r vendor/lightna/magento-pack/entry/. .
cp edition/main/sample.config.php edition/main/config.php
cp edition/main/sample.env.php edition/main/env.php

Configure Lightna Entry

Edit config.php and env.php in edition/main folder, follow the comments to verify and finish the configuration. Make sure there is no **** left in the files after edits.

Add generated assets folder (pub/lightna) into Magento .gitignore

Additional Modules

If needed on the project, add the following packages:

composer require lightna/redis - Redis storage support
composer require lightna/elasticsearch - Elasticsearch support
composer require lightna/magento-staging - Magento staging functionality support (required when staging modules are enabled in Magento)

Add newly installed packages to the enabled modules in edition/main/config.php

Configure Indices

If not all indices are needed at the beginning of the project, some of the indexes can be disabled.

Product pages use: product, content_product.

Category page uses: category, content_category

CMS page uses: cms

custom_redirect is used to handle not related to a specific entity redirects

To disable an unnecessary index, set entity.[entity_name].index => null in edition/main/config.php, See the example below:

    ...
    'entity' => [
        'category' => [
            'index' => null,
        ],
    ],
    ...

Install & Build

make install
make build

Be aware, after a successful build it can be replaced only by another successful build. If you need to slightly change the configuration, use make config.apply

Initialize Storages

By default, your index will be generated in the OPcache storage. To configure storage differently, refer to the configuration documentation.

make schema.update

Run this command every time you change storages configuration or update the project

Initialize Indices

./cli index.update.all

Setup `lightna_entry` in Magento

Create the Lightna configuration file in Magento at app/etc/lightna.php with the following content:

<?php
 
return [
    // Specify the correct path to the Lightna entry folder
    'lightna_entry' => __DIR__ . '/../../lightna',
];

Install Lightna_Frontend Magento Module

Run in the Magento root:

composer require lightna/magento-module-frontend --no-update && composer update lightna/magento-module-frontend

Enable the Lightna_Frontend Magento module using php bin/magento setup:upgrade. If you see the error Cannot process definition to array for type enum, it means that Lightna_Frontend is not yet enabled.

Setup Lightna Indexer Cron Job

* * * * * { cd [lightna_entry_path] && ./cli index.queue.watch; } 2>&1 >> [logs_path]/lightna-index.log

The index.queue.watch command applies changes immediately and continues monitoring for new changes until the end of the minute. This behavior can be adjusted via configuration. Alternatively, you can use index.queue.process if you need the indexer to process the queue explicitly once per minute.

Configure Images

At the given moment, Lightna does not resize images on its own but instead triggers Magento to perform the resizing. Since Magento does not resize images that are not registered in the theme, you need to ensure that image sizes are aligned between Magento and Lightna. To make Lightna use the image sizes from your design, make sure the sizes are registered in the Magento theme and properly configured in Lightna.

You can configure Lightna's image sizes in the YAML file as follows:

indexer:
  product:
    image:
      tile: { width: 285, height: 354 }
      thumbnail: { width: 100, height: 124 }
      preview: { width: 535, height: 664 }

Consider Lightna Lane

If you plan to use Lightna Lane, for example, to render a header or footer with Lightna on Magento pages, you can find an example in the lightna/magento-theme-lane package, which is currently in development.

Enable Lightna Rendering

Rename pub/index.php in Magento to pub/magento_index.php, then create a new pub/index.php file that requires Lightna's index.php:

<?php
 
require '../lightna/index.php';

Alternatively, create a symlink pub/index.php pointing to Lightna's index.php.

Verify Scope Resolving

By default, Lightna resolves scope based on the standard MAGE_RUN_CODE and falls back to store ID 1 if the run code isn't specified.

If you see: Exception: Config data for scope 1 not found, it means that the run code is unset, or you don’t have an active store with ID 1.

To customize scope resolution behavior, you can create a plugin for the Lightna\Magento\App\Scope::resolve method.

Bypassing Specific Stores

Sometimes, it makes sense to keep certain stores rendered by Magento. In that case, the following plugins are recommended:

Lightna\Engine\App\Router::canBypass - to bypass stores that will be rendered by Magento.
Lightna\Magento\App\Scope::getList - to hide certain stores from Lightna to avoid unnecessary indexing.

Session

Lightna needs to be able to read the Magento session; therefore, its configuration must be aligned with Magento.

Out of the box, Lightna supports:

File and Redis storage
session.serialize_handler: php_serialize, php. It is recommended to use php_serialize for better performance.

By default, Lightna does not support Magento's session compression settings, which are enabled in Magento and triggered based on a size threshold. To ensure consistency, you can either:

Disable Magento compression:
session.redis.compression_library => 'none' and clear all existing sessions after deployment.
Add the necessary decompression by plugging into Lightna\Session\App\Session::readContent.

Using a local Lightna module, you can add a new storage type or implement additional settings to fit your project’s needs.

Configuration example:

<?php
 
return [
    ...,
    'storage' => [
        'session_redis' => [
            'options' => [
                'host' => 'localhost',
                'port' => 6379,
                'db' => 2,
                'data_type' => 'hash',
                'data_hash_field' => 'data',
            ],
        ],
        ...,
    ],
    'session' => [
        'handler' => 'redis',
    ],
    ...,
];

Elasticsearch

Align Lightna Elasticsearch settings with Magneto.