[RFC|Merged] Extensions

[naderman]

What are extensions?
An extension consists of one directory located in phpBB/ext/ - this idea started as Self-contained MODs. All extensions can be viewed in the administration control panel. Extensions can be enabled, disabled and purged. When an extension is enabled its installation and/or update process is executed. This will typically run all [RFC] Migrations the extension supplies. A disabled extension no longer provides any functionality. Its code is not executed, but its data remains in the database. Should the user decide to reenable an extension, the update script will be run in case the database content is outdated. Purging an extension means disabling it as well as deleting all database content relating to the extension.

All plugin mechanisms in phpBB check extensions when they look for available plugins. This includes ACP/UCP/MCP modules, modular cron tasks, search backends, authentication plugins, cache drivers, captcha plugins. It will further include Migrations, Hooks, CSS and template snippets through the Improved Template Engine and other changes.

So extensions will piece the various extendable parts of phpBB together into one comprehensive mechanism. It will be the basis for any form of integrated MOD installation in phpBB 3.1, as discussed in [RFC] MOD Installation and [RFC] MOD Installer.

Why are they called extensions
To avoid ambiguity with MODs. Extensions do not require code modifications. MODs can however ship an extension and should handle their installation and database update requirements through an extension containing migrations. Extension was picked as the prefered term out of a few alternatives for phpBB4 in MODS -> plugins/add-ons/extensions.

How are extensions structured?
An extension can contain any code or resources (data, static files, ...). But for the extension mechanisms to work, some guidelines need to be followed. In the following <ext> is the name of the extension (which must not contain underscores), <name> is an arbitrary name for the individual plugin and <style> is the name of a phpBB style.

• XCP Module:
  phpBB/ext/<ext>/xcp/xcp_<name>_module.php
phpBB/ext/<ext>/xcp/xcp_<name>_info.php
• Cron Task:
  phpBB/ext/<ext>/cron/<name>_task.php
• Search Backend:
  phpBB/ext/<ext>/search/<name>_backend.php
• Cache driver:
  phpBB/ext/<ext>/cache/<name>_driver.php
• Authentication plugin:
  phpBB/ext/<ext>/auth/auth_<name>.php
• CAPTCHA plugin:
  phpBB/ext/<ext>/captcha/<name>_plugin.php
• Hook definitions:
  phpBB/ext/<ext>/hook/<name>_hook.php
• Migrations:
  phpBB/ext/<ext>/migration/<name>.php
• CSS:
  phpBB/ext/<ext>/styles/<style>/theme/<name>.css
• Template:
  phpBB/ext/<ext>/styles/<style>/template/<name>.html
• Template-independent Javascript:
  phpBB/ext/<ext>/assets/<name>.js
• Admin Template:
  phpBB/ext/<ext>/adm/style/<name>.html
• Language:
  phpBB/ext/<ext>/language/<language>/<name>.php

The [RFC] Autoloading & Class Naming Conventions had to be adjusted to allow for the phpbb_ext_ prefix to point to phpBB/ext/ instead of phpBB/includes/ext.

How are extensions utilised?
There will be an extension manager which provides the functionality for enabling/disabling/purging extensions. In addition there is an extension finder class that provides a simple interface to locate classes or simply files across all enabled extensions, as shown in these examples:

Code: Select all

$finder = new phpbb_extension_finder($extension_manager);
$cron_task_classes = $finder->directory('/cron')->suffix('_task')->get_classes();

Code: Select all

$finder = new phpbb_extension_finder($extension_manager);
$theme_files = $finder->directory("/styles/$style/theme")->suffix('.css')->get_files();

The finder caches queries, so that the typical performance impact of such a call is very low. The actual implementation of the plugin functionality is up to the individual subsystem. Extensions simply provide a way to tie multiple kinds of plugins together.



Patch (WIP): https://github.com/phpbb/phpbb3/pull/329
Ticket: http://tracker.phpbb.com/browse/PHPBB3-10323

[igorw]

Fully agree, added link to ticket. Finally mod manager in 3.1 is starting to make sense.

[naderman]

I updated the patch, it's now properly functional and has comments. The second commit modifies the new cron system to use the extension finder. Now working on the other plugin systems.

[Derky]

• CSS:
  phpBB/ext/<ext>/styles/<style>/theme/<name>.css
• Template:
  phpBB/ext/<ext>/styles/<style>/template/<name>.html

Where should JavaScript files go? When they differ per style they can be placed in the template folder again, but usually they are the exactly the same for each and every style.
my_custom_captcha.js

How is updating extentions handled?
1) Delete all files and than add new files
2) Or overwriting files
The last use case makes deleting (old) files (in new versions) impossible.
custom-library-1.4.4.php , ie6.js

[igorw]

Based on the pending jQuery ticket I'd suggest `phpBB/ext/<ext>/assets`.

[naderman]

How is updating extentions handled?
1) Delete all files and than add new files
2) Or overwriting files
The last use case makes deleting (old) files (in new versions) impossible.
custom-library-1.4.4.php , ie6.js

I believe you answered your own question there 1) for the reason you stated.

[naderman]

Based on the pending jQuery ticket I'd suggest `phpBB/ext/<ext>/assets`.

Added to the list.

[nickvergessen]

• ...
• CSS:
  phpBB/ext/<ext>/styles/<style>/theme/<name>.css
• Template:
  phpBB/ext/<ext>/styles/<style>/template/<name>.html
• ...

I dont really like this part on the first look, seems to have some pros and cons, but let me sleep a night over it, before commenting deeper on that one.

PS: What about language files?

[igorw]

Language files would be nice too, but we probably wouldn't want to load all of them on every page, so we need a good way to reference them.

[nickvergessen]

Well I would just not load them,
let it be loaded by the user with a hook into page_header()

another questions:
Where to put template-files for the ACP?