CiviEventInspector - Add util for displaying hook metadata

[totten]

This is meant to facilitate better code-generators and documentation-generators. Key features:

• Adds a new class, Civi\Core\CiviEventInspector.
• Adds a new hook, hook_civicrm_eventDefs. Extensions may use this to document their hooks.
• Implements the hook in core (to report on civicrm-core hooks and events)
• If you follow the practice of declaring static hook stubs (like civicrm-core does), then use addStaticStubs() to assimilate of them.

(Description updated to reflect current class/hook names.)

[totten]

On second thought, if the event dispatcher is the canonical representation of hooks, then perhaps I should rename it to EventInspector and include metadata about all events (regardless of whether they're named hook_foo). That's a small number of additional events, but it'd more complete.

[totten]

@xurizaemon @JohnFF I've updated this to report all events, including both hooks and oddballs.

To get a list of hooks, you could run:

$ cv ev '$i = new \Civi\Core\CiviEventInspector(); return $i->find("/^hook_/");'
...
   "hook_civicrm_validateForm": {
        "name": "hook_civicrm_validateForm",
        "description_html": "This hook is invoked during all CiviCRM form validation. An array of errors<br />\ndetected is returned. Else we assume validation succeeded.@param string $formName<br />\n&nbsp;&nbsp;&nbsp;&nbsp; The name of the form.<br />\n<strong>Param</strong>: array &amp;$fields the POST parameters as filtered by QF<br />\n<strong>Param</strong>: array &amp;$files the FILES parameters as sent in by POST<br />\n<strong>Param</strong>: array &amp;$form the form object<br />\n<strong>Param</strong>: array &amp;$errors the array of errors.@return mixed<br />\n&nbsp;&nbsp;&nbsp;&nbsp; formRule hooks return a boolean or<br />\n&nbsp;&nbsp;&nbsp;&nbsp;                         an array of error messages which display a QF Error<br />\n&nbsp;&nbsp;&nbsp;&nbsp;*/",
        "fields": {
            "formName": {
                "name": "formName",
                "ref": false
            },
            "fields": {
                "name": "fields",
                "ref": true
            },
            "files": {
                "name": "files",
                "ref": true
            },
            "form": {
                "name": "form",
                "ref": true
            },
            "errors": {
                "name": "errors",
                "ref": true
            }
        },
        "class": "Civi\\Core\\Event\\GenericHookEvent",
        "type": "hook",
        "signature": "$formName, &$fields, &$files, &$form, &$errors"
    },
...

[totten]

Oops, that last bit's a mistake. I'll squash it out.

[eileenmcnaughton]

@xurizaemon this is out of WIP now & you seem to have some familiarity with it - it looks OK to me - can you confirm you think it is good to merge?

[xurizaemon]

It seems like it will be relatively safe since nothing of significance is using it. ShowAllTheHooks is using it (see prev commit from fuzionnz/contrib.showallthehooks) but that's hardly an extensive test ... it does work, and it gives an interface that informs for available hooks and events, which is great.

[eileenmcnaughton]

I think given the scope of this I agree with @xurizaemon and am good to merge