README

Conso（PHP控制台应用程序，专为酷炫孩子们设计）。

🔥 简介

Conso是一个简单、轻量级的PHP包，帮助您轻松创建（可执行、.phar、可分享）命令行应用程序。

💥 它真的轻量吗？

📌 要求

• PHP >= 7.2 或更高版本
• PHPUnit >= 8（用于测试目的）

🚀 安装

• 通过composer

composer require lotfio/conso

• 用于测试

composer test

🎉 编写您的第一个命令

• 创建一个commands.php文件。
• 创建一个conso文件（您可以根据需要更改名称）。
• 将您的commands.php文件包含到conso可执行文件中。
• 它应该看起来像这样。

#!/usr/bin/env php
<?php declare(strict_types=1);

use Conso\{
    Conso,Input,Output
};

require 'vendor/autoload.php';

$conso = new Conso(new Input, new Output);

// include your commands
require_once 'commands.php';

$conso->run();

⭐ 可用的配置方法

<?php

$conso->setSignature(); // set application signature (top logo)
$conso->setName();     // set application name
$conso->setVersion(); // set application version
$conso->setAuthor(); // set application author
$conso->disableBuiltInCommands(); // disable builtin commands

• 现在在您的commands.php中定义一个新的test命令

<?php
// this is your commands file

// test command
$conso->command("test", function($input, $output){
    $output->writeLn("\n hello from test \n", 'red');
});

• 现在您的命令已经注册。
• 在终端中运行php conso --commands或./conso --commands，您应该能看到您的命令。

• 命令test已注册现在 （未显示描述，您稍后可以添加此描述）。
• 运行您的命令 php conso test 或 ./conso test。

⭐ 添加描述

• ->description(string $description);

<?php
// test command
$conso->command("test", function($input, $output){
    $output->writeLn("\n hello from test \n", 'red');

})->description("This is test command description :) ^^");

⭐ 定义子命令

• ->sub(string|array $subCommand);

<?php
// test command
$conso->command("test", function($input, $output){

    if($input->subCommand() == 'one')
        exit($output->writeLn("\n hello from one \n", 'yellow'));

    if($input->subCommand() == 'two')
        $output->writeLn("\n hello from two \n", 'green');

})->description("This is test command description :) ^^")->sub('one', 'two');

⭐ 定义命令标志

• 您可以使用flag方法->flags(string|array $flag)定义标志
• 这是保留标志列表 ['-h', '--help', '-v', '--version', '-c', '--commands', '-q', '--quiet', '--ansi', '--no-ansi']
• 对于调试，您可以使用-vv或--verbose标志来获取有关错误的更多详细信息
• 您还可以将值传递给标志 --flag=value 或 -f=value

<?php
// test command
$conso->command("test", function($input, $output){

    if($input->flag('-t') !== false)
        $output->writeLn("\n flag -t is defined for this command.\n", 'red');

    // you can get flag values
    // $output->writeLn($input->flag('-t'));

})->description("This is test command description :) ^^")->flags('-t');

⭐ 添加命令别名

• 您可以使用alias方法->alias(string $alias)为命令添加别名

<?php
// test command
$conso->command("test", function($input, $output){

    $output->writeLn("\n test called by alias \n", 'red');

})->description("This is test command description :) ^^")->alias('alias');

⭐ 定义命令帮助

• 您可以使用help方法->help(array $help)为命令添加帮助说明
• 您可以使用-h或--help标志显示命令帮助
• 帮助数组必须是包含子命令、选项和标志及其描述的数组

<?php
// test command
$conso->command("test", function($input, $output){

    $output->writeLn("\n test called by alias \n", 'red');

})->description("This is test command description :) ^^")->sub('one')->flags('-t')

  ->help([
      "sub commands" => [
          "one" => " help text for sub command goes here"
        ],
      "flags" => [
          "-t" => "help text for flag goes here"
        ]
  ]);

⭐ 组命令

• 您可以使用group()方法来组命令

<?php

$conso->group('my group of commands:', function($conso){

    $conso->command("command", function(){})->description('This is command description');
    $conso->command("test",    function(){})->description('This is command description');
    $conso->command("make",    function(){})->description('This is command description');

});

⭐ 类命令

• 类命令对于大型命令非常有用
• 首先您需要创建一个app/Commands文件夹。
• 您还可以将您的命令定义文件commands.php移动到app文件夹以清理项目。
• 不要忘记使用composer自动加载您的命令 psr-4{ "App\\" : "app" }
• 现在您需要将命令路径和命名空间添加到conso中，以便内置命令（command）可以自动为您创建命令。

    // add this to your conso file before run method
    $conso->setCommandsPath('app/Commands');
    $conso->setCommandsNamespace('App\\Commands');

• 要创建一个类命令，请运行php conso command:make {command name}
• 例如，让我们创建一个名为test的类命令 php conso command:make test
• 这将生成一个类似于以下所示的Test命令类

<?php

namespace App\Commands;

use Conso\{Conso, Command};
use Conso\Contracts\{CommandInterface,InputInterface,OutputInterface};

class Test extends Command implements CommandInterface
{
    /**
     * sub commands
     *
     * @var array
     */
    protected $sub  = [

    ];

    /**
     * flags
     *
     * @var array
     */
    protected $flags = [

    ];

    /**
     * command help
     *
     * @var array
     */
    protected $help  = [

    ];

    /**
     * command description
     *
     * @var string
     */
    protected $description = 'This is Test command description.';

    /**
     * execute method
     *
     * @param  InputInterface  $input
     * @param  OutputInterface $output
     * @return void
     */
    public function execute(InputInterface $input, OutputInterface $output) : void
    {
        commandHelp($this->app->invokedCommand, $output);
    }
}

• 现在您需要将此命令注册到您的commands.php文件中

$conso->command('test', Your\NameSpace\Test::class);

• 默认情况下，如果没有提供子命令，test命令将运行execute方法
• 每个子命令都是一个独立的方法

⭐ 从命令访问应用

• 从回调命令

<?php

// test command
$conso->command("test", function($input, $output){

    // get app config
    $this->getName();
    $this->getVersion();
    $this->getAuthor();
    $this->getCommandsPath();
    $this->getCommandsNamespace();

    // calling another command
    $this->call('command:subcommand -f --flags');
});

• 从类命令

<?php

    /**
     * execute method
     *
     * @param  InputInterface  $input
     * @param  OutputInterface $output
     * @return void
     */
    public function execute(InputInterface $input, OutputInterface $output) : void
    {
        // get app config
        $this->app->getName();
        $this->app->getVersion();
        $this->app->getAuthor();
        $this->app->getCommandsPath();
        $this->app->getCommandsNamespace();

        // calling another command
        $this->app->call('command:subcommand -f --flags');
    }

⭐ 命令命名空间

• 您可以使用 namespace() 方法将命令包裹在相同的命名空间中，这样可以使代码更加整洁。

<?php

$conso->namespace('Conso\\Commands', function($conso){

    // all commands withing Conso\Commands namespace
    $conso->command("command", Command::class);
    $conso->command("test",    Test::class);
    $conso->command("make",    Make::class);

});

⭐ HTTP 支持

• 您只需将命令传递给输入实例，就可以通过浏览器或任何 HTTP 客户端调用 conso。

<?php declare(strict_types=1);

use Conso\{
    Conso,Input,Output
};

require 'vendor/autoload.php';

// you can sanitize and pass your command her
$command = 'command:make HttpCommand';

$input   = new Input($command);

$conso   = new Conso($input, new Output);

require 'commands.php';

$conso->run();

⭐ 将您的应用程序编译为可共享的单个 .phar 文件

• 您可以从 2.0 版本及以上使用此功能。
• 要编译应用程序并创建可共享的 .phar 文件，请使用内置的 compile 命令。
• 运行 php conso compile:init 创建 conso.json 构建文件。

• 这将生成一个类似以下的 JSON 文件

{
    "src": [ /* your pacakge directories to compile should be added here */
        "src\/Conso", 
        "vendor" /* package dependencies if any */
    ],
    "build": "build", /* build location */
    "stub": "conso",  /* stub file (the entry point of your phar) */
    "phar": "conso.phar" /* output (your phar file name) */
}

• 您的存根文件应该看起来像这样

<?php // no need for shebang it will be added automatically 

declare(strict_types=1);

use Conso\{
    Conso,Input,Output
};

require 'vendor/autoload.php';

$conso = new Conso(new Input, new Output);

$conso->setName("app name");
$conso->setVersion("2.0.0");

$conso->setSignature(" app signature ");

$conso->disableBuiltInCommands(); // disable conso built in commands

// include your commands
// require 'app/commands.php';

$conso->run();

• 现在，您可以运行 php conso compile，您的软件包将被编译为 phar 文件。

• 您可以使用 --no-shebang 标志来避免在 phar 文件中添加 shebang（如果您想通过 http 调用 phar 文件，这很有用）

⭐ 测试助手

• 您可以使用 Conso\Testing\TestCase 测试助手类进行测试，该类可以帮助您
  • 打开测试模式（返回结果而不是输出到 STDOUT）。
  • 禁用 ANSI 颜色，这在测试时不需要。

✨ 待办事项

• 提高代码质量。

✨ 贡献

感谢您考虑为 Conso 贡献。所有贡献指南都列在 这里。

💖 支持

如果这个项目帮助您减少了开发时间，您可以请我喝杯咖啡 :) : Paypal。

✨ 许可证

Conso 是一个开源软件，许可协议为 MIT 许可证。