Download the PHP package maplephp/prompts without Composer

MaplePHP Prompts

PHP Prompts is a pretty, interactive, lightweight, and user-friendly CLI (Command Line Interface) PHP library designed for seamless use across Linux, Unix, Darwin, and Windows. It allows you to create and manage user prompts in a command-line environment, enabling the collection of various types of input with built-in validation and feedback.

Note that the prompt may not look as polished on Windows as on Unix, but it will work just as well.

Table of Contents

• Installation
• Usage Example
• Available Options
• Available Prompt Types
• Command instance
• Progress Bar
• Validation

Installation

To install PHP Prompts, use Composer:

Usage Example

Below is an example demonstrating how to use the PHP Prompts library to create interactive prompts and validate user input.

Step-by-Step Guide

1. Initialize

2. Set the Title and Description for the Prompts

   This step is optional but provides context for the user.

3. Define the Prompts

   Define the prompts and their respective settings, including type, message, validation rules, and error messages.

4. Execute the Prompt

   Prompt the user for input based on the defined prompts above. The collected user input will be saved in the $prompt variable.

Available Options

1. type

   • Description: Specifies the type of the prompt (e.g., text, password, toggle, select, list, continue, message, confirm).
   • Example: "type" => "text"

2. message

   • Description: The message or question displayed to the user.
   • Example: "message" => "Enter your full name"

3. default

   • Description: A default value for the prompt, used if the user does not provide input.
   • Example: "default" => "Your default value"

4. items

   • Description: An array of items to choose from, used with select type prompts.
   • Example: "items" => ["Option 1", "Option 2", "Option 3"]

5. validate

   • Description: Validation rules for the input. Can be an array of rules or a custom function.
   • Examples:
     • Length validation: "validate" => ["length" => [1, 200]]
     • Custom function validation:

6. error

   • Description: Error message or function to display when validation fails.
   • Examples:
     • Static message: "error" => "Input is required"
     • Custom function error:
7. confirm
   • Description: Message to display upon user confirmation, used with confirm type prompts.
   • Example: "confirm" => "Are you sure you want to continue?"

Available Prompt Types

Summary

• text: Prompts for regular text input.
• password: Prompts for masked password input.
• toggle: Asks a yes/no question.
• select: Provides a list of options for selection.
• list: Prompts for a comma-separated list of values.
• continue: Continue with input dependent on previous value
• message: Displays a message (no input).
• confirm: Asks for confirmation before proceeding.

Details

1. text

   • Description: Prompts the user for regular text input.
   • Usage Example:

2. password

   • Description: Prompts the user for password input, masking the characters as they are typed.
   • Usage Example:

3. toggle

   • Description: Asks the user a yes/no question.
   • Usage Example:

4. select

   • Description: Provides a list of options for the user to choose from.
   • Usage Example:

5. list

   • Description: Prompts the user for a comma-separated list of values.
   • Usage Example:

6. continue

   • Description: Continue with input dependent on previous value.
   • Usage Example:

7. message

   • Description: Displays a message to the user. This type does not collect input and will be excluded from the end result array.
   • Usage Example:
8. confirm
   • Description: Asks the user for confirmation before proceeding. Can display a custom confirmation message.
   • Usage Example:

These prompt types enable a variety of user interactions in a CLI environment, making it easy to collect and validate different kinds of input using the PHP Prompts library.

Command instance

You also execute some of the prompt above command directly with the Command class.

Progress Bar

The progress method of the Command class allows displaying a progress bar with customizable sleep intervals to indicate ongoing operations.

Validation and Error Handling

Each prompt can have validation rules and custom error messages. Validation can be defined using built-in rules (e.g., length, email) or custom functions. Errors can be specified as static messages or dynamic functions based on the error type.

Validation List

1. required

   • Description: Checks if the value is not empty (e.g., not "", 0, NULL).
   • Usage: "required" => []

2. length

   • Description: Checks if the string length is between a specified start and end length.
   • Usage: "length" => [1, 200]

3. email

   • Description: Validates email addresses.
   • Usage: "email" => []

4. number

   • Description: Checks if the value is numeric.
   • Usage: "number" => []

5. min

   • Description: Checks if the value is greater than or equal to a specified minimum.
   • Usage: "min" => [10]

6. max

   • Description: Checks if the value is less than or equal to a specified maximum.
   • Usage: "max" => [100]

7. url

   • Description: Checks if the value is a valid URL (http|https is required).
   • Usage: "url" => []

8. phone

   • Description: Validates phone numbers.
   • Usage: "phone" => []

9. date

   • Description: Checks if the value is a valid date with the specified format.
   • Usage: "date" => ["Y-m-d"]

10. dateTime

    • Description: Checks if the value is a valid date and time with the specified format.
    • Usage: "dateTime" => ["Y-m-d H:i"]

11. bool

    • Description: Checks if the value is a boolean.
    • Usage: "bool" => []

12. oneOf

    • Description: Validates if one of the provided conditions is met.
    • Usage: "oneOf" => [["length", [1, 200]], "email"]

13. allOf

    • Description: Validates if all of the provided conditions are met.
    • Usage: "allOf" => [["length", [1, 200]], "email"]

14. float

    • Description: Checks if the value is a float.
    • Usage: "float" => []

15. int

    • Description: Checks if the value is an integer.
    • Usage: "int" => []

16. positive

    • Description: Checks if the value is a positive number.
    • Usage: "positive" => []

17. negative

    • Description: Checks if the value is a negative number.
    • Usage: "negative" => []

18. validVersion

    • Description: Checks if the value is a valid version number.
    • Usage: "validVersion" => [true]

19. versionCompare

    • Description: Validates and compares if a version is equal/more/equalMore/less... e.g., than withVersion.
    • Usage: "versionCompare" => ["1.0.0", ">="]

20. zip

    • Description: Validates ZIP codes within a specified length range.
    • Usage: "zip" => [5, 9]

21. hex

    • Description: Checks if the value is a valid hex color code.
    • Usage: "hex" => []

22. age

    • Description: Checks if the value represents an age equal to or greater than the specified minimum.
    • Usage: "age" => [18]

23. domain

    • Description: Checks if the value is a valid domain.
    • Usage: "domain" => [true]

24. dns

    • Description: Checks if the host/domain has a valid DNS record (A, AAAA, MX).
    • Usage: "dns" => []

25. matchDNS

    • Description: Matches DNS records by searching for a specific type and value.
    • Usage: "matchDNS" => [DNS_A]

26. equal

    • Description: Checks if the value is equal to a specified value.
    • Usage: "equal" => ["someValue"]

27. notEqual

    • Description: Checks if the value is not equal to a specified value.
    • Usage: "notEqual" => ["someValue"]

28. string

    • Description: Checks if the value is a string.
    • Usage: "string" => []

29. equalLength

    • Description: Checks if the string length is equal to a specified length.
    • Usage: "equalLength" => [10]

30. lossyPassword

    • Description: Validates password with allowed characters [a-zA-Z\d$@$!%*?&] and a minimum length.
    • Usage: "lossyPassword" => [8]

31. strictPassword

    • Description: Validates strict password with specific character requirements and a minimum length.
    • Usage: "strictPassword" => [8]

32. pregMatch

    • Description: Validates if the value matches a given regular expression pattern.
    • Usage: "pregMatch" => ["a-zA-Z"]

33. atoZ

    • Description: Checks if the value consists of characters between a-z or A-Z.
    • Usage: "atoZ" => []

34. lowerAtoZ

    • Description: Checks if the value consists of lowercase characters between a-z.
    • Usage: "lowerAtoZ" => []

35. upperAtoZ

    • Description: Checks if the value consists of uppercase characters between A-Z.
    • Usage: "upperAtoZ" => []

36. isArray

    • Description: Checks if the value is an array.
    • Usage: "isArray" => []

37. isObject

    • Description: Checks if the value is an object.
    • Usage: "isObject" => []
38. boolVal
    • Description: Checks if the value is a boolean-like value (e.g., "on", "yes", "1", "true").
    • Usage: "boolVal" => []

Usage Example

Here is an example of how to use the validation functions in the prompt library:

Conclusion

PHP Prompts provides a straightforward way to create interactive command-line interfaces in PHP. By defining prompts, validation rules, and error messages, developers can easily gather and validate user input in a CLI environment.