[RFC|Merged] Extensions

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
User avatar
naderman
Product Manager
Product Manager
Posts: 1727
Joined: Sun Jan 11, 2004 2:11 am
Location: Karlsruhe, Germany
Contact:

[RFC|Merged] Extensions

Post by naderman » Mon Aug 15, 2011 3:05 am

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

User avatar
igorw
Registered User
Posts: 500
Joined: Thu Jan 04, 2007 11:47 pm

Re: [RFC] Extensions

Post by igorw » Mon Aug 15, 2011 11:07 pm

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

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

Re: [RFC] Extensions

Post by naderman » Mon Aug 15, 2011 11:24 pm

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.

User avatar
Derky
Development Team
Development Team
Posts: 17
Joined: Sat Oct 08, 2005 7:50 pm
Location: Netherlands
Contact:

Re: [RFC] Extensions

Post by Derky » Tue Aug 16, 2011 10:26 am

naderman wrote:
  • 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

User avatar
igorw
Registered User
Posts: 500
Joined: Thu Jan 04, 2007 11:47 pm

Re: [RFC] Extensions

Post by igorw » Tue Aug 16, 2011 10:42 am

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

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

Re: [RFC] Extensions

Post by naderman » Tue Aug 16, 2011 6:18 pm

Derky wrote: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.

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

Re: [RFC] Extensions

Post by naderman » Tue Aug 16, 2011 6:20 pm

igorw wrote:Based on the pending jQuery ticket I'd suggest `phpBB/ext/<ext>/assets`.
Added to the list.

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

Re: [RFC] Extensions

Post by nickvergessen » Wed Aug 17, 2011 7:40 pm

naderman wrote:
  • ...
  • 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?
Member of the Development-TeamNo Support via PM

User avatar
igorw
Registered User
Posts: 500
Joined: Thu Jan 04, 2007 11:47 pm

Re: [RFC] Extensions

Post by igorw » Wed Aug 17, 2011 10:26 pm

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.

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

Re: [RFC] Extensions

Post by nickvergessen » Thu Aug 18, 2011 7:16 am

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

Post Reply