{"id":22477551,"url":"https://github.com/maplephp/prompts","last_synced_at":"2025-08-02T13:31:03.432Z","repository":{"id":240768983,"uuid":"770051209","full_name":"MaplePHP/Prompts","owner":"MaplePHP","description":"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.","archived":false,"fork":false,"pushed_at":"2024-10-02T14:58:40.000Z","size":48,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-11-13T06:19:50.773Z","etag":null,"topics":["cli","cmd","command-line","command-line-interface","command-line-tool","cross-os","cross-platform","darwin","interactive","linux","php","pretty","prompt","terminal","unix","windows"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MaplePHP.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-10T19:30:19.000Z","updated_at":"2024-10-02T14:58:41.000Z","dependencies_parsed_at":"2024-05-20T20:47:21.076Z","dependency_job_id":"46f1c67f-7db7-42d1-b896-e118ed7f04dc","html_url":"https://github.com/MaplePHP/Prompts","commit_stats":null,"previous_names":["maplephp/prompts"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaplePHP%2FPrompts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaplePHP%2FPrompts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaplePHP%2FPrompts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaplePHP%2FPrompts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MaplePHP","download_url":"https://codeload.github.com/MaplePHP/Prompts/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228476038,"owners_count":17926134,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","cmd","command-line","command-line-interface","command-line-tool","cross-os","cross-platform","darwin","interactive","linux","php","pretty","prompt","terminal","unix","windows"],"created_at":"2024-12-06T14:11:31.007Z","updated_at":"2024-12-06T14:11:31.759Z","avatar_url":"https://github.com/MaplePHP.png","language":"PHP","readme":"# MaplePHP Prompts\n\nPHP 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.\n\n![Prompt demo](http://wazabii.se/github-assets/maplephp-prompt-v2.gif)\n\n_Note that the prompt may not look as polished on Windows as on Unix, but it will work just as well._\n\n### Table of Contents\n- [Installation](#installation)\n- [Usage Example](#usage-example)\n- [Available Options](#available-options)\n- [Available Prompt Types](#available-prompt-types)\n- [Command instance](#command-instance)\n- [Progress Bar](#progress-bar)\n- [Validation](#validation-and-error-handling)\n\n## Installation\n\nTo install PHP Prompts, use Composer:\n\n```bash\ncomposer require maplephp/prompts\n```\n\n## Usage Example\n\nBelow is an example demonstrating how to use the PHP Prompts library to create interactive prompts and validate user input.\n\n### Step-by-Step Guide\n\n1. **Initialize**\n\n```php\n$prompt = new MaplePHP\\Prompts\\Prompt();\n```\n\n2. **Set the Title and Description for the Prompts**\n\n   This step is optional but provides context for the user.\n\n   ```php\n   $prompt-\u003esetTitle(\"Hello there!\");\n   $prompt-\u003esetDescription(\"We need your contact information to stay in touch, thank you.\");\n   ```\n\n3. **Define the Prompts**\n\n    Define the prompts and their respective settings, including type, message, validation rules, and error messages.\n   ```php\n   $prompt-\u003eset([\n        \"name\" =\u003e [\n            \"type\" =\u003e \"text\",\n            \"message\" =\u003e \"Full Name\",\n            \"validate\" =\u003e [\n                \"length\" =\u003e [1,200]\n            ]\n        ],\n        \"email\" =\u003e [\n            \"type\" =\u003e \"text\",\n            \"message\" =\u003e \"Email\",\n            \"validate\" =\u003e [\n                \"length\" =\u003e [1,200],\n                \"email\" =\u003e []\n            ],\n            \"error\" =\u003e \"The email address entered is not valid.\"\n        ],\n        \"newsletter\" =\u003e [\n            \"type\" =\u003e \"toggle\",\n            \"message\" =\u003e \"Receive newsletter?\",\n        ],\n        \"method\" =\u003e [\n            \"type\" =\u003e \"select\",\n            \"message\" =\u003e \"Preferred contact method?\",\n            \"items\" =\u003e [\n                \"email\" =\u003e \"Email\",\n                \"phone\" =\u003e \"Phone\"\n            ],\n        ],\n        \"contactByPhone\" =\u003e [\n            \"type\" =\u003e \"continue\",\n            \"items\" =\u003e function($prevVal) {\n                if($prevVal === \"phone\") {\n                    return [\n                        \"phone\" =\u003e [\n                            \"type\" =\u003e \"text\",\n                            \"message\" =\u003e \"Phone\",\n                            \"validate\" =\u003e [\n                                \"length\" =\u003e [1,30],\n                                \"phone\" =\u003e []\n                            ]\n                        ]\n                    ];\n                }\n                return false;\n            }\n        ],\n        \"confirm\" =\u003e [\n            \"type\" =\u003e \"confirm\",\n            \"message\" =\u003e \"Do you wish to continue?\"\n        ]\n   ]);\n      ```\n4. **Execute the Prompt**\n\n    Prompt the user for input based on the defined prompts above. The collected user input will be saved in the `$prompt` variable.\n\n    ```php\n    // Execute the prompt\n    $prompt = $prompt-\u003eprompt();\n    // Print out the user inputs\n    print_r($prompt); \n    ```\n\n\n## Available Options\n\n1. **type**\n   - **Description**: Specifies the type of the prompt (e.g., `text`, `password`, `toggle`, `select`, `list`, `continue`, `message`, `confirm`).\n   - **Example**: `\"type\" =\u003e \"text\"`\n\n2. **message**\n   - **Description**: The message or question displayed to the user.\n   - **Example**: `\"message\" =\u003e \"Enter your full name\"`\n\n3. **default**\n   - **Description**: A default value for the prompt, used if the user does not provide input.\n   - **Example**: `\"default\" =\u003e \"Your default value\"`\n\n4. **items**\n   - **Description**: An array of items to choose from, used with `select` type prompts.\n   - **Example**: `\"items\" =\u003e [\"Option 1\", \"Option 2\", \"Option 3\"]`\n\n5. **validate**\n   - **Description**: Validation rules for the input. Can be an array of rules or a custom function.\n   - **Examples**:\n     - Length validation: `\"validate\" =\u003e [\"length\" =\u003e [1, 200]]`\n     - Custom function validation: \n       ```php\n       \"validate\" =\u003e function($input) {\n           return strlen($input) \u003e= 3;\n       }\n       ```\n\n6. **error**\n   - **Description**: Error message or function to display when validation fails.\n   - **Examples**:\n     - Static message: `\"error\" =\u003e \"Input is required\"`\n     - Custom function error:\n       ```php\n       \"error\" =\u003e function($errorType, $input, $row) {\n           if ($errorType === \"length\") {\n               return \"Is required\";\n           }\n           return \"Must be a number\";\n       }\n       ```\n\n7. **confirm**\n   - **Description**: Message to display upon user confirmation, used with `confirm` type prompts.\n   - **Example**: `\"confirm\" =\u003e \"Are you sure you want to continue?\"`\n\n## Available Prompt Types\n\n### Summary\n\n- **text**: Prompts for regular text input.\n- **password**: Prompts for masked password input.\n- **toggle**: Asks a yes/no question.\n- **select**: Provides a list of options for selection.\n- **list**: Prompts for a comma-separated list of values.\n- **continue**: Continue with input dependent on previous value \n- **message**: Displays a message (no input).\n- **confirm**: Asks for confirmation before proceeding.\n\n### Details\n\n1. **text**\n   - **Description**: Prompts the user for regular text input.\n   - **Usage Example**:\n     ```php\n     \"firstname\" =\u003e [\n         \"type\" =\u003e \"text\",\n         \"message\" =\u003e \"First name\"\n     ]\n     ```\n\n2. **password**\n   - **Description**: Prompts the user for password input, masking the characters as they are typed.\n   - **Usage Example**:\n     ```php\n     \"password\" =\u003e [\n         \"type\" =\u003e \"password\",\n         \"message\" =\u003e \"Password\"\n     ]\n     ```\n\n3. **toggle**\n   - **Description**: Asks the user a yes/no question.\n   - **Usage Example**:\n     ```php\n     \"ssl\" =\u003e [\n         \"type\" =\u003e \"toggle\",\n         \"message\" =\u003e \"Do you want SSL?\"\n     ]\n     ```\n\n4. **select**\n   - **Description**: Provides a list of options for the user to choose from.\n   - **Usage Example**:\n     ```php\n     \"select\" =\u003e [\n         \"type\" =\u003e \"select\",\n         \"message\" =\u003e \"Select an item below\",\n         \"items\" =\u003e [\n             \"Lorem 1\",\n             \"Lorem 2\",\n             \"Lorem 3\"\n         ]\n     ]\n     ```\n\n5. **list**\n   - **Description**: Prompts the user for a comma-separated list of values.\n   - **Usage Example**:\n     ```php\n     \"keyword\" =\u003e [\n         \"type\" =\u003e \"list\",\n         \"message\" =\u003e \"Keywords\"\n     ]\n     ```\n5. **continue**\n    - **Description**: Continue with input dependent on previous value.\n    - **Usage Example**:\n      ```php\n      \"continue\" =\u003e [\n         \"type\" =\u003e \"continue\",\n         \"items\" =\u003e function($prevVal) {\n            if($prevVal === \"phone\") {\n                return [\n                    \"phone\" =\u003e [\n                        \"type\" =\u003e \"text\",\n                        \"message\" =\u003e \"Phone\",\n                        \"validate\" =\u003e [\n                            \"length\" =\u003e [1,30],\n                            \"phone\" =\u003e []\n                        ]\n                    ]\n                ];\n            }\n            return false;\n        }\n      ]\n      ```\n6. **message**\n   - **Description**: Displays a message to the user. This type does not collect input and will be excluded from the end result array.\n   - **Usage Example**:\n     ```php\n     \"message\" =\u003e [\n         \"type\" =\u003e \"message\",\n         \"message\" =\u003e \"Lorem ipsum dolor\"\n     ]\n     ```\n\n7. **confirm**\n   - **Description**: Asks the user for confirmation before proceeding. Can display a custom confirmation message.\n   - **Usage Example**:\n     ```php\n     \"confirm\" =\u003e [\n         \"type\" =\u003e \"confirm\",\n         \"message\" =\u003e \"Do you wish to continue?\"\n     ]\n     ```\n\nThese 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.\n\n## Command instance\nYou also execute some of the prompt above command directly with the Command class.\n\n```php\n$command = new MaplePHP\\Prompts\\Command();\n// Print messages and return input\n$input = $command-\u003emessage(\"Text field\", true);\n$input = $command-\u003emask(\"Masked input (password)\");\n$input = $command-\u003etoggle(\"Toggle yes/no\");\n$input = $command-\u003eselect(\"Choose a value\", [\n    //...\n]);\n$input = $command-\u003elist(\"Comma seperated list\");\n$input = $command-\u003econfirm(\"Confirm\");\n\n// Print messages\n$command-\u003emessage(\"Print message\");\n$command-\u003etitle(\"Print bolded message\");\n$command-\u003estatusMsg(\"Print blue status message\");\n$command-\u003eapprove(\"Print green approve message\");\n$command-\u003eapprove(\"Print red error message\");\n```\n\n## Progress Bar\n\nThe `progress` method of the `Command` class allows displaying a progress bar with customizable sleep intervals to indicate ongoing operations.\n\n```php\n$command = new MaplePHP\\Prompts\\Command();\n$command-\u003eprogress(1, 100, function($i, $length) {\n    return 20;\n});\n```\n\n## Validation and Error Handling\n\nEach 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.\n\n### Validation List\n\n1. **required**\n   - **Description**: Checks if the value is not empty (e.g., not `\"\"`, `0`, `NULL`).\n   - **Usage**: `\"required\" =\u003e []`\n\n2. **length**\n   - **Description**: Checks if the string length is between a specified start and end length.\n   - **Usage**: `\"length\" =\u003e [1, 200]`\n\n3. **email**\n   - **Description**: Validates email addresses.\n   - **Usage**: `\"email\" =\u003e []`\n\n4. **number**\n   - **Description**: Checks if the value is numeric.\n   - **Usage**: `\"number\" =\u003e []`\n\n5. **min**\n   - **Description**: Checks if the value is greater than or equal to a specified minimum.\n   - **Usage**: `\"min\" =\u003e [10]`\n\n6. **max**\n   - **Description**: Checks if the value is less than or equal to a specified maximum.\n   - **Usage**: `\"max\" =\u003e [100]`\n\n7. **url**\n   - **Description**: Checks if the value is a valid URL (http|https is required).\n   - **Usage**: `\"url\" =\u003e []`\n\n8. **phone**\n   - **Description**: Validates phone numbers.\n   - **Usage**: `\"phone\" =\u003e []`\n\n9. **date**\n   - **Description**: Checks if the value is a valid date with the specified format.\n   - **Usage**: `\"date\" =\u003e [\"Y-m-d\"]`\n\n10. **dateTime**\n    - **Description**: Checks if the value is a valid date and time with the specified format.\n    - **Usage**: `\"dateTime\" =\u003e [\"Y-m-d H:i\"]`\n\n11. **bool**\n    - **Description**: Checks if the value is a boolean.\n    - **Usage**: `\"bool\" =\u003e []`\n\n12. **oneOf**\n    - **Description**: Validates if one of the provided conditions is met.\n    - **Usage**: `\"oneOf\" =\u003e [[\"length\", [1, 200]], \"email\"]`\n\n13. **allOf**\n    - **Description**: Validates if all of the provided conditions are met.\n    - **Usage**: `\"allOf\" =\u003e [[\"length\", [1, 200]], \"email\"]`\n\n14. **float**\n    - **Description**: Checks if the value is a float.\n    - **Usage**: `\"float\" =\u003e []`\n\n15. **int**\n    - **Description**: Checks if the value is an integer.\n    - **Usage**: `\"int\" =\u003e []`\n\n16. **positive**\n    - **Description**: Checks if the value is a positive number.\n    - **Usage**: `\"positive\" =\u003e []`\n\n17. **negative**\n    - **Description**: Checks if the value is a negative number.\n    - **Usage**: `\"negative\" =\u003e []`\n\n18. **validVersion**\n    - **Description**: Checks if the value is a valid version number.\n    - **Usage**: `\"validVersion\" =\u003e [true]`\n\n19. **versionCompare**\n    - **Description**: Validates and compares if a version is equal/more/equalMore/less... e.g., than withVersion.\n    - **Usage**: `\"versionCompare\" =\u003e [\"1.0.0\", \"\u003e=\"]`\n\n20. **zip**\n    - **Description**: Validates ZIP codes within a specified length range.\n    - **Usage**: `\"zip\" =\u003e [5, 9]`\n\n21. **hex**\n    - **Description**: Checks if the value is a valid hex color code.\n    - **Usage**: `\"hex\" =\u003e []`\n\n22. **age**\n    - **Description**: Checks if the value represents an age equal to or greater than the specified minimum.\n    - **Usage**: `\"age\" =\u003e [18]`\n\n23. **domain**\n    - **Description**: Checks if the value is a valid domain.\n    - **Usage**: `\"domain\" =\u003e [true]`\n\n24. **dns**\n    - **Description**: Checks if the host/domain has a valid DNS record (A, AAAA, MX).\n    - **Usage**: `\"dns\" =\u003e []`\n\n25. **matchDNS**\n    - **Description**: Matches DNS records by searching for a specific type and value.\n    - **Usage**: `\"matchDNS\" =\u003e [DNS_A]`\n\n26. **equal**\n    - **Description**: Checks if the value is equal to a specified value.\n    - **Usage**: `\"equal\" =\u003e [\"someValue\"]`\n\n27. **notEqual**\n    - **Description**: Checks if the value is not equal to a specified value.\n    - **Usage**: `\"notEqual\" =\u003e [\"someValue\"]`\n\n28. **string**\n    - **Description**: Checks if the value is a string.\n    - **Usage**: `\"string\" =\u003e []`\n\n29. **equalLength**\n    - **Description**: Checks if the string length is equal to a specified length.\n    - **Usage**: `\"equalLength\" =\u003e [10]`\n\n30. **lossyPassword**\n    - **Description**: Validates password with allowed characters `[a-zA-Z\\d$@$!%*?\u0026]` and a minimum length.\n    - **Usage**: `\"lossyPassword\" =\u003e [8]`\n\n31. **strictPassword**\n    - **Description**: Validates strict password with specific character requirements and a minimum length.\n    - **Usage**: `\"strictPassword\" =\u003e [8]`\n\n32. **pregMatch**\n    - **Description**: Validates if the value matches a given regular expression pattern.\n    - **Usage**: `\"pregMatch\" =\u003e [\"a-zA-Z\"]`\n\n33. **atoZ**\n    - **Description**: Checks if the value consists of characters between `a-z` or `A-Z`.\n    - **Usage**: `\"atoZ\" =\u003e []`\n\n34. **lowerAtoZ**\n    - **Description**: Checks if the value consists of lowercase characters between `a-z`.\n    - **Usage**: `\"lowerAtoZ\" =\u003e []`\n\n35. **upperAtoZ**\n    - **Description**: Checks if the value consists of uppercase characters between `A-Z`.\n    - **Usage**: `\"upperAtoZ\" =\u003e []`\n\n36. **isArray**\n    - **Description**: Checks if the value is an array.\n    - **Usage**: `\"isArray\" =\u003e []`\n\n37. **isObject**\n    - **Description**: Checks if the value is an object.\n    - **Usage**: `\"isObject\" =\u003e []`\n\n38. **boolVal**\n    - **Description**: Checks if the value is a boolean-like value (e.g., \"on\", \"yes\", \"1\", \"true\").\n    - **Usage**: `\"boolVal\" =\u003e []`\n\n### Usage Example\n\nHere is an example of how to use the validation functions in the prompt library:\n\n```php\n$inp-\u003eset([\n    \"firstname\" =\u003e [\n        \"type\" =\u003e \"text\",\n        \"message\" =\u003e \"First name\",\n        \"validate\" =\u003e [\n            \"length\" =\u003e [1, 200],\n            \"required\" =\u003e []\n        ],\n        \"error\" =\u003e \"Required\"\n    ],\n    \"email\" =\u003e [\n        \"type\" =\u003e \"text\",\n        \"message\" =\u003e \"Email\",\n        \"validate\" =\u003e [\n            \"length\" =\u003e [1, 200],\n            \"email\" =\u003e []\n        ]\n    ],\n    \"age\" =\u003e [\n        \"type\" =\u003e \"text\",\n        \"message\" =\u003e \"Age\",\n        \"validate\" =\u003e [\n            \"number\" =\u003e [],\n            \"min\" =\u003e [18]\n        ]\n    ]\n]);\n```\n\n## Conclusion\n\nPHP 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.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaplephp%2Fprompts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaplephp%2Fprompts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaplephp%2Fprompts/lists"}