Implement more flexible API file-loader

(Note: Description copied from discussion on civicrm-api circa Aug 4, 2011.)

In addition to loading functions from the file:

api/v$

{version}/${entity}.php

also look for files like:

api/v${version}

/$

{entity}

/$

{action}

.php

More specifically, if someone tries to invoke

civicrm_api('widget','frobincate', array(
'version' => 3,
));

then we would search for:

a. api/v3/Widget.php-- civicrm_api3_widget_frobincate
b. api/v3/Widget/frobincate.php – civicrm_api3_widget_frobincate
c. api/v3/Generic.php – civicrm_api3_generic_frobincate
d. api/v3/Generic/frobincate.php – civicrm_api3_generic_frobincate

This has a few key properties:

1. Tracks closely to the current coding conventions
2. Does not require any explicit registration or declaration
3. Anyone who can put files on the include_path[F1] can add new entities, new actions, and/or new generic-actions
4. Files can be safely moved from one module to another
5. Reasonably intuitive – if you can browse the file system, you can understand the loading process
6. Overloading is not included
7. No facility for "API explorer" or "service browsers" – that would require scanning the file tree and then scanning the PHP function space. But that could be cached and, in any event, those features aren't performance-sensitive.

If an API consumer is doing some debugging and wants to figure out which file contains the function, he can do an 'rgrep' on the function name, or he can do something like

ls sites/all/modules//api/v3/MyEntity

I can't imagine a modular design which would be easier on the API consumer.

In implementing this, the civicrm_api entry point would need to test a few different files using, say, file_exists+function_exists. The performance impact should be negligible – esp. if we search in the right order and do some caching.

[F1] Footnote: It's probably simplest to search the include_path. There are other search techniques that have functional advantages, but they'd require refactoring key pieces in Civi's hook and user-framework setup.