Merge pull request #572 from universalhandle/patch-12

Corrected errors in and reorganized hook_civicrm_apiWrappers() documentation

docs/hooks/hook_civicrm_apiWrappers.md

@@ -2,12 +2,10 @@
 
 ## Summary
 
-This hook allows you to add, override, or remove methods to be called before and after api calls — and to modify either the parameters or the result of the call.
+This hook allows you to add, override, or remove methods to be called before and after API calls — and to modify either the parameters or the result of the call.
 
 ## Notes
 
-The methods must be implemented on an `API_Wrapper` object which is added to the array passed by-reference. See below for more information on the `API_Wrapper` class.
-
 Introduced in CiviCRM 4.4.0.
 
 !!! caution ""
@@ -15,36 +13,55 @@ Introduced in CiviCRM 4.4.0.
 
 ## Definition
 
+    hook_civicrm_apiWrappers(&$wrappers, $apiRequest)
+
+## Parameters
+
+- API_Wrapper[] $wrappers - an array of objects which implement the [`API_Wrapper`](#wrapper-class) interface.
+- array $apiRequest - contains keys 'entity', 'action', and params; see [API Usage](/api/usage.md).
+
+## Returns
+
+- Void
+
+## Wrapper class
+
+The `API_Wrapper` interface specifies two methods:
+
+ * `fromApiInput($apiRequest)`  - Allows for modifcation of API parameters before the request is executed.
+   Should return a (possibly modified) $apiRequest array.
+
+ * `toApiOutput($apiRequest, $result)` - Allows for modification of the result before it is returned.
+   Should return a (possibly modified) $result array.
+
+These methods will be called for every API call unless the `hook_civicrm_apiWrappers()` implementation
+conditionally registers the object. One way to optimize this is to check for the API Entity in
+`hook_civicrm_apiWrappers()` and to check for the API action in the wrapper methods.
+
+## Example
+
+In the file where hooks are implemented, e.g., `path/to/myextension/myextension.php`:
+
 ```php
 /**
-  * Implements hook_civicrm_apiWrappers
+  * Implements hook_civicrm_apiWrappers().
   */
 function myextension_civicrm_apiWrappers(&$wrappers, $apiRequest) {
-  //&apiWrappers is an array of wrappers, you can add your(s) with the hook.
-  // You can use the apiRequest to decide if you want to add the wrapper (eg. only wrap api.Contact.create)
+  // The APIWrapper is conditionally registered so that it runs only when appropriate
   if ($apiRequest['entity'] == 'Contact' && $apiRequest['action'] == 'create') {
-    $wrappers[] = new CRM_Myextension_APIWrapper();
+    $wrappers[] = new CRM_Myextension_APIWrappers_Contact();
   }
 }
 ```
 
-## Wrapper class
-
-The wrapper is an object that contains two methods:
-
- * `fromApiInput()` allows for modification of the params before doing the api call.
-
- * `toApiInput()` allows for modification of the result of the call
-
-These methods will be called for every API call unless the `hook_civicrm_apiWrappers()` implementation conditionally registers the object. One way to optimize this is to check for the API Entity in `hook_civicrm_apiWrappers()` and to check for the API action in the wrapper methods.
-
-To take advantage of CiviCRM's php autoloader, this file should be named
-`path/to/myextension/CRM/Myextension/APIWrapper.php`
+Since we named the wrapper class `CRM_Myextension_APIWrappers_Contact`, the following code is placed in
+`path/to/myextension/CRM/Myextension/APIWrappers/Contact.php` to take advantage of CiviCRM's PHP autoloader:
 
 ```php
-    class CRM_Myextension_APIWrapper implements API_Wrapper {
+    class CRM_Myextension_APIWrappers_Contact implements API_Wrapper {
+
       /**
-       * the wrapper contains a method that allows you to alter the parameters of the api request (including the action and the entity)
+       * Conditionally changes contact_type parameter for the API request.
        */
       public function fromApiInput($apiRequest) {
         if ('Invalid' == CRM_Utils_Array::value('contact_type', $apiRequest['params'])) {
@@ -54,7 +71,7 @@ To take advantage of CiviCRM's php autoloader, this file should be named
       }
 
       /**
-       * alter the result before returning it to the caller.
+       * Munges the result before returning it to the caller.
        */
       public function toApiOutput($apiRequest, $result) {
         if (isset($result['id'], $result['values'][$result['id']]['display_name'])) {