README

PHP Prompts 是一个漂亮、交互式、轻量级且用户友好的 CLI（命令行界面）PHP 库，适用于 Linux、Unix、Darwin 和 Windows 系统的无缝使用。它允许您在命令行环境中创建和管理用户提示，内置验证和反馈，从而收集各种类型的输入。

请注意，在 Windows 上提示可能不如在 Unix 上看起来那么精致，但它的工作效果是一样的。

目录

• 安装
• 使用示例
• 可用选项
• 可用提示类型
• 命令实例
• 进度条
• 验证

安装

要安装 PHP Prompts，请使用 Composer

composer require maplephp/prompts

使用示例

以下是一个示例，展示了如何使用 PHP Prompts 库创建交互式提示并验证用户输入。

步骤指南

1. 初始化

$prompt = new MaplePHP\Prompts\Prompt();

1. 设置提示的标题和描述

   这一步是可选的，但为用户提供上下文。

   $prompt->setTitle("Hello there!");
   $prompt->setDescription("We need your contact information to stay in touch, thank you.");

2. 定义提示

   定义提示及其相应的设置，包括类型、消息、验证规则和错误消息。

   $prompt->set([
        "name" => [
            "type" => "text",
            "message" => "Full Name",
            "validate" => [
                "length" => [1,200]
            ]
        ],
        "email" => [
            "type" => "text",
            "message" => "Email",
            "validate" => [
                "length" => [1,200],
                "email" => []
            ],
            "error" => "The email address entered is not valid."
        ],
        "newsletter" => [
            "type" => "toggle",
            "message" => "Receive newsletter?",
        ],
        "method" => [
            "type" => "select",
            "message" => "Preferred contact method?",
            "items" => [
                "email" => "Email",
                "phone" => "Phone"
            ],
        ],
        "contactByPhone" => [
            "type" => "continue",
            "items" => function($prevVal) {
                if($prevVal === "phone") {
                    return [
                        "phone" => [
                            "type" => "text",
                            "message" => "Phone",
                            "validate" => [
                                "length" => [1,30],
                                "phone" => []
                            ]
                        ]
                    ];
                }
                return false;
            }
        ],
        "confirm" => [
            "type" => "confirm",
            "message" => "Do you wish to continue?"
        ]
   ]);

3. 执行提示

   根据上述定义的提示提示用户输入。收集到的用户输入将保存在 $prompt 变量中。

   // Execute the prompt
   $prompt = $prompt->prompt();
   // Print out the user inputs
   print_r($prompt); 

可用选项

1. type

   • 描述：指定提示的类型（例如，text、password、toggle、select、list、continue、message、confirm）。
   • 示例： "type" => "text"

2. message

   • 描述：显示给用户的消息或问题。
   • 示例： "message" => "Enter your full name"

3. default

   • 描述：提示的默认值，如果用户没有提供输入则使用。
   • 示例： "default" => "Your default value"

4. items

   • 描述：用于选择提示的项的数组，与 select 类型提示一起使用。
   • 示例： "items" => ["Option 1", "Option 2", "Option 3"]

5. validate

   • 描述：输入的验证规则。可以是规则数组或自定义函数。
   • 示例:
     • 长度验证： "validate" => ["length" => [1, 200]]
     • 自定义函数验证

       "validate" => function($input) {
           return strlen($input) >= 3;
       }

6. error

   • 描述：验证失败时显示的错误消息或函数。
   • 示例:
     • 静态消息： "error" => "Input is required"
     • 自定义函数错误

       "error" => function($errorType, $input, $row) {
           if ($errorType === "length") {
               return "Is required";
           }
           return "Must be a number";
       }

7. confirm

   • 描述：用于 confirm 类型提示的用户确认时的消息。
   • 示例： "confirm" => "Are you sure you want to continue?"

可用提示类型

总结

• text：提示常规文本输入。
• password：提示密码输入，输入的字符将被隐藏。
• toggle：询问是/否问题。
• select：提供选项列表供选择。
• list：提示逗号分隔的值列表。
• continue：根据先前值继续输入
• message：显示消息（无输入）。
• confirm：在继续之前请求确认。

详细信息

1. text

   • 描述：提示用户进行常规文本输入。
   • 使用示例:

     "firstname" => [
         "type" => "text",
         "message" => "First name"
     ]

2. password

   • 描述：提示用户进行密码输入，输入的字符将被隐藏。
   • 使用示例:

     "password" => [
         "type" => "password",
         "message" => "Password"
     ]

3. toggle

   • 描述：询问用户是/否问题。
   • 使用示例:

     "ssl" => [
         "type" => "toggle",
         "message" => "Do you want SSL?"
     ]

4. select

   • 描述：为用户提供一个选择列表。
   • 使用示例:

     "select" => [
         "type" => "select",
         "message" => "Select an item below",
         "items" => [
             "Lorem 1",
             "Lorem 2",
             "Lorem 3"
         ]
     ]

5. 列表

   • 描述：提示用户输入以逗号分隔的值列表。
   • 使用示例:

     "keyword" => [
         "type" => "list",
         "message" => "Keywords"
     ]

6. 继续

   • 描述：根据前一个值继续输入。
   • 使用示例:

     "continue" => [
        "type" => "continue",
        "items" => function($prevVal) {
           if($prevVal === "phone") {
               return [
                   "phone" => [
                       "type" => "text",
                       "message" => "Phone",
                       "validate" => [
                           "length" => [1,30],
                           "phone" => []
                       ]
                   ]
               ];
           }
           return false;
       }
     ]

7. message

   • 描述：向用户显示消息。此类型不收集输入，并将从最终结果数组中排除。
   • 使用示例:

     "message" => [
         "type" => "message",
         "message" => "Lorem ipsum dolor"
     ]

8. confirm

   • 描述：在继续之前询问用户确认。可以显示自定义确认消息。
   • 使用示例:

     "confirm" => [
         "type" => "confirm",
         "message" => "Do you wish to continue?"
     ]

这些提示类型允许在CLI环境中进行各种用户交互，使用PHP Prompts库轻松收集和验证不同类型的输入。

命令实例

您还可以使用Command类直接执行上述部分提示命令。

$command = new MaplePHP\Prompts\Command();
// Print messages and return input
$input = $command->message("Text field", true);
$input = $command->mask("Masked input (password)");
$input = $command->toggle("Toggle yes/no");
$input = $command->select("Choose a value", [
    //...
]);
$input = $command->list("Comma seperated list");
$input = $command->confirm("Confirm");

// Print messages
$command->message("Print message");
$command->title("Print bolded message");
$command->statusMsg("Print blue status message");
$command->approve("Print green approve message");
$command->approve("Print red error message");

进度条

Command类的progress方法允许显示带有自定义休眠间隔的进度条，以指示正在进行的操作。

$command = new MaplePHP\Prompts\Command();
$command->progress(1, 100, function($i, $length) {
    return 20;
});

验证和错误处理

每个提示都可以有验证规则和自定义错误消息。验证可以使用内置规则（例如，长度、电子邮件）或自定义函数定义。错误可以指定为静态消息或基于错误类型的动态函数。

验证列表

1. required

   • 描述：检查值是否不为空（例如，不是""、0、NULL）。
   • 用法："required" => []

2. length

   • 描述：检查字符串长度是否在指定的起始和结束长度之间。
   • 用法："length" => [1, 200]

3. email

   • 描述：验证电子邮件地址。
   • 用法："email" => []

4. number

   • 描述：检查值是否为数值。
   • 用法："number" => []

5. min

   • 描述：检查值是否大于或等于指定的最小值。
   • 用法："min" => [10]

6. max

   • 描述：检查值是否小于或等于指定的最大值。
   • 用法："max" => [100]

7. url

   • 描述：检查值是否为有效的URL（http|https是必需的）。
   • 用法："url" => []

8. phone

   • 描述：验证电话号码。
   • 用法："phone" => []

9. date

   • 描述：检查值是否为指定格式的有效日期。
   • 用法："date" => ["Y-m-d"]

10. dateTime

    • 描述：检查值是否为指定格式的有效日期和时间。
    • 用法："dateTime" => ["Y-m-d H:i"]

11. bool

    • 描述：检查值是否为布尔值。
    • 用法："bool" => []

12. oneOf

    • 描述：验证是否满足提供的条件之一。
    • 用法："oneOf" => [["length", [1, 200]], "email"]

13. allOf

    • 描述：验证是否满足提供的所有条件。
    • 用法："allOf" => [["length", [1, 200]], "email"]

14. float

    • 描述：检查值是否为浮点数。
    • 用法："float" => []

15. int

    • 描述：检查值是否为整数。
    • 用法："int" => []

16. positive

    • 描述：检查值是否为正数。
    • 用法："positive" => []

17. negative

    • 描述：检查值是否为负数。
    • 用法："negative" => []

18. validVersion

    • 描述：检查值是否为有效的版本号。
    • 用法："validVersion" => [true]

19. versionCompare

    • 描述：验证并比较版本是否相等/更大/更小等，例如，与thanWithVersion比较。
    • 用法："versionCompare" => ["1.0.0", ">="]

20. zip

    • 描述：验证指定长度范围内的ZIP代码。
    • 用法："zip" => [5, 9]

21. hex

    • 描述：检查值是否为有效的十六进制颜色代码。
    • 用法："hex" => []

22. age

    • 描述：检查值是否代表等于或大于指定最小值的年龄。
    • 用法："age" => [18]

23. domain

    • 描述：检查值是否为有效的域名。
    • 用法："domain" => [true]

24. dns

    • 描述：检查主机/域名是否有有效的DNS记录（A，AAAA，MX）。
    • 用法："dns" => []

25. matchDNS

    • 描述：通过搜索特定类型和值来匹配DNS记录。
    • 用法："matchDNS" => [DNS_A]

26. equal

    • 描述：检查值是否等于指定值。
    • 用法："equal" => ["someValue"]

27. notEqual

    • 描述：检查值是否不等于指定值。
    • 用法："notEqual" => ["someValue"]

28. string

    • 描述：检查值是否为字符串。
    • 用法："string" => []

29. equalLength

    • 描述：检查字符串长度是否等于指定长度。
    • 用法："equalLength" => [10]

30. lossyPassword

    • 描述：验证密码，允许字符 [a-zA-Z\d$@$!%*?&] 和最小长度。
    • 用法："lossyPassword" => [8]

31. strictPassword

    • 描述：验证具有特定字符要求和最小长度的严格密码。
    • 用法："strictPassword" => [8]

32. pregMatch

    • 描述：验证值是否匹配给定的正则表达式模式。
    • 用法："pregMatch" => ["a-zA-Z"]

33. atoZ

    • 描述：检查值是否由 a-z 或 A-Z 之间的字符组成。
    • 用法："atoZ" => []

34. lowerAtoZ

    • 描述：检查值是否由 a-z 之间的小写字符组成。
    • 用法："lowerAtoZ" => []

35. upperAtoZ

    • 描述：检查值是否由 A-Z 之间的大写字符组成。
    • 用法："upperAtoZ" => []

36. isArray

    • 描述：检查值是否为数组。
    • 用法："isArray" => []

37. isObject

    • 描述：检查值是否为对象。
    • 用法："isObject" => []

38. boolVal

    • 描述：检查值是否为类似布尔值（例如，“on”，“yes”，“1”，“true”）。
    • 用法："boolVal" => []

使用示例

以下是如何在prompt库中使用验证函数的示例

$inp->set([
    "firstname" => [
        "type" => "text",
        "message" => "First name",
        "validate" => [
            "length" => [1, 200],
            "required" => []
        ],
        "error" => "Required"
    ],
    "email" => [
        "type" => "text",
        "message" => "Email",
        "validate" => [
            "length" => [1, 200],
            "email" => []
        ]
    ],
    "age" => [
        "type" => "text",
        "message" => "Age",
        "validate" => [
            "number" => [],
            "min" => [18]
        ]
    ]
]);

结论

PHP Prompts 以简单直接的方式在PHP中创建交互式命令行界面。通过定义提示、验证规则和错误消息，开发人员可以轻松地在CLI环境中收集和验证用户输入。