GitLab

Overview

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.

Current behavior

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

Proposed behavior

Migrate the Api4ArgParser (Test) into core. Provide a high-level entry function which accepts constant parameters in "+" notation.

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.