Commands: Integrate with the Form Builder

[dtdesign]

The form builder is ubiquitous these days and an increasing amount of our forms already rely on it or are in a constant process of being migrated. The form builder was introduced in 5.2 long before the commands appeared which means that it is still tied to either a complete “do your own” or "use a DatabaseObjectAction” to save or update records.

Adding Support for Commands

Commands are a bit different in that they come with an explicit constructor signature. We can use reflection to resolve the parameter names to collect requires parameters and to identify the types in order to catch errors as early as possible. ReflectionClass::newInstanceArgs() can possibly used to call the constructor using an array of parameters.

Handling of Extra Parameters

One challenge is the support for properties that are not known in the base class. This is a common issue when dealing with additional columns created by plugins since those are not part of the known signature.

This could be indicated by a PHP attribute to signal the support for “arbitrary” data like this:

public function __construct(
    string $foo,
    int $bar = 0,
    #[ExtraParameters]
    array $extra = [],
) {}

This attribute MUST only appear once and only permits string keys. Furthermore, any key in this array MUST NOT match an existing named parameter to prevent collisions.

All extra parameters MUST be scalar types.

Unresolved Issues

Extra Parameters That Do Not Map to the DatabaseObject

There needs to be a way to flag parameters that should not be passed to the command because they are handled elsewhere.

Command’s __invoke() Must Return a Result

The form builder requires the result to be returned, for example the object that has been created. This enables certain features, such as redirecting or providing an edit link without relying on any events inside of the command.

This is also required to support extra parameters that are not passed to the command because these may need to be connect the data with the result.

Maybe add some kind of callback to the form builder? A third party must already inject its form field so it would have a chance to set up a callback too?