Diff for events: https://github.com/p/phpbb3/compare/dev ... re%2Fhooks
Diff for hook locations: https://github.com/p/phpbb3/compare/fea ... 2Fledges-2
Pull request and comments: https://github.com/phpbb/phpbb3/pull/551
General Hook Architecture of phpBB3.1
This is an early draft and subject to change
“Hooks” are a popular concept in contemporary web applications. Generally speaking, a “hook” is a place where extensions can register functions to be called when certain events occur.
While phpBB 3.0 had a powerful hook system, it is obvious that few people ever bothered to use it. The new system thus has to meet the challenge: it has to be easier to use, more powerful and extremely scalable.
The architecture of a phpBB MODule
MODs are stored in the mod/ directory, each MOD using its own subdirectory.
Functions to be called by a hook are identified by naming convention. The hook “foo” automatically invokes all MOD methods named “<MODNAME>_foo”.
Every MOD using the hook system has to provide a class <MODNAME>_class.php implementing the phpBB\MOD interface. The interface declares four methods:
returns an associative array mapping hook names to an array holding a flag whether the method is static and the hook’s priority. Hooks not mentioned here are used statically and with default priority.
Called on installation of the MOD
Called on de-installation of the MOD
Called when the MOD is updated to a newer version
Additonally, a info file with the following information is required:
s an associative array with information about the MOD. Required keys:
- Description : a String describing the MOD
- Target core version : version of phpBB this MOD is intended for
- Version: Version of the MOD
- Author : a string listing the author name
- Installation: a flag describing whether this is an editless MOD or not.
- Requires: An array of other MODs required by this one.
- Plugins: an associative array listing all plugins (captcha/search/db/*cp modules/…) the MOD provides
- A modx installation file for core changes (discouraged)
- Language files in the language subdirectory
- Plugin files
The hook functions of a MOD are enumerated during install and recorded in a table. This enumeration is repeated every time a new MOD is installed or uninstalled. The hook table is cached and stores all MODs to invoke for a given hook.
MOD classes are instantiated on page load, if the MOD declares any non-static hooks. Only one instance per MOD will be created, stored in an array of the static PHPBB class. MODs that are exclusively static are not instantiated automatically.
Debug: Unless DEBUG is defined, phpBB will disable any MODs that are triggering errors. MODs are not to use trigger error, but have to call the phpBB_message method instead. This behavior can be overridden.
Core Hooks (Note, this is an incomplete list subject to changes):
- MOD_start: Called on page load, after the database connection is established
- MOD_exit: Called when the php instance exits, before the database connection is closed
- MOD_cron: Called in cron runs
- MOD_sessionStart: Called when a session is created
- MOD_sessionExit: Called when an user logs out
- MOD_register: Called on all steps of the registration process, with a parameter indicating the current step (‘ToS’, ‘form’, ‘validation’, ‘save’)
- MOD_templateInject: Can return additional template snippets that are added to the template file prior to compilation. A parameter lists the current template region where the injection will take place. Only called when template files are (re-)compiled.
- MOD_css: Css files to add, loaded from the MOD directory. Called on theme compile.
- MOD_js: js files to add, loaded from the MOD directory. Called on template compile
- MOD_post: Called on all steps of the posting process, with a parameter indicating the current step
- MOD_message: Called on all steps of the PM process, with a parameter indicating the current step
- MOD_page_<x>: where <x> is the current phpBB page (index, viewtopic, viewforum, …). Called several times during each page, with a parameter stating the current position in the page.
- MOD_url: all urls created by phpBB are run through this hook.
- MOD_path: Called when an URL is requested – for URL re-writing
- MOD_page: Called when an URL is requested that does not lead to one of the phpBB pages - for adding pages.
- All hooks supported by the 3.0 hook system
MODules can introduce their own hooks simply by calling phpBB’s “invoke_hook” method. If the hook to be called is unknown, it will be added to the hook table and all installed MODs will be queried for this hook during the next cron run.
Once the hook infrastructure is committed, we will accept RFCs for placing hooks in the code. Such RFCs should include:
- Reason for adding the hook
- Where to call the hook
- Input values
- Return values
- Actions to be performed on/with the return values (if any)