phpBB

Development Wiki

Difference between revisions of "Developing Extensions"

From phpBB Development Wiki

(Fig. 1 - Example Controller Class)
m (Getting Started)
Line 8: Line 8:
 
<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.
 
<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 ===
+
=== composer.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]].
 
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]].
  

Revision as of 19:55, 4 October 2012

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.

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

While, some extensions perform only background tasks or simply modify a pre-existent page, some extensions may require the inclusion of a front-facing file. For example, a blog extension needs to display one or more entries on its own page. This is achieved by adding a class that extends the phpbb_extension_controller base class. For our example, we will use an extension named foobar made by vendor named example.

The Controller

In order for your extension to have a user-accessible page, you must create a front controller class, which is responsible for controlling what a user sees when he accesses your extension's front end. You will need to create a new file in the root of your extension directory (i.e. ./ext/example/foobar/) called controller.php. This file must contain a new class called phpbb_ext_example_foobar_controller (This follows the phpBB class naming guidelines, driving the class name from the directory structure and the file in which the class is contained). Your class must extend phpbb_extension_controller. The only required method within your controller class is a public handle() method (as is defined in the phpbb_extension_controller_interface, which is implemented by the phpbb_extension_controller abstract class). The handle() method receives no arguments, and serves as your class's constructor. Your controller should not have its own __construct() method.

Accessing Common phpBB Variables

The following phpBB variables are automatically inherited as class properties by your controller class when it extends phpbb_extension_controller: $template, $user, $db, $request, $config, $phpbb_root_path, $phpEx

To access these within your class, use the $this-> prefix. For example, the $user object can be accessed as $this->user. Note: These class properties are set within the phpbb_extension_controller::__construct() method. As such, you should use handle() as your constructor method, rather than overwriting the parent constructor.

Fig. 1 - Example Controller Class
<?php

class phpbb_ext_example_foobar_controller extends phpbb_extension_controller
{
    
/**
    * Extension front handler method. This is called automatically when your extension is accessed 
    * through index.php?ext=example/foobar
    * @return null
    */
    
public function handle()
    {
        
// We defined the phpBB objects in __construct() and can use them in the rest of our class like this
        
echo 'Welcome, ' $this->user->data['username'];

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

    
/**
    * Display method - This is not a required method, but just for example.
    *
    * @return null
    */
    
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');

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