README

# Luna Module - Console A PHP **Console Module** designed for managing and streamlining CLI operations in the **Luna Framework**. **Robust**, **Flexible**, and **Developer-Friendly** - Simplifying CLI-based workflow execution 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 Console Module facilitates command-line interactions by implementing tools and features that simplify CLI development.

Detailed documentation is available in the Wiki: Luna Console Wiki.

Key Features

CLI Command Management: Facilitates the creation and management of CLI commands.
Error Handling: Streamlined error reporting for smooth developer experience.
Flexibility: Thin yet powerful integration with the Luna ecosystem for CLI workflows.
PSR-4 Autoloading: Clean and autoloaded code structure.
PHP 8.2 Features: Implements the latest PHP features, promoting 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.

⚙️ Setup and Installation

To use the Luna Console 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-console

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.

Run the CLI

Here's a quick example of how to use the console to execute commands.

Go first in your project's directory.

cd <your_project_directory>;

Then, you could see which commands are available.

bin/console

To execute a command, follow the example below.

bin/console <my_command> [...args]

Create a command

Here's a quick example of a Luna command :

/**
 * Represents the declaration of the Luna command. 
 */
class TestCommand extends AbstractCommand
{
    # --------------------------------
    # Constants

    // Arguments
    protected const ARG_NAME = 'name';

    # --------------------------------
    # Configuration

    /**
     * @inheritDoc
     *
     * @throws CommandException
     * @throws InputDefinitionException
     */
    protected function configure(): void
    {
        $this
            ->setName(name: 'test:test')
            ->setDescription(description: 'This is a test command.')
            ->setDefinition([
                new InputArgument(name: self::ARG_NAME, mode: InputArgument::OPTIONAL, default: 'First argument.')
            ])
        ;
    }

    # --------------------------------
    # Core methods

    /**
     * @inheritDoc
     *
     * @throws ContainerException
     * @throws DependencyInjectorException
     * @throws ReflectionException
     */
    protected function execute(
        InputInterface  $input,
        OutputInterface $output
    ): int {
        // ----------------
        // Vars

        // Get constants
        $keyName = self::ARG_NAME;

        // Get arguments
        $name = $input->getArgument($keyName);

        // ----------------
        // Process
        
        // Build the console UI
        $ui = new OceanUI($input, $output);

        // Display some texts
        $ui
            ->section('Test - Display Argument')
            ->text('Hello world !')
        ;

        // Display argument
        if (!TypeManager::isEmpty($name)) {
            $ui->text("- Argument '{$keyName}' : {$name}");
        }

        return 0;
    }
}

Commands need to be registered in the configuration config/services/console under the section Commands

📄 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-console

Maintainers

Details