Port "+options" for constant-parameters to APIv4-PHP
APIv4 made a step forward in more clearly distinguishing different parts of the input (where-criteria vs update-values vs options...). This also had the affect of making it more verbose. For CLI bindings in
cv api4, improvising API calls was a struggle... until I started using a DSL with
+ options. This issue proposes to make the same mechanism available in PHP code.
In PHP, one may write:
Civi\Api4\Foo::update() ->addWhere('field1', '=', 'value1') ->addWhere('field2', '>', 'value2') ->setValue('field3', 'value3') ->execute() civicrm_api3('Foo', 'update', [ 'where' => [ ['field1', '=', 'value1'], ['field2', '>', 'value2'], ], 'values' => ['field3' => 'value3'], ]);
This is good in that it's very structured, but it's also very verbose.
In CLI usage, the verbosity of JSON killed the ability to improvise calls to the API.
cv api4 worked around this with a DSL -- the most common options support a "+" notation ("where" == "+w"; "select" == "+s"; "limit" == "+l"; etc). This allows one to express constant parameters much more concisely:
cv api4 Foo.update +w field1=value1 +w field2>value2 +v field3=value3
api4('Activity.update +w field1=value1 +w field2>value2 +v field3=value3')->execute(); $count = api4('Activity.get +s row_count +w activity_type.name="Tell a friend"')->execute(); $events = api4('Event.get +s id,title +o start_date')->execute();
What if you want to include a mix of constant-parameters and variable-parameters? You wouldn't drop random variable expressions inside the string - because that leads to escaping issues. Instead, mix-in the normal APIv4 OOP notation:
// Same as above, but the filter "value2" is a dynamic value coming from a variable api4('Activity.update +w field1=value1 +w field2>value2') ->setValue('field3', $value3) ->execute();
Side benefit: having the parser in core would make it easier for drush/wp-cli bindings to use the same notation as cv.