@mattab opened this Issue on March 18th 2009 Member

We need to decide on a hook naming convention for all Piwik hooks.
At first sight I would propose

  • all hooks are either at the start or at the very end of a method. If current hooks are in the middle of a function, code should be refactored to put the hook either at start or end
  • hooks are named Class.method for hooks at start of method, or Class.method.end for hooks at end of method.
  • how to name hooks that make it possible to "replace" a php class?

Ideally we would generate an automatic documentation that would parse the calls to the Piwik_PostEvent function, and generate a simple page listing all existing hooks, as well as the phpdoc comment above the function call. See #5684

See also drupal hooks documentation

@robocoder commented on April 26th 2009 Contributor

isn't this a dupe of #264?

@mattab commented on June 2nd 2009 Member

not a blocker for 0.4 but should be done in the next release

@robocoder commented on July 24th 2009 Contributor

For consistency, I think:

* ArchiveProcessing_Day.compute
* ArchiveProcessing_Period.compute

Should be renamed to:

* ArchiveProcessing.Day.compute
* ArchiveProcessing.Period.compute
@robocoder commented on July 30th 2009 Contributor

re: comment:5 - this would break third party plugins like GeoIP, UserLanguage, and EntryPage

@robocoder commented on August 22nd 2009 Contributor

re: hook documentation

Assuming it's possible with phpdoc, would it be easier if all standard hooks were defined in one place, e.g.,

class Piwik_Event
     * Authenticate API request
     * <a class='mention' href='https://github.com/param'>@param</a> $token_auth
     * <a class='mention' href='https://github.com/see'>@see</a> Piwik_View::factory()
     * <a class='mention' href='https://github.com/link'>@link</a> https://github.com/piwik/piwik/blob/master/core/API/Request.php#L107
    const API_REQUEST_AUTHENTICATE = 'API.Request.authenticate';

    // ...
@mattab commented on August 24th 2009 Member

vipsoft, the problem with pre-defining hooks is that you then have to write them twice in the source code. It is better if you just can add the hook in one line. A simple grep script with pre-defined comment format would do the trick to automatically generate the documentation, wouldn't it - or should we use phpdoc?

@robocoder commented on August 25th 2009 Contributor

The flip side is that misspelling a hook generates an error; whereas a typo in a string would go undetected.

@mattab commented on April 1st 2010 Member

For the automatic hook documentation, maybe we can use Zend_Reflection docbook retrieval features: http://framework.zend.com/manual/en/zend.reflection.reference.html

@mattab commented on May 1st 2010 Member

Vipsoft, you are right, your solution would work well, excuse my previous comment.

It would need to work also for hooks triggered in the Plugins code. Plugins can not add their hook to the core hook class, as technically they are loosely coupled. We would also need a way for plugins to define their own hooks, using the same class interface.

This solution would also make it easier to spot names that don't follow the naming standard.

It also makes #264 a lot easier of course, as we just need to parse the core hook class, and all the plugins hook classes.

@mattab commented on July 22nd 2010 Member

Hook names make sense in Piwik atm, appart from ArchiveProcessing Anthon pointed out, but already used in plugins. Closing

This Issue was closed on July 22nd 2010
Powered by GitHub Issue Mirror