Argument Handling for PHP CLI Scripts
This project aims to deliver a easy to use and free as in freedom php command component.
Take a look on openhub.net.
The current change log can be found here.
mkdir -p vendor/net_bazzline/php_component_cli_arguments cd vendor/net_bazzline/php_component_cli_arguments git clone https://github.com/bazzline/php_component_cli_arguments .
composer require net_bazzline/php_component_cli_arguments:dev-master
- easy up handling of following kinds of arguments
- flags (command -f|--force)
- lists (command --foobar=foo | command -f=foo)
- values values (command )
Simple call run.php with tons of arguments like illustrated below.
php run.php --foo bar --foobar=foo --foobar="bar" -f="foo" -f=bar -b foobar foo -flag
Generates the following output.
arguments provided: --foo bar --foobar=foo --foobar=bar -f=foo -f=bar -b foobar foo -flag flags provided: foo b f l a g lists provided: foobar foo bar f foo bar values provided: bar foobar foo
All arguments are grouped into one of three types, flags, lists or values. Argument or parameter? I could not spot a major difference. When I think about parameters, my mind slipps into the domain of methods or functions, thats why I have decided to call them arguments. Furthermore, php.net calls the "argument list" also :-).
A flag is an argument that changes the behaviour of an command. It acts as a trigger so you can turn things on or off (best example in the world "-h|--help")
The position in a commandcall for a flag is not important, only the existence.
Valid flags are:
- -flag (shortcut for -f -l -a -g)
A list is an argument that contains multiple values per name.
php example.php --my_list="argument one" --my_list="argument two"
would result into a list with the name "my_list" and two arguments, "argument one" and "argument two".
Lists are the most complex arguments. Like for flags, the position in a commandcall for a list usage is not important.
Valid Lists are:
- -l="val ue"
- --list="val ue"
Values are straight forward arguments. You simple pass them to your command. Instead of a flag or a list, the position is important.
Valid values are:
- "val ue"
php example.php "value one" "value two"
First value has the content "value one", second value has the content "value two".
php example.php "value two" "value one"
First value has the content "value two", second value has the content "value one".
Short Name and Long Name Notation
Flag and list arguments supporting short name ("-f") and long name ("--foo") notation. A short name is indicated by a single "-" while a long name is indicated by a double "-". The handling and the support of them is domain specific (and also a matter of tast). To merge the usage and the content for lists is not part of this component.
Why no Validation?
Validation is a complex topic. That's why I decided to not put it into the domain of this component.
It would complicate the code itself. I would have created a universal validation interface that would slow down the usage of this component. Furthermore, you would have to learn a validation expression language or would have need to write code that fits my validation interface but not your "way of coding".
At the end, what is validation all about?
- check if a argument (flag, list, value) is passed or not
- if it is passed validate the value or if it is allowed under that circumstance (if it is right to use flag "-f" while also flag "-b" is passed etc.)
- if it is not passed but was mandatory, create a specific message or throw an exception (and the same for optional arguments)
To sum it up, validation is domain specific for the validation itself and the error handling. That's why I have decided to not support it deeply. The component supports your validation implementation with the methods "hasLists()", "hasList($name)" etc.
Since I won't write "never say never", if you have a smart idea or way to easy up validation, I'm open for an question or a pull request.
What about Optional Arguments?
Optional arguments underlying the same problems as validation. It is not that easy to implement in an elegant way. It is very special/domain specific (e.g. an argument is optional if flag "--xyz" is used, otherwise mandatory). Your code has to take care if an argument is passed or not anyways. Using the available "has..."-methods should be sufficient and generic enough.
Other Great Components
- search on packagist
Star it if you like it :-). Add issues if you need it. Pull patches if you enjoy it. Write a blog entry if you use it :-D.