CiviCRM Community Forums (archive)

Hi Xavier,

I'd really like to see us getting somewhere with the 'self-documenting' explain/ discover function. I agree with Michal/ Piotr that using good code commenting / PHPDoc would be a good idea. However, the convention for code commenting is fairly limited - e.g. it tells you that you can pass in a $params array but doesn't mention the possible fields in that array.

An explain option (however) could return the possibilities based on a combination of:

a function with std options for the type of operation (e.g. GET)
a function that returns custom fields for the entity
a function that returns the dao fields for the entity
a function that returns hard-coded 'extras' for the specified function

We could compare the variables returned by this function against the Unit Test in some way

On other things

- I think the *current* consensus is not to have an UPDATE function where a CREATE with entity_id will do (e.g. there might be an update for something like address update where the instruction would be 'replace existing home mobile with this' but for contact, for example, you would use create to update the individual with contact_id x. I guess you are suggesting a change of consensus to a chained approach?


My other question is how do we migrate - I'm thinking that maybe we need a v3 with all the correct names & core error catching & a v4 with all the other bits & pieces. The could sit in different folders & the API can call the folder that matches the version name (default is 2). I realise this does involve shipping more than one API (which Lobo was against) but I *think* the main problem with shipping more than one is support & a fairly ruthless approach of only supporting the most recent of any given API is more easily applied to APIs than the rest of the code (i.e if a v3 of contact exists we would tell people to switch & then we'll help. Since all they would need to do to switch would be to change the version parameter it wouldn't be a biggie. The include they use wouldn't change in this scenario (a file in the top level about the v2 etc folders where the to-be deprecated code is right now)

Will it cook dinner & wash my socks?

I would have though farenheit was due to be deprecated anyway....

You meant civicrm_marmite_delete

(not sure api standardisation is good stand up comedy material)

X+

Eric - I think this is a prime example of a poor naming convention.

civicrm_warm_british_bear()

and

civicrm_warm_british_beer

Are quite different functions. I believe the second was the intended syntax

So, on the issue I have been banging on about on whether we support field names in v4 or whether we support unique name (if exists else field name) I have hit an example (still on pledge BAO example) where the field name is ambiguous

If running a pledge_get with the return property of contribution_type I get a query based on returning me the contribution_type for all contributions for that contact. The contribution types for the object I am querying (pledge) aren't returned at all.