Extensions in phpBB 3.1

tas2580  

Bald wird phpBB 3.1 kommen und damit werden die Mods aus phpBB 3.0 nicht mehr funktionieren. Eine der größten Neuerungen in phpBB 3.1 ist das es keine Mods mehr geben wird, stattdessen wird es Extensions geben. Ein großer Unterschied zu den Mods aus phpBB 3.0 ist das man zum einbauen keine Änderungen am Code mehr machen muss. Eine Extension wird in phpBB 3.1 nur hoch geladen und kann dann im Adminbereich aktiviert und auch wieder deaktiviert werden. Für die meisten Foren-Admins dürfte das eine sehr nette Sache sein. Für Mod-Schreiber ist das erstellen von Extensions leider ein bisschen aufwendiger geworden wie das erstellen von einfachen phpBB 3.0 Mods. Ich werde hier an einem kleinen Beispiel zeigen wie man eine einfache Extension für phpBB 3.1 erstellt.

Eine Extension liegt komplett im Ordner /ext/AUTOR/NAME/ in diesem Beispiel wäre das also /ext/tas2580/test/. Extensions sind also nach ihren Autoren geordnet. In diesem Ordner muss eine Datei mit dem Namen composer.json liegen. Der Inhalt der Datei sieht folgendermaßen aus:

{
	"name": "tas2580/test",
	"type": "phpbb-extension",
	"description": "A simple test extension",
	"homepage": "https://tas2580.net",
	"version": "0.1.0",
	"time": "2014-15-10",
	"license": "GPL-2.0",
	"authors": [{
			"name": "Tobias Schäfer",
			"email": "mail@tas2580.net",
			"homepage": "https://tas2580.net",
			"role": "Lead Developer"
		}],
	"require": {
		"php": ">=5.3.3"
	},

	"extra": {
		"display-name": "Test Extension",
		"soft-require": {
			"phpbb/phpbb": ">=3.1.0-RC4,<3.2.*@dev"
		}
	}
}

Hier werden Angaben zur Extension selber und zum Autor gemacht. Außerdem kann angegeben werden welche PHP Version und welche phpBB Versionen unterstützt werden.

Die zweite Datei die mindestens in jeder Extension enthalten sein sollte ist die /ext/AUTOR/NAME/ext.php und sieht folgendermaßen aus:

<?php
/**
*
* @package phpBB Extension - tas2580 test
* @copyright (c) 2014 tas2580
* @license http://opensource.org/licenses/gpl-2.0.php GNU General Public License v2
*
*/

namespace tas2580\test;

/**
* @ignore
*/

class ext extends \phpbb\extension\base
{
}

Hier können über die Mehtoden enable_step(), disable_step() und purge_step() spezielle Anweisungen gegeben werden die bei der Installation und Deinstallation ausgeführt werden. Im Normalfall reicht es aber wenn man die Datei leer lässt und phpBB den Job überlässt.

Jetzt hat man eigentlich schon eine fertige Extension die man im Admin-Bereich installieren kann. Allerdings kann die Extension jetzt noch nichts da ja noch kein eigener Code der die Extension irgendwas machen lässt vorhanden ist.

Neue Seite anlegen

Oft benötigt man für seine Extension eine neue Seite. Früher hat es gereicht einfach im Root-Pfad eine seite.php anzulegen. Das ist jetzt ein bisschen Komplizierter geworden. Für eine einfache Seite werden wieder mind. vier Dateien benötigt. Zu erst muss das Routing definiert werden, dazu benötigt man die /ext/AUTOR/NAME/config/routing.yml, im einfachsten Fall sieht sie folgendermaßen aus:

test_base_controller:
    pattern: /test
    defaults: { _controller: tas2580.test.controller:base, page: 1 }

Hier wird angegeben das beim Aufruf von .../ext.php/test die Klasse test aufgerufen wird, für den Parameter page wird eine 1 übergeben.

Außerdem benötigt man die Datei /ext/AUTOR/NAME/config/services.yml in der angegeben wird was man alles an die Klasse der neuen Seite übergeben möchte. Für die meisten Vorhaben sollten die im folgenden Beispiel aufgelisteten Services ausrechen.

services:
    tas2580.test.controller:
        class: tas2580\test\controller\main
        arguments:
            - @config
            - @template
            - @user
            - @controller.helper
            - %core.root_path%
            - %core.php_ext%

Dann braucht man natürlich noch die Datei für den Code der neuen Seite. Hier muss man darauf achten das die Parameter im __construct() mit den Angaben in der services.yml übereinstimmen. Die Datei wird dann unter /ext/AUTOR/NAME/controller/main.php abgelegt.

<?php
/**
*
* @package phpBB Extension - tas2580 test
* @copyright (c) 2014 tas2580
* @license http://opensource.org/licenses/gpl-2.0.php GNU General Public License v2
*
*/

namespace tas2580\test\controller;

class 
main
{
   
/**
   * Constructor
   * NOTE: The parameters of this method must match in order and type with
   * the dependencies defined in the services.yml file for this service.
   *
   * @param \phpbb\config   $config      Config object
   * @param \phpbb\template   $template   Template object
   * @param \phpbb\user   $user      User object
   * @param \phpbb\controller\helper      $helper            Controller helper object
   * @param string         $root_path   phpBB root path
   * @param string         $php_ext   phpEx
   */
   
public function __construct(\phpbb\config\config $config, \phpbb\template\template $template, \phpbb\user $user, \phpbb\controller\helper $helper$root_path$php_ext)
   {
      
$this->config $config;
      
$this->template $template;
      
$this->user $user;
      
$this->helper $helper;
      
$this->root_path $root_path;
      
$this->php_ext $php_ext;
   }

   
/**
   * Base controller to be accessed with the URL /test/{page}
   * (where {page} is the placeholder for a value)
   *
   * @param int   $page   Page number taken from the URL
   * @return Symfony\Component\HttpFoundation\Response A Symfony Response object
   */
   
public function base($page 1)
   {


      
/*
      * The render method takes up to three other arguments
      * @param   string      Name of the template file to display
      *                  Template files are searched for two places:
      *                  - phpBB/styles/<style_name>/template/
      *                  - phpBB/ext/<all_active_extensions>/styles/<style_name>/template/
      * @param   string      Page title
      * @param   int         Status code of the page (200 - OK [ default ], 403 - Unauthorized, 404 - Page not found, etc.)
      */
      
return $this->helper->render('test_body.html'$this->user->lang['TEST_TITLE']);
   }
}

Innerhalb der Mehtode base() kann man jetzt seinen PHP Code schreiben, am Ende wird die Seite dann ausgegeben, hier wird dann auch angegeben wie die passende Template Datei heißt. Die Datei muss unter /ext/AUTOR/NAME/styles/prosilver/template/ angelegt werden. Eine Template Datei könnte dann folgendermaßen aussehen:

<!-- INCLUDE overall_header.html -->
Hier dein HTML Code
<!-- INCLUDE overall_footer.html -->

Da man Text nie direkt ausgeben sollte sondern dafür Sprach Variablen verwenden sollte benötigen wir noch eine Sprachdatei in der zu den Sprach-Variablen Texte definiert werden. Die Datei liegt unter /ext/AUTOR/NAME/language/common.php und sieht folgendermaßen aus:

<?php
/**
*
* @package phpBB Extension - tas2580 test
* @copyright (c) 2014 tas2580
* @license http://opensource.org/licenses/gpl-2.0.php GNU General Public License v2
*
*/

if (!defined('IN_PHPBB'))
{
    exit;
}

if (empty(
$lang) || !is_array($lang))
{
    
$lang = array();
}

$lang array_merge($lang, array(
    
'ACP_TEST'                => 'Test',
    
'ACP_TEST_TITLE'            => 'Test Extension1',
    
'TEST_TITLE'                => 'Test Titel',
));

Die hier im Beispiel eingetragenen Variablen werden später für das Admin Modul benötigt. Die Datei kann nach belieben um auf der neu angelegten Seite verwendete Sprach-Variablen erweitert werden.

Events anlegen

Events können genutzt werden um eigenen Code an bestimmten Stellen innerhalb von phpBB auszuführen. In folgendem Beispiel wird beim aufrufen der page_header() Funktion ein weiterer Link zur neu angelegten Seite eingefügt und beim Aufruf von user_setup() unsere Sprachdatei eingebunden so das sie global verfügbar ist. Wenn die Sprachdatei etwas größer ist sollte man sie aufsplitten und alles was nur auf der neuen Seite gebraucht wird in eine extra Datei packen die man dann beim Aufruf der Seite extra einbinden kann. Um Events anzulegen wird die Datei /ext/AUTOR/NAME/event/main_listener.php benötigt.

<?php
/**
*
* @package phpBB Extension - tas2580 test
* @copyright (c) 2014 tas2580
* @license http://opensource.org/licenses/gpl-2.0.php GNU General Public License v2
*
*/

namespace tas2580\test\event;

/**
* @ignore
*/
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

/**
* Event listener
*/
class main_listener implements EventSubscriberInterface
{
    static public function 
getSubscribedEvents()
    {
        return array(
            
'core.user_setup'            => 'load_language_on_setup',
            
'core.page_header'            => 'add_page_header_link',
        );
    }

    
/* @var \phpbb\controller\helper */
    
protected $helper;

    
/* @var \phpbb\template\template */
    
protected $template;

    
/**
    * Constructor
    *
    * @param \phpbb\controller\helper    $helper        Controller helper object
    * @param \phpbb\template            $template    Template object
    */
    
public function __construct(\phpbb\controller\helper $helper, \phpbb\template\template $template)
    {
        
$this->helper $helper;
        
$this->template $template;
    }

    public function 
load_language_on_setup($event)
    {
        
$lang_set_ext $event['lang_set_ext'];
        
$lang_set_ext[] = array(
            
'ext_name' => 'tas2580/test',
            
'lang_set' => 'common',
        );
        
$event['lang_set_ext'] = $lang_set_ext;
    }

    public function 
add_page_header_link($event)
    {
        
$this->template->assign_vars(array(
            
'U_TEST_PAGE'    => $this->helper->route('tas2580_test_controller'),
        ));
    }
}

Außerdem wird für den Link im Header noch eine Template Datei gebraucht, die unter /ext/AUTOR/NAME/styles/prosilver/template/event/overall_header_navigation_prepend.html angelegt wird. Der Inhalt der Datei ist recht einfach und enthält nur den Link zur neuen Seite.

<li class="small-icon"><a href="{U_TEST_PAGE}">{L_TEST_TITLE}</a></li>

Events können also nicht nur für Funktionen innerhalb von phpBB genutzt werden sondern auch im Template. Eine vollständige Liste aller Events gibt es hier. Sollte man weitere Events benötigen kann man im dafür eingerichteten Forum ein Request erstellen.

Ein Admin Modul anlegen

Für ein einfaches Modul im Adminbereich werden mind. 3 Dateien benötigt. Auch diese Dateien liegen komplett im Ordner der Extension. Die erste Datei liefert Informationen zum Admin Modul und liegt unter /ext/AUTOR/NAME/acp/test_info.php, die darin enthaltene Klasse muss den Namen der Datei haben und könnte folgendermaßen aussehen:

<?php
/**
*
* @package phpBB Extension - tas2580 test
* @copyright (c) 2014 tas2580
* @license http://opensource.org/licenses/gpl-2.0.php GNU General Public License v2
*
*/

namespace tas2580\test\acp;

class 
test_info
{
    function 
module()
    {
        return array(
            
'filename'    => '\tas2580\test\acp\test_module',
            
'title'        => 'ACP_TEST_TITLE',
            
'version'    => '1.0.0',
            
'modes'        => array(
                
'settings'    => array(
                    
'title' => 'ACP_TEST',
                    
'auth' => 'ext_tas2580/test && acl_a_board'
                    
'cat' => array('ACP_TEST_TITLE')
                ),
            ),
        );
    }
}

Die zweite Datei enthält den eigentlichen Code des Admin Moduls, sie liegt unter /ext/AUTOR/NAME/acp/test_module.php. Auch hier muss der Name der Klasse wieder gleich wie der Name der Datei sein.

<?php
/**
*
* @package phpBB Extension - tas2580 test
* @copyright (c) 2014 tas2580
* @license http://opensource.org/licenses/gpl-2.0.php GNU General Public License v2
*
*/

namespace tas2580\test\acp;

class 
test_module
{
    public 
$u_action;

    public function 
main($id$mode)
    {
        global 
$user$template;

        
$this->tpl_name 'test_body';
        
$this->page_title $user->lang('ACP_TEST_TITLE');

        
/* Hier kommt dein PHP Code für den Adminbereich hin */

        
$template->assign_vars(array(
            
'VARIABLE'                => 'Test Variable',
        ));
    }
}

Als letztes wird noch eine Datei für das Template benötigt. Die Datei liegt unter /ext/AUTOR/NAME/adm/style/test_body.html wobei der Name der Datei in der test_module.php mit $this->tpl_name 'test_body'; angegeben wird. Der Inhalt der Datei sieht dann folgendermaßen aus:

<!-- INCLUDE overall_header.html -->
Hier dein HTML Code oder die {VARIABLE} die im PHP Code definiert wurde.
<!-- INCLUDE overall_footer.html -->

Das anlegen von UCP oder MCP Modulen funktioniert genau gleich nur das sie eben in den entsprechenden Ordnern angelegt werden müssen.

Fazit

Als Mod-Schreiber muss man sich in Zukunft deutlich mehr mit phpBB befassen um alle Events zu kennen. Es reicht nicht mehr einfach in den Code zu schauen und an irgend welchen Stellen seine Änderungen zu machen. Außerdem benötigt man jetzt auf jeden Fall neue Dateien, eine einfache install.xml die man im Browser aufrufen kann reicht für eine Extension nicht mehr. Für Betreiber von phpBB Foren ohne Programmierkenntnisse wird es aber in Zukunft deutlich einfacher Extensions zu installieren.


Ähnliche Beiträge


Kommentare

Kommentar #121

nice example, german is not my native language

I now make a request
how to make a module donors for your extension paypal

thanks Joe

Kommentar #124

Hallo ;D
Schönes Tutorial ;D Nur wie wird die erstellte seite im Forum aufgerufen ?

Kommentar #125

Indem du die URL die in der routing.yml angegeben wurde aufrufst. In dem Beispiel wäre es FORENURL/test.
Wenn du ein Link einfügen willst musst du ein Template Event dazu erstellen.


Kommentar schreiben

URLs werden automatisch umgewandelt.
[b]DEIN TEXT[/b] für Fett gedruckt
[quote]DEIN ZITAT[/quote] für Zitate
[code]DEIN CODE[/code] für Code
captcha