Proposed changes to the API

I really want user_relationships_load_relationships($criteria) to return an array indexed by relatee whenever possible. But it seems a little weird to have that behavior only happen if $criteria contains a key of 'uid' — it seems like the behavior is hidden from the API user. Another option is to have it accept an optional second parameter, $relater. If $relater is set, use that to determine the $relatee to index by. My problem with that is that it's possible to specify the criteria such that some of the matching relationships don't have $relater as either the requester_id or the requestee_id. The returned array might then be unpredictably indexed, possibly leading to weird, hard-to-track-down bugs.

What do folks think? How should the function determine the uid of the relater: by inspecting the criteria, which is a bit cryptic but always safe, or by accepting a parameter, which is more explicit but riskier?

Well, I'll just have a big ol' conversation with myself here. :-)

I realized that there can be more than one relationship between 2 individuals, so returning a flat array indexed by relatee would only return one of their relationships, selected somewhat arbitrarily. That's obviously unacceptable, so now I'm thinking of having 3 API functions:

 user_relationships_count_relationships($criteria = array());
 user_relationships_load_relationships($criteria = array());
 user_relationships_load_relationships_by_relatee($criteria = array(), $relater = -1);

ur_count_relationships() just returns a count, as it does already. ur_load_relationships() returns a flat array with an arbitrary index. ur_load_relationships_by_relatee() returns an array indexed by $relatee relative to $relater. Each element of the array is itself an array of the relationships that exist between $relater and $relatee. All relationships that match the criteria but don't involve $relater are returned in the array indexed by $relatee=-1, so as not to conflict with any valid user id.

I think this works ok., and is fairly comprehensible. Anybody else want to chime in on this conversation? :-)

Here's a patch that implements the API as described in update #2 above.

In the absence of any objections, I've committed the changes to the API.

I also updated the criteria for counting/loading relationships such that the values of uid, uid1, uid2, rid, requester_id, requestee_id and rtid can be scalars or arrays; if they're arrays, the functions match relationships where the appropriate column matches any element in the array.