To add a little more about our current approach: we discussed adding support for name-based keys to the Civi API. For example, one might write:
$params = array(
'contact_type' => 'Individual',
'first_name' => 'Bob',
'last_name' => 'Roberts',
'mygroup:myfield' => 'My Value', // used to require "custom_123"
);
$result = civicrm_contact_create($params);
This goes a little deeper than our first conversation, e.g. the $result should also use named-based keys, and control parameters such as 'return.*' should also respect the name-based keys. We also need to maintain backward compatibility. To avoid confusion among API consumers, the decision to use name-based keys or id-based keys should be all-or-nothing. I think a more fully-fleshed snippet would be:
$params = array(
'#format' => 'group:field',
'contact_type' => 'Individual',
'mygroup:myfield' => 'My Value',
'return.mygroup:myfield' => 1,
'return.mygroup:myfield2' => 1,
'return.display_name' => 1,
);
$result = civicrm_contact_get($params);
// assert isset($params[*]['mygroup:myfield'])
// assert isset($params[*]['mygroup:myfield2'])
// assert isset($params[*]['display_name'])
The attached file offers some more steps to help us get there. There are some revisions to CRM_Core_BAO_CustomField:
1. There's a new function, getFullnameIdMappings(), which is an alternative to getCustomFieldID(). In contexts with a large number of custom-data fields or a large-number of operations, getFullnameIdMappings should offer a performance improvement. Note the two levels of caching (PHP "static" and CRM_Core_BAO_Cache).
2. There's a commented-out revision to getKeyID. This should have the domino-effect that we discussed – e.g. _civicrm_custom_format_params calls getKeyID, so now several API calls can accept inbound $params data with name-based keys.
In theory, we might get a similar domino affect to provide name-based keys for outbound $result data by modifying CRM_Core_BAO_CustomGroup::formatGroupTree and CRM_Contact_BAO_Contact. My concern (as someone who reads code) is that it would make the data-structures harder to predict/understand – e.g. sometimes the data uses "custom_123" format, and sometimes it uses "custom_123_4" format, and sometimes "mygroup:myfield", and sometimes a "custom" data-tree.
As an alternative, we could do all of the translation in the API layer. This is like _civicrm_custom_format_params, but it also address control-parameters and output-data. The attached draft is an idea for how to implement that layer. Here are a few notable things about the approach:
- It doesn't change any core functions, so all existing application logic, unit tests, etc. remain correct.
- It can rewrite input data, control parameters, and output data.
- The CRM_API_Formatter_FieldRewrite should be very amenable to unit testing – e.g. you can inject a mock-value for _nameIdMapping.
- If we encounter some issue with the new naming convention, then we can put our fixes in the CRM_API_Formatter layer – without revising application logic or core functions.
- It leaves me some options in plotting a migration path from my current mechanism to the official mechanism.
Let me know what you think of the approach/patch. If the basic approach works, I can clean it up a bit (e.g. make a proper patch, add unit tests, and provide a backward-compatible version).
New Feature
Trivial
To add a little more about our current approach: we discussed adding support for name-based keys to the Civi API. For example, one might write:
$params = array(
'contact_type' => 'Individual',
'first_name' => 'Bob',
'last_name' => 'Roberts',
'mygroup:myfield' => 'My Value', // used to require "custom_123"
);
$result = civicrm_contact_create($params);
This goes a little deeper than our first conversation, e.g. the $result should also use named-based keys, and control parameters such as 'return.*' should also respect the name-based keys. We also need to maintain backward compatibility. To avoid confusion among API consumers, the decision to use name-based keys or id-based keys should be all-or-nothing. I think a more fully-fleshed snippet would be:
$params = array(
'#format' => 'group:field',
'contact_type' => 'Individual',
'mygroup:myfield' => 'My Value',
'return.mygroup:myfield' => 1,
'return.mygroup:myfield2' => 1,
'return.display_name' => 1,
);
$result = civicrm_contact_get($params);
// assert isset($params[*]['mygroup:myfield'])
// assert isset($params[*]['mygroup:myfield2'])
// assert isset($params[*]['display_name'])
The attached file offers some more steps to help us get there. There are some revisions to CRM_Core_BAO_CustomField:
1. There's a new function, getFullnameIdMappings(), which is an alternative to getCustomFieldID(). In contexts with a large number of custom-data fields or a large-number of operations, getFullnameIdMappings should offer a performance improvement. Note the two levels of caching (PHP "static" and CRM_Core_BAO_Cache).
2. There's a commented-out revision to getKeyID. This should have the domino-effect that we discussed – e.g. _civicrm_custom_format_params calls getKeyID, so now several API calls can accept inbound $params data with name-based keys.
In theory, we might get a similar domino affect to provide name-based keys for outbound $result data by modifying CRM_Core_BAO_CustomGroup::formatGroupTree and CRM_Contact_BAO_Contact. My concern (as someone who reads code) is that it would make the data-structures harder to predict/understand – e.g. sometimes the data uses "custom_123" format, and sometimes it uses "custom_123_4" format, and sometimes "mygroup:myfield", and sometimes a "custom" data-tree.
As an alternative, we could do all of the translation in the API layer. This is like _civicrm_custom_format_params, but it also address control-parameters and output-data. The attached draft is an idea for how to implement that layer. Here are a few notable things about the approach:
Let me know what you think of the approach/patch. If the basic approach works, I can clean it up a bit (e.g. make a proper patch, add unit tests, and provide a backward-compatible version).