CiviCRM Community Forums (archive)

In most API's civicrm_create_error is used to return error results, and in some API's the function civicrm_create_success is called to return valid results. In most cases the valid result is returned as an array. From v3 onwards the standard on paper will be:

• use civicrm_create_error to return errors from the API. At some point we would like to introduce some standards in error messages, but I think that is still a little further on the path to perfection :-).
• when valid results are returned from an API function, civicrm_create_success is used

For those amongst you that did not know this: both the civicrm_create_error and the civicrm_create_success function are in the CRM/api/v2/utils.php (at the moment, that will become CRM/api/v3/utils.php for the new version).

I have just committed the changed civicrm_create_success function for the v3 API. This is not in the core CiviCRM yet nor in the standard svn, but I do want to share what I have done and hopefully get some comments and feedback :-)

Here is the new code :
function civicrm_create_success( $params = 1 )
{
    $result = array();
    $result['is_error'] = 0;

    if (is_array($params)) {
        $result['count'] = count($params);

    } else {
        if (!empty($params)) {
            $result['count'] = 1;
        } else {
            $result['count'] = 0;
        }
    }
    $result['values'] = $params;
    return $result;
}

This means there will be one array with output, named 'result' that will always hold the following elements:

• element is_error that will always have the value 0 is there is no error (which is obviously the case in civicrm_create_success) and the value 1 if there is an error (which will always be the case in civicrm_create_error)
• the element count that will have a count of the elements in the array received in civicrm_create_success. So if there are more levels in the incoming array, it will count the elements at the top level
• an element values that will hold the actual values of the result

Next steps for me now:

• update the REST.php so it can cope with more than 2 levels in XML, which it currently can not
• update civicrm_create_error
• change all the existing API's to use civicrm_create_error and civicrm_create_success.

Erik

Chat about it Friday, I am not entirely happy with the <values> either, but a standard way will be nice....by the way, the problem with having an extra level (so changing the $result['id'] to $result['values']['id'] would happen now too if we start using the civicrm_create_success consistently? I believe the problem is that we are not consistent in the API's anyway, so whatever we decide to do towards standardization will IMO always throw up problems with backward compatibility....the warning sign is required in any case for V3!

and Eileen, happy birthday from me too!!!!!