[RFC|Merged] General Hook Architecture of phpBB3.1

[Oleg]

The absolutelly first idea about name of appropriate event would probably (well...still imagine you are common extensions author) be "core.user_add_after" or at least "core.user_add" - because original function maintaining this is called "user_add".

If the function is appropriately named, event name can incorporate function name. There is no requirement that event name be different from anything else in the code.

But it takes time! And (as you all know) programmers are really not willing to loose time lookuping names...

Of all the languages I know php is the (only) one where programmers are expected to continuously check documentation for the correct order of parameters and correct function names. When developers complain about this the usual answer from above is "use an ide with auto-complete" which essentially makes the programmer consult the ide instead of documentation for this information.

(Obviously we don't want to perpetuate this situation.) Anyway, back to topic:

It has never ever been wrong to make things clear...longer, but clearer.

There are different definitions of "clear". The other one is "it should be clear what an event does from its name and parameters to someone unfamiliar with phpbb's code".

[Senky]

"it should be clear what an event does from its name and parameters to someone unfamiliar with phpbb's code".

Valid argument. Okay, you decide, however take into consideration you will need to have really good accessible/simple/up-to-date documentation.

[brunoais]

About that before and after.

I think you should use something like <namespace>.<something (may include dots)>.before <namespace>.<something (may include dots)>.after. I t just makes more sense to me. Instead of using underscores and include the before and the after in the underscore naming.

[Oleg]

"it should be clear what an event does from its name and parameters to someone unfamiliar with phpbb's code".

Valid argument. Okay, you decide, however take into consideration you will need to have really good accessible/simple/up-to-date documentation.

Documentation should be good, up-to-date and I don't know what you mean by "accessible" but we can have it next to coding guidelines, regardless of how this situation is resolved.

To that end as I already mentioned I am working on extracting event documentation from code.

[Senky]

Accessible means if new developer finds it, he can find it on Google, or find on google at least some kind of page leading him to it. But if it will be often linked in discussions, it will easily get to first place for queries like "events phpBB".

[Senky]

Btw, will all extensions have possibility to add events to their code?

[imkingdavid]

Btw, will all extensions have possibility to add events to their code?

You mean Extension A adds an event in its code that Extension B can use if Extension A is installed? I don't see a problem with that, but I haven't thought it through very much. Obviously it would need to use a prefix other than core. so it wouldn't clash with the core events.

[Senky]

Btw, will all extensions have possibility to add events to their code?

You mean Extension A adds an event in its code that Extension B can use if Extension A is installed? I don't see a problem with that, but I haven't thought it through very much. Obviously it would need to use a prefix other than core. so it wouldn't clash with the core events.

Yes! Imagine Gallery MOD as an extension - I bet they will want to add events to their code. The same for Ultimate Points, etc. That is why I was so happy to see "core." prefix, so I would say it would be really nice to present possibility to add events to extensions to MOD authors after release of 3.1.

We probably just need to think of the way how extensions will have possibility to choose prefix, and how it will be managed in extensions DB (because it would be really nice to check for existance of event prefix in MPV).

[nickvergessen]

php Events

Here is some documentation about our php Events, that I'd like to put in the wiki and maybe even into the coding guidelines.

• Naming
  
  • Only events of the core should be prefixed with core.
  • Event names should only contain dots (to separate prefixes), underscores and lowercase letters
  • Event names should be short, descriptive and not use acronyms (like del instead of delete, note: length is not restricted)
  • Events before/after a certain action should be appended with _before/_after. If both events exist (before and after) the base-name (apart from the appendix) must be the same
  • Event's main name should be verb->noun, so an event when we remove a user from a group should be core.group_remove_user (in this case group_ is just some kind of prefix, to specify the position of the event more clearly)
• Docs
  
  • All events that are merged to the core, must have a doc block with the following information:
    

    Code: Select all

    /**
* {Short one line description}
*
* {Optional: further explanation if needed, can be multiple lines}
*
* @event {identifier of the event}
* @var {type} {variable_name} {Information about the variable that is passed to the event, one per line.}
* @since {Version when the event was added}
*/

    
    Example:
    

    Code: Select all

    /**
* Run custom quicktool code
*
* @event core.acp_users_overview_run_quicktool
* @var   array   user_row   Current user data
* @var   string   action   Quick tool that should be run
* @since 3.1-A1
*/

  • Doc lines should not be longer than 79 characters (including the whitespaces/tabs, before the *)

[EXreaction]

This should be in a wiki page of hook guidelines for future reference

Also, instead of core.group_remove_user, would core.group.remove_user make more sense?