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

[Senky]

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).

[MattF]

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...

[Senky]

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...

[MichaelC]

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.

[Oleg]

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.

[nickvergessen]

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!

[Oleg]

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.

[naderman]

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]

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]

+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.