README

# Luna Module - System A PHP **System Module** designed for handling OS abstraction, filesystem operations, package management, and system bridges in the **Luna Framework**. **Robust**, **Portable**, and **Developer-Friendly** – Simplifying interaction with the underlying operating system in your PHP projects.

[[TOC]]

ℹ️ About the Project

This project is developed in PHP 8.2 and is part of the Luna Framework ecosystem.

The Luna System Module provides a structured way to interact with the operating system, manage files and directories, execute system commands, and handle package resources in a consistent and framework‑oriented way.

Detailed documentation is available in the Wiki: Luna Wiki.

Key Features

OS Abstraction Layer: Unified API for OS‑level features (Linux, Windows, etc.).
Filesystem Operations: High‑level helpers for reading, writing, copying, syncing, and removing files/directories.
Bridge‑Based Resolution: Smart bridge system to resolve the concrete OS implementation based on the runtime environment.
Package Management Utilities: Helpers for copying package files/directories, including template‑aware operations.
Command Execution: Integration with system executors for running shell commands safely.
Dependency Injection Integration: Seamless usage with Luna’s DI and container components.
PSR‑4 Autoloading: Clean and autoloaded code structure.
PHP 8.2 Features: Implements modern PHP features for clean, predictable code.

🔧 Dependencies

It uses PHP 8.2+, ensuring compatibility with modern features.

This module depends on the following:

Luna Framework: The Luna framework's core.
(MIT License)
Development tools:
- PHPUnit

Refer to the composer.json file for additional details.

🤖 AI Assistance

This project's .claude/CLAUDE.md only contains repository-specific overrides. The generic Luna rules (repository conventions, documentation, unit tests, releases, refactoring) are provided by the luna-agent sub-agent and its luna-* skills, maintained separately and installed globally:

shiros/ai/luna-agent

⚙️ Setup and Installation

To use the Luna System module, follow the steps below:

Step 1: Install via Composer

Ensure Composer is installed, then execute the following in your root project folder:

composer require shiros/luna-system

Autoloading is handled by Composer (PSR‑4). When used within a Luna application, the module is auto‑discovered via composer.json → luna.module:

{
    "luna": {
        "module": "Luna\\System\\Module"
    }
}

Step 2: Autoload the Module

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

require 'vendor/autoload.php';

🚀 Usage Example

Refer to the official documentation for advanced examples and further details about system bridges, OS utilities, filesystem helpers, and package operations.

📄 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: Create the test environment file

The test suite reads its environment from the path configured as ENV_PATH in phpunit.xml (./env.test, extension auto-detected). This file isn't committed, so create it locally by copying the committed template env.php.dist:

cp env.php.dist env.test.php

The env.php.dist file contains %TOKEN%-style placeholders (e.g. %LUNA_ENV%) that are resolved from system environment variables at runtime.

From there, you have two options:

Use system environment variables (recommended, matches what CI does) — export the tokens referenced by env.test.php before running the tests:
```
export LUNA_ENV=test
```
Edit the copy directly — replace the placeholder (s) in env.test.php with a literal value, e.g. 'Environment' => '%LUNA_ENV%' becomes 'Environment' => 'test'. Since env.test.php is a local, untracked copy, this never risks committing the value.

The CI pipeline runs the exact same copy step, with LUNA_ENV (and any future token) declared as a CI/CD variable. This keeps the pipeline script immutable — the only file to maintain when adding a new environment key (or secret) is env.php.dist.

Step 3: 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-system

Maintainers

Package info

Statistics

Security