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

These requests for comments/change have lead to an implemented feature that has been successfully merged into the 3.1/Ascraeus branch. Everything listed in this forum will be available in phpBB 3.1.
Post Reply
Oleg
Posts: 1150
Joined: Tue Feb 23, 2010 2:38 am
Contact:

Re: [RFC|Accepted] General Hook Architecture of phpBB3.1

Post by Oleg » Sat Jun 23, 2012 5:23 am

Senky wrote: 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
Extension Customisations
Extension Customisations
Posts: 283
Joined: Thu Jul 16, 2009 4:41 pm

Re: [RFC|Accepted] General Hook Architecture of phpBB3.1

Post by Senky » Sat Jun 23, 2012 8:59 am

Oleg wrote:"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.

User avatar
brunoais
Registered User
Posts: 958
Joined: Fri Dec 18, 2009 3:55 pm

Re: [RFC|Accepted] General Hook Architecture of phpBB3.1

Post by brunoais » Sun Jun 24, 2012 8:02 am

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
Posts: 1150
Joined: Tue Feb 23, 2010 2:38 am
Contact:

Re: [RFC|Accepted] General Hook Architecture of phpBB3.1

Post by Oleg » Mon Jun 25, 2012 6:15 am

Senky wrote:
Oleg wrote:"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
Extension Customisations
Extension Customisations
Posts: 283
Joined: Thu Jul 16, 2009 4:41 pm

Re: [RFC|Accepted] General Hook Architecture of phpBB3.1

Post by Senky » Mon Jun 25, 2012 8:04 am

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
Extension Customisations
Extension Customisations
Posts: 283
Joined: Thu Jul 16, 2009 4:41 pm

Re: [RFC|Accepted] General Hook Architecture of phpBB3.1

Post by Senky » Wed Jun 27, 2012 7:48 am

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

User avatar
imkingdavid
Registered User
Posts: 1050
Joined: Thu Jul 30, 2009 12:06 pm

Re: [RFC|Accepted] General Hook Architecture of phpBB3.1

Post by imkingdavid » Wed Jun 27, 2012 12:29 pm

Senky wrote: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.
I do custom MODs. PM for a quote!
View My: MODs | Portfolio
Please do NOT contact for support via PM or email.
Remember, the enemy's gate is down.

Senky
Extension Customisations
Extension Customisations
Posts: 283
Joined: Thu Jul 16, 2009 4:41 pm

Re: [RFC|Accepted] General Hook Architecture of phpBB3.1

Post by Senky » Wed Jun 27, 2012 2:14 pm

imkingdavid wrote:
Senky wrote: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).

User avatar
nickvergessen
Former Team Member
Posts: 733
Joined: Sun Oct 07, 2007 11:54 am
Location: Stuttgart, Germany
Contact:

Re: [RFC|Accepted] General Hook Architecture of phpBB3.1

Post by nickvergessen » Sat Aug 11, 2012 5:00 pm

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 *)
Member of the Development-TeamNo Support via PM

User avatar
EXreaction
Registered User
Posts: 1555
Joined: Sat Sep 10, 2005 2:15 am

Re: [RFC|Accepted] General Hook Architecture of phpBB3.1

Post by EXreaction » Sat Aug 11, 2012 5:04 pm

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?

Post Reply