phpBB

Development Wiki

Developing Extensions

From phpBB Development Wiki

Revision as of 08:50, 23 March 2012 by Michaelc (Talk | contribs)

phpBB 3.1 "Ascraeus" introduces extensions as another way to add new community-contributed features into a phpBB installation. Extensions are different from MODs in that they do not make any file modifications to the core phpBB files. Instead, extensions are entirely contained in their own directories within the ./ext/ directory in the phpBB root.

Getting Started

For an example extension package, please view the following repository: https://github.com/naderman/phpbb3-example-ext

Extensions should be located in the phpBB directory as follows: phpBB/ext/<vendor>/<ext>

<vendor> is the author or group of authors of the extension. Note that vendor and extension directory names may ONLY contain numbers and letters. Underscores, dashes, and other characters are NOT permitted. It is perfectly fine to have an extension named iamanextension.

extension.json

This file is the metadata file containing specific information about your extension. For information on what information goes into the file, please view extension_meta_data.

ext.php

Each extension should have a file called ext.php at phpBB/ext/<vendor>/<ext>/ext.php. Here is an example file from an example extesnion phpBB/ext/example/foobar/ext.php:

class phpbb_ext_example_foobar_ext extends phpbb_extension_base
{
}

The class is required in order for phpBB to identify your extension as an extension. It also may contain any special (un)installation commands in the methods enable_step(), disable_step() and purge_step(). As it is, these methods are defined in phpbb_extension_base, which this class extends, but you can overwrite them to give special instructions for those cases.

Front-facing Files

Some extensions may require the inclusion of a front-facing file. For example, a blog might need to display all blog entries. This is achieved by adding a class that implements the phpbb_extension_controller_interface. For our example, we will use an extension named "foobar" made by vendor named "example".

Writing

To create a "front" file, create a new file in the root of your extension directory ./ext/example/foobar/ called controller.php. This file must contain a new class called "phpbb_ext_example_foobar_controller" (where foobar is identical to the extension directory) that implements "phpbb_extension_controller_interface". The class must contain a public function called "handle()", which should take no arguments.

Tip: To use common phpBB objects within your extension front page, you will need to use the global keyword. You may then assign those to class properties so that you do not have to use global in all of your methods.


<?php

class phpbb_ext_example_foobar_controller implements phpbb_extension_controller_interface
{
    
// This is the handle() method by which this class is referenced.
    // Think of it like __construct(); it is automatically called by phpBB when the page is accessed
    
public function handle()
    {
        
// We have to globalize the phpBB objects (and config array) if we wish to use them in our extension.
        
global $user$template$db$request$config;
        
// To prevent having to globalize it and others in every method, we can assign it as a class property.
        
$this->user $user;
        
$this->template $template;
        
$this->db $db;
        
$this->request $request;
        
$this->config $config;

        
// So now if we need to use the user object, for instance, we use $this->user like so:
        
echo 'Welcome, ' $this->user->data['username'];
        
// Anything in this function will be executed when the front file is loaded.

        // So to output stuff to the page, let's a call our function display()
        
$this->display();
    }

    private function 
display()
    {
        
// The following takes two arguments:
        // 1) which extension language folder we're using (it's not smart enough to use its own automatically)
        // 2) what language file to use
        
$this->user->add_lang_ext('example/foobar''foobar');

        
// This tells the template where to look for the template files
        
$this->template->set_ext_dir_prefix($phpbb_root_path 'ext/example/foobar/');

        
// foobar_body.html is in ./ext/foobar/example/styles/prosilver/template/foobar_body.html
        
$this->template->set_filenames(array(
                
'body' => 'foobar_body.html'
        
));

        
// And we assign template variables the same as before as well
        
$this->template->assign_var('MESSAGE''Yes, this is hard-coded language, which should still be avoided in virtually all cases.');

        
// And now to output the page.
        
page_header($user->lang('WELCOME_TO_FOOBAR'));
        
page_footer();
    }
}

You can also include other public and private methods to call within the handle() method.

Invoking

To load your page, visit domain.com/forum/index.php?ext=foobar