APIv4 - Add metadata about class args

[colemanw]

Overview

The CustomValue API is a virtual entity, where multiple api entities all get routed to the same class by virtue of all sharing the prefix "Custom_" and pass a class arg to the php factory functions e.g. CustomValue::get('MyCustomGroup').

Instead of hard-coding this idea into the API Explorer now it's part of the entity metadata so that other APIs, notaby ECK, can use a similar pattern.

Before

Hard-coded

After

Flexible, uses metadata.

[civibot]

(Standard links)

• If this is your first pull-request for CiviCRM, please browse CONTRIBUTING.md for information about the development and testing processes.
• If you are reviewing this pull-request, you may wish to consult the test sites and the Review Standards (long template, short template).

[totten]

OK, so I didn't realize that API Explorer had any special bits for Custom_ and played with it for a moment to understand. Just to verbalize/comprehend... here's a (redacted/simplified) example of the metadata from Entity.get:

$ cv api4 Entity.get +w name=Custom_Education
[
    {
        "name": "Custom_Education",
        "class": "Civi\\Api4\\CustomValue",
        "virtual_entity_prefix": "Custom_" // <== New
    }
]

With just name, you can generate a valid API call in almost every binding.

Procedural PHP: civicrm_api('Custom_Education', 'get', ...)
Angular:        crmApi4('Custom_Education', 'get', ...)
JS:             CRM.api4('Custom_Education', 'get', ...)
CLI:            cv api4 Custom_Education.get ...
REST:           https://example.com/civicrm/ajax/api4/Custom_Education/get

We need this functionality because the PHP class-binding looks quite different. (Change Custom to CustomValue and split apart the words.)

Civi\Api4\CustomValue::get('Education');

The addition of virtual_entity_prefix makes it possible to generate the above PHP code -- it tells you what should not pass into the PHP class. You have to synthesize things to figure what should pass in.

var extraArg = _.camelCase(entityInfo.name.substr(entityInfo.virtual_entity_prefix.length));
var phpCode = entityInfo.class + '::get(' + extraArg + ')';

$extraArg = CRM_Utils_String::convertStringToCamel(substr($entityInfo['name'], strlen($entityInfo['virtual_entity_prefix'])));
call_user_func([$entityInfo['class'], 'get'], $extraArg);

It might be cleaner to affirmatively specify what should pass into the PHP class (eg class_arg).

$ cv api4 Entity.get +w name=Custom_Education
[
    {
        "name": "Custom_Education",
        "class": "Civi\\Api4\\CustomValue",
        "class_arg": ["Education"] // <== New
    }
]

var phpCode = entityInfo.class + '::get(' + entityInfo.class_arg + ')';

call_user_func([$entityInfo['class'], 'get'], $entityInfo['class_arg']);

This contract allows the consumers to be simpler (less string-munging), and it makes the naming/mapping more flexible. (This is equally compatible with prefixes, suffixes, in-fixes, no-fixes, and completely-different-name-ixes. The underlying identities could be names or numbers or composite-keys.)

But this feedback is not a hard blocker. There could be other reasons/future-directions where virtual_entity_prefix seems better... Anyway, I've tested this, and it works. So if you still lean toward virtual_entity_prefix, then it's OK to merge.

[colemanw]

That's a really good idea @totten - that simplifies the API Explorer code and could be useful in other ways.

[totten]

Yeah, looks pretty good. I did a small tweak to the variable-name that appears in generated snippets ($custom_Educations / $customEducations).

Merge on pass.

[colemanw]

Thanks @totten - I just pushed a slightly different tweak that keeps the same behavior as before this PR. E.g. entity name Custom_My_Stuff becomes variable name myStuff (but now it works generically so other virtual entities like Eck get the same nice formatting).