FEATURE: Introduce --help flag option for existing CLI commands

[crydotsnake]

Upgrade instructions

None

Review instructions

This change introduces a new way of using the help function for existing Flow/Neos CLI commands.

Currently you always used:

./flow help user:create

With this change it is possible to use the new --help flag as an alternative at the end of a CLI command:

./flow user:create --help

But of course the first way will also still work!

Demo

https://github.com/neos/flow-development-collection/assets/39345336/4f93f5cf-0435-4344-b37a-0a76b6df7824

Checklist

• [x] Code follows the PSR-2 coding style
• [ ] Tests have been created, run and adjusted as needed
• [ ] The PR is created against the lowest maintained branch
• [ ] Reviewer - PR Title is brief but complete and starts with FEATURE|TASK|BUGFIX
• [ ] Reviewer - The first section explains the change briefly for change-logs
• [ ] Reviewer - Breaking Changes are marked with !!! and have upgrade-instructions

[crydotsnake]

Open TODOs

I'm still thinking about if i could implement this better.

Also i still have to think about how to improve the description for the --help flag. Because it is not even with the other options. It looks different because the description for the --help attribute is implemented in the HelpCommandController. And not like the others directly in the method signature.

And also the tests needs to be adjusted.

[jonnitto]

As it is not possible to combine --help with other options, I would remove the description.

[crydotsnake]

but wonder if we shouldn't safeguard users who actually used help as argument in their command because that would be pretty breaking for them.

Good point! i havent thought about this so far.. How could we best do this?

[crydotsnake]

but wonder if we shouldn't safeguard users who actually used help as argument in their command because that would be pretty breaking for them.

@kitsunet Do you maybe have an idea, how we could solve this the best way?

[dlubitz]

I think @kitsunet is right and we can't provide safely this global flag without potentially breaking dedicated help arguments of the commands.

[bwaidelich]

Thanks for this contribution. This is a feature that I'm missing forever. It's small, but it really enhances UX.

If you're concerned about existing commands with a --help argument we could target 9.0. But maybe we can easily detect these cases and ignore the global flag for those?

Lastly, I agree to @mhsdesign's comments about the check against --help – but personally I would be OK with that if the choice is hacky but working or not at all :)

[crydotsnake]

Thanks for this contribution. This is a feature that I'm missing forever. It's small, but it really enhances UX.

If you're concerned about existing commands with a --help argument we could target 9.0. But maybe we can easily detect these cases and ignore the global flag for those?

Lastly, I agree to @mhsdesign's comments about the check against --help – but personally I would be OK with that if the choice is hacky but working or not at all :)

But maybe we can easily detect these cases and ignore the global flag for those?

Yes, that would be awesome. As i think this is really a good improvement.

[robertlemke]

I wonder if there's actually any Flow application out there which implemented its own --help argument. And even if there is, I think it would be totally fine if this new feature would just override the custom implementation and that's it. It shouldn't cause an error, but I personally would be totally fine, if the custom argument implementation would just be ignored.

In that sense, what's missing to get this into 8.4? I'd love to have it in soon, so we can making plans for a release.

[mhsdesign]

Yeah sorry i didnt meant to side track it with asking what happens if --help is a real argument.

In the end this will make --help an reserved argument and we have to agree on that (which is likely but still breaking? so !!!?)

But by that i was just trying to make a point that some things are not thought out yet ^^

i would put this logic at below line 155 of $commandIdentifier so we can use this variable and also use $rawCommandLineArguments meaning we support the $commandLine being a string possibly.

Also the case flow --help will with this implementation result in an error as there is no command id named --help. The general help should be shown i suppose.

...

Also this raw lookup against --help seems a little hacky. Like flow does support this short notation of boolean parameters but --help=true or --help=false are technically possible and will now still end up being passed to the final controller do we want that?

And the other points are still valid imo and have not been tackled.

[robertlemke]

It now adds the following at the bottom of the general help screen (list of commands):

And the command-specific help looks like this:

Let's merge this?

[crydotsnake]

Thanks u both! @mhsdesign @robertlemke ❤️ Sorry i havent continue working on that 😅