Where to put api wrapper class in an extension

Question

I just wrote an extension with short-name "genderselfidentify" (it's cool, you should check it out), which implements hook_civicrm_apiWrappers. This hook requires you to declare a class for your api wrapper functions, but the docs for it don't say exactly what you should name the class or where you should put it. The example given is:

function example_civicrm_apiWrappers(&$wrappers, $apiRequest) {
  $wrappers[] = new api_v3_APIWrapperExample();
}

Which implies that

• The class name should start with api_v3_
• It should be placed in the extension's api/v3 directory
• (noting the lack of require_once in the example) it will be autoloaded by CiviCRM.

I found all the above to be true, naming my class api_v3_GenderselfidentifyAPIWrapper the autoloading and wrapper functionality worked great... but then I noticed something strange in the API Explorer:

Why is my wrapper class showing up as if it were an entity?

Answer 1

The example in the wiki was problematic. If you look at the wrappers included with core, they're never placed under the api/v3 folder -- they're always under CRM/Utils/API. (I've updated the wiki to use a different name.)

That's merely a matter of convention, though. The API-wrapper system doesn't impose any constraints on where to put the class or how to name it. As far as that system is concerned, you can use any valid PHP class (as long as it implements the API_Wrapper interface).

The limitation here is in the reflection mechanism (MagicFunctionProvider->getEntityNames() and getActionNames()) which maps between API entities/actions and files/folders/functions. This is tricky to do because the naming conventions have been traditionally loose/ambiguous, so the current implementation uses a general rule of thumb: if you put any PHP file under "api/v3", then it will be reported as an entity name.