[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
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 » Thu Jun 21, 2012 5:27 pm

nickvergessen, great idea!

Others: you tell me, how often you change filename/class/function name? Once chosen, it does not change ever! Otherwise it removes backward compatibility with MODs. I agree in adding prefixing, it massively increases ease of finding proper events while developing extension (you oftent don't even need to look at documentation if it has proper name).

User avatar
VSE
Extension Customisations
Extension Customisations
Posts: 670
Joined: Mon Mar 08, 2010 9:18 am

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

Post by VSE » Thu Jun 21, 2012 5:41 pm

Senky wrote:Others: you tell me, how often you change filename/class/function name?
Right now... File names and functions have changed and moved around for the build of 3.1... For example, the template system...
Has an irascible disposition.

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 » Thu Jun 21, 2012 5:58 pm

Yes, and it is problem for MODs currently working with 3.0.x. The only thing that saves that is creation of extensions, but (as you tell) MODs are not expected to disappear after release of 3.1, so every MOD using template system, even every theme needs to be changed to work with 3.1. So if there will be some kind of backward compatibility while moving from 3.0 to 3.1, I do not see any reason not to do the same next time.

+ what is the problem with having one event with multiple names? One old, one new. And check for using it in MODs DB, if old name is not used anymore, delete it in next release. In this way, you can maintain backward compatibility and innovation next to each other...

User avatar
MichaelC
Development Team
Development Team
Posts: 889
Joined: Thu Jan 28, 2010 6:29 pm

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

Post by MichaelC » Thu Jun 21, 2012 9:54 pm

Minor releases are expected to have BC breaks for Extensions anyway. And filenames/classes/functions should not be renamed in maintenance releases so no worry about breaking BC there. Breaking BC between minor releases is best avoided but perfectly allowable; its done all the time. Your breaking BC by renaming the function, there is nothing wrong with renaming the event also when that is done.

As a note, if the function/class is prefixed by phpbb_ then that should be excluded from the event name.
Formerly known as Unknown Bliss
psoTFX wrote: I went with Olympus because as I said to the teams ... "It's been one hell of a hill to climb"
No unsolicited PMs please except for quotes.

Oleg
Posts: 1150
Joined: Tue Feb 23, 2010 2:38 am
Contact:

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

Post by Oleg » Fri Jun 22, 2012 3:36 am

Initial conversation that triggered the current naming discussion: https://gist.github.com/0512237e034e79babdb6

The other thing that I wanted was for event documentation to be specified in the code, using something similar to docblocks we use for function/class documentation. Currently documentation for events is in the wiki. This has two problems:

1. As events change, documentation cannot cover multiple versions effectively. Think about how you would deal with, for example, event parameter list being changed between 3.1 and 3.2. Advantage of inline documentation in the code is that it is possible to obtain documentation for the version of the code you have in front of you.

2. External documentation is not guaranteed to be up to date, or complete. This already happens with some events having documentation that does not particularly well explain what the events do.

I started on an extractor for event documentation. Right now since we don't have docblocks it just pulls the name and parameters (which is still useful, for example, for examining whether different event names and parameters are consistent). See https://gist.github.com/ee1d6edbb7b84e9b19a5. I can fairly easily add the function, class or file name to that output already to address one of the comments above.

The code is currently in https://github.com/p/phpbb-tools/blob/m ... act-events. Yes, it's in python, and I wrote it without referencing python docs once.

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 » Fri Jun 22, 2012 8:33 am

naderman wrote:One of the big advantages of events is that they can keep working when we decide to rename or move functions, classes or files. They even continue to work when we use them in a different place providing the same context.
Oleg had the same argument, but you both seem to forget one thing: MODs do not only do stuff in functions, but also call functions!
Member of the Development-TeamNo Support via PM

Oleg
Posts: 1150
Joined: Tue Feb 23, 2010 2:38 am
Contact:

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

Post by Oleg » Fri Jun 22, 2012 9:20 am

My reasoning essentially is that at any point in time we should be doing the best thing possible under the circumstances. We do change behavior when that brings benefits. I would take either breaking compatibility or creating backward-compatible wrappers for changed functions over retaining our existing code forever.

User avatar
naderman
Product Manager
Product Manager
Posts: 1727
Joined: Sun Jan 11, 2004 2:11 am
Location: Karlsruhe, Germany
Contact:

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

Post by naderman » Fri Jun 22, 2012 11:11 am

I entirely agree with Oleg here. And as he pointed out generating sufficient event documentation out of the code will make it easy enough for MOD authors to understand where events are triggered.

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 » Fri Jun 22, 2012 11:30 am

Well but...why not just make it easier by prefixing it? More work, longer strings? I do not consider this as a valid argument. The easier extension author finds appropriate event, the more likely he will develop. It is not about how easily YOU can maintain the code, but how easily COMMUNITY can change it. Just like php frameworks, WordPress, Joomla, Drupal... developers of original code make more afford, write more code, just for others to allow them write extensions/modules/MODs/whatever faster and more effectively. I cannot imagine more efficient naming as filename/classname/functionname_*.

Imagine you are just common extensions author. You want to alter one field while user registration. 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". And if he is still not sure, he can simply visit the file where this function lies and look up the event name. But it takes time! And (as you all know) programmers are really not willing to loose time lookuping names...

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

sajaki
Registered User
Posts: 86
Joined: Mon Jun 21, 2010 8:28 pm

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

Post by sajaki » Fri Jun 22, 2012 4:53 pm

+1 for Nils.

File and event names should be decoupled. Otherwise you would create dependencies that will hamper version upgrades. a file rename would then break the API.
Consider the wordpress API. hooks are available for almost every base action. no filenames are ever mentioned.
http://codex.wordpress.org/Plugin_API/Action_Reference.

Post Reply