API: checkbox/multiselect custom fields expect a strange structure

Created by: seancolsen

This ticket was migrated from https://issues.civicrm.org/jira/browse/CRM-13544

I am trying to write checkbox values to the v3 API (contact object). According to the comments at the top of CustomValue.php:

 // custom_24 is checkbox or multiselect, so pass items as an array
 * 'custom_24' => array('bar', 'baz'),

I tried writing using this code:

$params['custom_37'] = array("Sjogrens Syndrome","HIV");

however regardless of what values I put in the array, the values were being set to 0 and 1 in the database.

I confirmed that it is using array keys instead of values by trying with:

$params['custom_37'] = array(3=>4,5=>6);

This resulted in 3 and 5 being set in the database.

I tried debugging inside CustomValue.php (function civicrm_api3_custom_value_create) but that function does not seem to get called at all.

For a second I thought that I should be looking somewhere else (i.e. this creates an actual value option for a custom field rather than saving a value), but the nomenclature suggests that "creating" a custom value means creating/updating an object that has a custom field (for example, in api/v3/examples/Contact/CustomFieldCreate.php)

For now I am just using the array keys, but eventually we should correct either the documentation or the code.