TL;DR - everyone is bad ad documenting functionality under the assumption that it is obvious.
Over the last 2-3 months I've been (passively) looking for a piece of functionality in Laravel artisan console conversation tools - ability to ask a choice question with multiple answers. This hasn't been a priority, but something I've kept noticing and wondered why it isn't there.
Background - I work in a web agency and a large point is the ability to start a new project quickly and efficiently - we are using a plug-and-play module structure and ability to install modules during initial project setup stage is a good feature to have. We already have a list of modules available from an API endpoint, so key aspect is to select ones you want. So what I want to achieve is a list of modules where you just navigate through with arrows and tick the ones you want to install.
First attempt (few months ago) - Laravel has choice() method where you can pass options and select which you want. But no mention of accepting multiple values in documentation and for some reason I've learned to gloss over function attributes from 4th onward. Tweeted asking if anyone knows about a package that does this and shelved it.
Second attempt (few days ago) - started looking at this again and noticed few things. First of all - Laravel Command is Macroable so nothing stops me from building up a multiChoice() method and injecting it into the Command class. But I also noticed that choice() 5th attribute is $multiple. Tried it out and indeed, if I enter the options 0,2 they come up, yay.. or maybe not. Having to enter the options manually feels slow and maybe could be improved?
Third attempt(today) - ok, without further inverstigation I wanted to start playing around and build up the multiChoice() method. Laravel side is easy - with Marcroable I can quickly inject a method inside Command. The tricky bit comes down to how underlying input processing will work (this most likely would mean creating a pull request to Symfony project repos which actually makes me excited).
Having done a few js framework installs and seeing how they tend to handle "checkbox" options in console I already imagined of handling space bar keystroke in multiple question scenario. Started diving through code until was inside Symfony QuestionHelper class. Strarted mocking around, quickly got to the point where I knew what I would need to do, but then I found out that the functionality I was looking for already existed via tab character instead of space. However it's not as intuitive as I'd like, so I'm torn - should I stop and just add a comment for users to understand the usage during usage or should I attempt to build up a functionality that might be declined when it gets to the PR review?
Luckily I haven't spent too much time on this - maybe 2 or 3 hours in total. But these could've been 2-3 minutes if they were documented or made a bit more obvious. I've already submitted a PR to Laravel docs to add information about the multiple choice functionality. I've also learned how important is the documentation of functionality - even the minor details you see as obvious. This is why I'm aiming to revisit the documentation for the functionality my organisation has and ensure it is up to date and detailed.
Top comments (0)