Skip to content

GitLab

  • Projects
  • Groups
  • Snippets
  • Help
    • Loading...
  • Help
    • Help
    • Support
    • Community forum
    • Submit feedback
    • Contribute to GitLab
  • Sign in
C
Core
  • Project overview
    • Project overview
    • Details
    • Activity
    • Releases
  • Repository
    • Repository
    • Files
    • Commits
    • Branches
    • Tags
    • Contributors
    • Graph
    • Compare
  • Issues 924
    • Issues 924
    • List
    • Boards
    • Labels
    • Service Desk
    • Milestones
  • Operations
    • Operations
    • Incidents
  • Analytics
    • Analytics
    • Repository
    • Value Stream
  • Wiki
    • Wiki
  • Snippets
    • Snippets
  • Members
    • Members
  • Collapse sidebar
  • Activity
  • Graph
  • Create a new issue
  • Commits
  • Issue Boards
  • Development
  • Core
  • Issues
  • #1489

Closed
Open
Opened Dec 19, 2019 by totten@tottenOwner

Port "+options" for constant-parameters to APIv4-PHP

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.

Edited Dec 19, 2019 by totten
To upload designs, you'll need to enable LFS and have admin enable hashed storage. More information
Assignee
Assign to
None
Milestone
None
Assign milestone
Time tracking
None
Due date
None
Reference: dev/core#1489