[10.x] Document Laravel Prompts & prompting for missing input.

[jessarcher]

This PR adds documentation for Laravel Prompts.

I've also included documentation for the existing PromptsForMissingInput functionality.

[woodspire]

Two questions based on your Laracon 2023 presentation:

Laravel\Prompts\select

Can it be optional ? It seems that "no selection" is not possible.

Laravel\Prompts\confirm

Is there a way to not select any of the options ? So we make sure the user really select something instead of only pressing the enter key.

Can there be more than 2 options ?

[woodspire]

Also, you specify that for Windows, it's only working with WSL because the windows php exe is missing some stuff (readline module I think?)

So am I right to say that it's not a windows terminal problem but a php compilation problem ?
I mean, there are lots of terminal on windows (on the top of my head, from Microsoft; cmd, terminal, powershell), so if it's a default terminal problem, specify in the doc that it's possible on Windows but not with default terminals.

Thanks !

[jessarcher]

Two questions based on your Laracon 2023 presentation:

Laravel\Prompts\select

Can it be optional ? It seems that "no selection" is not possible.

There's nothing built-in to make it optional, but you can add an option named "None" (or whatever wording is appropriate for your prompt) and check whether it was the selected option.

For example, this is what we'll be doing in the Laravel installer:

I had considered trying to make it optional, but I couldn't come up with an intuitive UI that was any better than just adding a custom "None" option.

Laravel\Prompts\confirm

Is there a way to not select any of the options ? So we make sure the user really select something instead of only pressing the enter key.

Not at the moment, but you can specify the default as false if you want them to select "Yes explicitly". Is there a specific use case you have in mind where this isn't suitable?

Can there be more than 2 options ?

I would just use the select function. The confirm function is really just for returning a boolean. Do you have a use case in mind where this isn't suitable?

[jessarcher]

Also, you specify that for Windows, it's only working with WSL because the windows php exe is missing some stuff (readline module I think?)

So am I right to say that it's not a windows terminal problem but a php compilation problem ? I mean, there are lots of terminal on windows (on the top of my head, from Microsoft; cmd, terminal, powershell), so if it's a default terminal problem, specify in the doc that it's possible on Windows but not with default terminals.

Thanks !

You are correct about readline. Even with the readline module included, Windows is missing many of the functions: https://stackoverflow.com/a/71178783

An alternative approach is using the Unix stty command to control the terminal behaviour, but I haven't been able to find a Windows equivalent.

In either case, the terminal application itself doesn't matter. We'd either need an equivalent to the stty command or for php.exe to include the missing readline functions.

It comes down to the following main requirements:

1. We need to be able to read each key as it's pressed. On Windows, we only receive everything after the "Enter" key has been pressed. This is especially important for prompts using the arrow keys. On Unix, we achieve this with stty -icanon.
2. We need to prevent the typed keys from echoing to the bottom of the terminal so that we can control the output ourselves. On Unix, we achieve this with stty -echo.

We also need to intercept Ctrl+C to restore the terminal settings (and ideally render the "Cancelled" state). register_shutdown_function doesn't seem to help here. On Unix, we're using stty -isig for this.

This isn't an issue for Symfony's prompts because the user input is always the very last thing on the screen, and none of the prompts require the arrow keys (although they can optionally be used in supported environments). The experience is still degraded on Windows, but Symfony's UI choices allow for that at the cost of limiting the UI possibilities in other environments.

[woodspire]

@jessarcher Thanks for all your answers. You answered all my questions.

Have a nice day and thanks for providing us with such a great addition.