README

# Luna Framework A **modern PHP framework** designed for flexibility, modularity, and maintainability. **Lightweight**, **Scalable**, and **OOP-first** - Simplifying complex application development on PHP **8.2**.

[[TOC]]

ℹ️ About the Project

Luna Framework is a modular PHP framework inspired by Symfony, but with a tailored approach that enables scalability and better adaptation to modern PHP standards.
The framework’s core focus lies in simplicity, extensibility, and developer productivity.

This project is actively developed in PHP 8.2, leveraging features such as strict typing, attributes, and much more.

Detailed documentation is available in the Wiki: Luna Wiki.

Key Features

Configurable Architecture: Supports modular configuration through JSON, YAML, and PHP files.
PSR-4 Compliant: Fully autoloadable and adheres to PSR-4 standards for seamless integration.
Typed Syntax and OOP Design: Uses the latest PHP 8.2 features for strong typing, safety, and readability.
Custom Dependency Management: Manage and resolve custom modules via the Lock and LunaLock components.
Error Management: Precise exception handling for configurations, files, and runtime errors.

🗂️ Directory Structure

Luna Framework organizes its file structure for maintainability and scalability:

📂 luna/
 ├── 📂 bin/          # Executable scripts
 ├── 📂 config/       # Configuration files
 ├── 📂 resources/    # Resource files (e.g., assets, views)
 ├── 📂 src/          # Core framework source code
 ├── 📂 tests/        # Automated test cases
 ├── 📂 vendor/       # Composer dependencies
 └── 📄 README.md     # Documentation for the project

🔧 Dependencies

It uses PHP 8.2+, ensuring support for the latest features, and requires minimal setup to get started.

Luna Framework depends on the following:

Monolog: Comprehensive logging functionality.
(MIT License)
Symfony YAML: Reads and writes YAML configurations.
(MIT License)
Developer tools for testing:
- PHPUnit

Refer to the composer.json file for additional details.

⚙️ Setup and Installation

To use the Luna framework in your project, follow these steps:

Step 1: Install via Composer

First, ensure you have Composer installed in your system.
Run the following command in your project's root directory:

composer require shiros/luna

Once installed, you can configure your project’s environment in the directory /config.

Step 2: Autoload the framework

The module supports PSR-4 autoloading. If you're using the Luna Framework, it's automatically available. Otherwise, make sure to include Composer's autoloader:

require 'vendor/autoload.php';

Create a Project Using Luna

To kickstart your development with Luna Framework, use the Luna Skeleton as a base. It is a pre-configured project template designed to minimize setup and maximize productivity.

Follow these steps:

First, visit the Luna Skeleton repository for additional details and latest resources.
Run the following command to create a new Luna project:

composer create-project shiros/luna-skeleton your-project-name

Navigate into your newly created project folder:

cd your-project-name

Start configuring your project by updating environment files located under /config.

Your new project should now be ready to use Luna Framework!

🚀 Usage Example

Refer to the official documentation for advanced examples and further details.

Registering kernel

The Luna Framework kernel is easy to load. Here's an example on how to do it:

use Luna\Component\Lock\LunaLock;
use Luna\Kernel;
use Luna\KernelInterface;

try {
    /**
     * Create Luna kernel options.
     * Options let you customize the kernel.
     * 
     * - KernelInterface::OPT_ENVIRONMENT: Allows specifying a custom environment file / instance.
     * - KernelInterface::OPT_LOCK       : Allows specifying a custom lock file.
     * - KernelInterface::OPT_STANDALONE : Deactivate Luna's modules loading.
     */
    $options = [
        // Environment 
        KernelInterface::OPT_ENVIRONMENT => '/path/to/env_file',
        KernelInterface::OPT_ENVIRONMENT => [ 'key1' => 'value1' ],
                  
        // Lock 
        KernelInterface::OPT_ENVIRONMENT => '/path/to/lock_file.lock',
        KernelInterface::OPT_ENVIRONMENT => new LunaLock(),
        
        // Mode
        KernelInterface::OPT_STANDALONE => true, // By default, the standalone mode isn't enabled.
    ];

    /**
     * Create a Luna Kernel instance.
     * You can pass options to customize the kernel.
     */
    $kernel = new Kernel();
    // $kernel = new Kernel($options);
    
    /**
     * Starts the kernel as a Web handler.
     * You could do that only if the module 'shiros/web' is installed.
     */
    $kernel->start();
} catch (Throwable $e) {
    echo 'Error: ' . $e->getMessage();
}

Handling Configuration Files

Luna Framework supports multiple configuration formats. Here's an example on how to use it:

use Luna\Config\Config;

try {
    // Create a config instance
    $config = new Config();
    
    /**
     * Load your config folder.
     * Loads 'config/app.php', 'config/services.php', etc.
     */
    $config->load(
        path : __DIR__ . '/config', 
        files: ['app', 'services']  // Target files. Configuration files to load
    );

    // Show the configuration
    var_dump($config->all());
} catch (Throwable $e) {
    echo 'Error: ' . $e->getMessage();
}

Registering and Resolving Modules

Here's an example of how Luna Framework manages module registration with Lock and LunaLock :

use Luna\Component\Lock\Entity\LockModule;  
use Luna\Component\Lock\LunaLock;

$lockFilePath = __DIR__ . '/var/luna.lock'; // Path to your lock file

try {
    // Create LunaLock instance
    $lunaLock = new LunaLock($lockFilePath);
    
    // Adds a new module
    $newModule = new LockModule(
        name   : 'example/module',
        version: '1.0.0',
        class  : 'Example\\Module\\Class'
    );
    $lunaLock->addModule($newModule);

    // Get all registered modules
    $modules = $lunaLock->getModules();
    var_dump($modules);
} catch (Throwable $e) {
    echo 'Error: ' . $e->getMessage();
}

This example demonstrates how modules are dynamically loaded and saved using the framework's Lock system.

📄 Testing

This project uses PHPUnit for testing, you can run the test suite as follows.

Step 1: Install development dependencies

Before running the test suite, ensure all project dependencies, including development dependencies, are installed. Use Composer** to handle this:

composer install

This command will fetch all the required libraries and ensure your project setup is complete.

Step 2: Execute the Test Suite

Once dependencies are installed, you can execute the test suite using PHPUnit.
This ensures all the functionality of the framework is working as expected:

vendor/bin/phpunit --configuration phpunit.xml --colors=always

The test results will be displayed in your console. Colored output simplifies understanding the testing status:

Green: Tests passed successfully.
Red: Tests failed.
Yellow: Warnings or skipped tests.

For more details on the tests, explore the /tests directory. It contains comprehensive unit tests covering various parts of the framework.

📃 License

This project is licensed under the MIT License, allowing you to use and modify this project freely.
See the LICENSE file for more details.

👨‍💻 Authors and Contributors

This project was created and is maintained by Alexandre Caillot (Shiroe_sama), with contributions from the community.

Authors

Alexandre Caillot (Shiroe_sama)

Contributors

We thank the following contributors for making this project better:

Maxime Mazet (ElBidouilleur)

shiros / luna

Maintainers

Details