This library aims at making command parsing easy. Not only does it parse strings into commands and parameters, it allows you to define restrictions to parameters (so-called strategies) and do automatic type/content validation.
To install this library, you will need Composer.
$ composer require wildphp/command-parser ^0.1
This library comes with a set of ready-to-use parameters, but you might want to develop your own. More on that later.
The most important classes in the library are the Command, ParameterStrategy, CommandParser and CommandProcessor.
This is the class which defines your commands. It is a storage class, meaning it does nothing more but store items you hand to it.
A Command takes two parameters for its constructor. A callback which should be called when the command is triggered, and
one or more ParameterStrategy instances which will define the behavior of the command. For example:
$foo = function () {};
$command = new Command($foo, new ParameterStrategy(0, 1, [
new NumericParameter(),
]); A ParameterStrategy instance describes the ways in which commands may be executed.
Its constructor takes a few arguments:
__construct(
int $minimumParameters = -1,
int $maximumParameters = -1,
array $initialValues = [],
bool $implodeLeftover = false
)$minimumParametersand$maximumParametersdescribe how many parameters this particular strategy may take. They can be set to -1 or false to disable either bound. However, minimum cannot be larger than maximum.$initialValuesis an array ofParameterInterfaceobjects. More on those below.$concatLeftoveris a boolean. When set to true, the strategy will concatenate all remaining parameters together into one when the maximum parameter count is reached. For example, consider a strategy which will only take up to 2 parameters. If you pass it a command with 3 parameters with this flag set, for example '!test 1 2 3', 2 and 3 will be concatenated asarray('1', '2 3')
Takes any value which is numeric, it uses the php is_numeric function internally.
Set a predefined string in its constructor and only that string will be accepted as its value, thus any other value will be rejected.
Returns true under any circumstance, since parameters are always strings.
As the name would suggest, this is the class in charge of actually parsing messages. When it does so, it hands out ParsedCommand
objects. As it is a utility class, its methods are called statically.
findApplicableStrategy(Command $commandObject, array $parameters): ParameterStrategy
This method finds the most applicable strategy to use on $parameters and returns it.
parseFromString(string $string, string $prefix = '!'): ParsedCommand
Parses a command and its parameters from a string, but does not process them. See below for the CommandProcessor.
Set $prefix for the prefix to use, which should prefix any command given.
ParsedCommand is an object containing the command name and the original parameters given.
This class processes a ParsedCommand further and provides the value conversion facilities. Moreover, when instantiated, it acts as a storage facility for commands so they need not be stored elsewhere.
The heart of this class is this static function.
public static function processParsedCommand(ParsedCommand $parsedCommand, Command $command): ProcessedCommand
It takes a ParsedCommand object and accompanying Command object and processes it into a ProcessedCommand object,
which contains the original ParsedCommand data plus the callback, the converted parameter values and also the applied strategy used for conversion.
process(ParsedCommand $parsedCommand): ProcessedCommand
Much the same as the above function but uses the internal command collection.
registerCommand(string $command, Command $commandObject): bool
Adds a command to the internal command collection, identified by $command. Returns true on success, false if the given identifier
already exists.
findCommand(string $command): Command
Returns a Command object added by above function which is identified by $command.
You can see the full list of contributors in the GitHub repository.