⚡ ZAP CLI

A lightweight PHP command-line interface (CLI) framework for building modular, easy-to-use console applications.

Features

• Simple Command Structure: Create commands by extending a base class with a handle() method
• Automatic Command Loading: Commands are auto-discovered from the Commands/ directory
• Nested Subcommands: Organize commands in subdirectories (e.g., user:create, user:list)
• Argument Parsing: Built-in support for named arguments (--key=value)
• Colored Output: Beautiful terminal output with color support (green, red, yellow, blue)
• Logging: Automatic logging of all command executions to logs/app.log
• Helper Functions: Utility methods for user interaction (pause, clear screen, etc.)

Installation

1. Clone or download this repository
2. Ensure PHP 7.4+ is installed
3. No external dependencies required!

Quick Start

Running Commands

# View all available commands
php zap help

# Run a command
php zap greet

# Run a command with arguments
php zap sum --a=5 --b=3

# Run a nested subcommand
php zap user:create
php zap user:list

Creating a Command

Basic Command

Create a file in src/Commands/ named YourNameCommand.php:

<?php

namespace App\Commands;

use App\Helpers;

class YourNameCommand
{
    public static string $description = "Description of what this command does";

    public static function handle(array $args): void
    {
        Helpers::info("Command started");
        Helpers::success("Success message");
        Helpers::error("Error message");
        Helpers::warn("Warning message");
    }
}

The command will be automatically registered as php zap yourname.

Nested Subcommands

Create a subdirectory in src/Commands/ and add commands inside:

src/Commands/
├── User/
│   ├── CreateCommand.php  → php zap user:create
│   └── ListCommand.php    → php zap user:list

Helper Functions

The Helpers class provides useful utilities:

use App\Helpers;

// Output with colors
Helpers::println("Text", 'green');   // Green text
Helpers::println("Text", 'red');     // Red text
Helpers::println("Text", 'yellow');  // Yellow text
Helpers::println("Text", 'blue');    // Blue text

// Status messages (auto-logged)
Helpers::success("Operation completed");  // ✔ Green
Helpers::error("Something went wrong");   // ✖ Red
Helpers::info("Information");             // ℹ Blue
Helpers::warn("Warning");                 // ! Yellow

// User interaction
Helpers::pause();           // Wait for Enter key
Helpers::clearScreen();     // Clear terminal
Helpers::line();            // Print separator line

// Argument parsing
$args = Helpers::parseArgs($input);

// Logging
Helpers::log("Message", 'INFO');
Helpers::log("Error occurred", 'ERROR');

Project Structure

cnsl/
├── zap                    # Entry point script
├── README.md              # This file
├── .gitignore             # Git ignore rules
├── logs/                  # Application logs (auto-created)
└── src/
    ├── Zap.php            # Main CLI framework
    ├── Helpers.php        # Utility functions
    └── Commands/          # Your commands go here
        ├── GreetCommand.php
        ├── SumCommand.php
        └── User/
            ├── CreateCommand.php
            └── ListCommand.php

How It Works

1. Entry Point: php zap loads the zap file
2. Autoloading: PSR-4 autoloader in zap file loads classes from src/
3. Command Discovery: Helpers::loadCommands() scans src/Commands/ for *Command.php files
4. Execution: The framework parses arguments and calls the command's handle() method
5. Logging: All operations are logged to logs/app.log

Argument Parsing

Arguments are passed using the --key=value format:

php zap sum --a=10 --b=20

Inside your command:

public static function handle(array $args): void
{
    $a = $args['a'] ?? 0;  // Access as associative array
    $b = $args['b'] ?? 0;
    echo $a + $b;
}

Logging

All messages logged via Helpers::log(), Helpers::success(), Helpers::error(), Helpers::info(), and Helpers::warn() are automatically written to logs/app.log with timestamps and log levels.

License

MIT