Informationen zu Plugins - Doku

Informationen zu Plugins

Was ist ein Plugin?

Durch Plugins wird das Forum um Funktionen erweitert. Im Grunde genommen beinhalten Plugins PHP-Code, der an bestimmten Stellen im Code des Forums, so genannten Hooks (=Haken), ausgeführt wird. Eine Auflistung aller Hooks finden Sie weiter unten auf dieser Seite.

Wie funktioniert ein Plugin?

Wenn ein Plugin im Admin-CP aktiviert wird, wird sein Codename (der Dateiname ohne die Endung .php) im Cache plugins abgelegt.

Alle aktiven Plugins werden am Anfang jeder Seite geladen (weshalb sehr viele aktive Plugins den Seitenaufbau verlangsamen können). Die zu verwendenden Hooks werden dabei zwischengespeichert.

Wird eine Seite aufgerufen wird gesucht, ob an die Hooks, die ausgeführt werden, Plugins gekoppelt sind. Ist das der Fall wird der Plugincode ausgeführt.

Wie installiere ich ein Plugin?

Hier finden Sie eine kurze Anleitung wie ein Plugin installiert wird. Bitte beachten Sie dass für verschiedene Plugins zusätzliche Schritte erforderlich sind. Weitere Informationen finden Sie in der jeweiligen Readme.

Laden Sie die Plugindatei (die in dem Format pluginname.php vorliegen muss) in den Ordner inc/plugins/ des Forums. Der Dateiname darf nicht geändert werden.
Gehen Sie im Admin-CP in den Plugin-Manager.
Suchen Sie das Plugin in der Liste und aktivieren Sie es.
Wenn das Plugin erfolgreich aktiviert werden kann, werden Sie zurück zur Übersicht aller Plugins geleitet.

Wie ist ein Plugin aufgebaut?

Vorab ein Hinweis: Da Plugins wie auch das Forum in PHP programmiert sind, ist ein Grundwissen in PHP/MySQL und eine gewisse Kenntnis des MyBB erforderlich. Ein Beispielplugin liegt dem MyBB bei mit dem Dateinamen hello.php. Diese befindet sich im Order inc/plugins/.

Die Funktionen zur Information, Aktivierung, Deaktivierung müssen dem Codenamen des Plugins entsprechen (also dem Dateinamen ohne die Endung .php) mit dem jeweiligen Zusatz _info, _activate oder _deactivate. Ist der Dateiname Ihres Plugins beispielsweise foo.php trägt die dazugehörige Informations-Funktion den Namen foo_info().

<?php
// Direktzugriff auf die Datei aus Sicherheitsgründen sperren
if(!defined("IN_MYBB"))
{
	die("Direct initialization of this file is not allowed.<br /><br />Please make sure IN_MYBB is defined.");
}
 
// Die Informationen, die im Pluginmanager angezeigt werden
function pluginname_info()
{
	return array(
		"name"		=> "Pluginname",
		"description"	=> "Pluginbeschreibung",
		"website"	=> "Webseite des Plugins (Herstellerseite)",
		"author"	=> "Name des Erstellers",
		"authorsite"	=> "Webseite des Erstellers",
		"version"	=> "Version",
		"compatibility" => "Kompatible MyBB-Version (Sternchen als Platzhalter möglich); z.B. 18*"
	);
}
 
// Diese Funktion wird aufgerufen, wenn das Plugin installiert wird (optional).
function pluginname_install()
{
}
 
// Diese Funktion wird aufgerufen, wenn das Plugin deinstalliert wird (optional).
function pluginname_uninstall()
{
}
 
// Funktion zur Überprüfung des Installationsstatus; liefert true zurürck, wenn Plugin installiert, sonst false (optional).
function pluginname_is_installed()
{
} 
 
// Diese Funktion wird aufgerufen, wenn das Plugin aktiviert wird.
function pluginname_activate()
{
}
 
// Diese Funktion wird aufgerufen, wenn das Plugin deaktiviert wird.
function pluginname_deactivate()
{
}

Technisch gesehen müssen die Funktionen zur Aktivierung und Deaktivierung nicht in der Plugindatei vorhanden sein, wenn sie nicht benötigt werden. Ebenso sind die Funktionen zur Installation und Deinstallation optional. Wenn diese nicht vorhanden sind, lässt sich das Plugin „nur“ (de)aktivieren. Ansonsten lässt sich ein Plugin (de)installieren und (de)aktivieren. Diese zusätzliche Funktion ergibt dann einen Sinn, wenn ein Plugin z.B. Daten in der Datenbank ablegt. Diese werden dann bei der Deaktivierung nicht gelöscht.

Die Funktionen in Ihrem Plugin können Sie nach Ihren Wünschen benennen. Es ist ratsam, den Codenamen des Plugins als Präfix zu wählen, so dass es nicht zu Überschneidungen mit anderen Plugins kommt (ist der Name der Plugindatei beispielsweise foo.php können Sie die Funktionen foo_run, foo_bar, foo_foo, etc. nennen).

Wenn Ihr Plugin neue Einstellungen in die Forensoftware integriert, sollten Sie nach der Aktivierung/Deaktivierung die Einstellungen erneuern, d.h. die Datei settings.php neu beschreiben lassen, so dass die neuen Werte übernommen werden. Dafür gibt es im MyBB die Funktion rebuild_settings();.

Das Hook-System

Jetzt kommen sie schon erwähnten Hooks ins Spiel. Darüber bestimmen Sie an welcher Stelle Ihr Plugin ausgeführt wird. Es gibt zwei Arten von Hooks:

Hooks ohne Argumente
Hooks mit Argumenten

Zunächst schauen wir uns die Hooks ohne Argumente an. Der Code dazu sieht folgendermaßen aus:

$plugins->run_hooks("global_end");

Der Name des Hooks ist global_end, womit das Plugin am Ende der Datei global.php des Forums ausgeführt würde. Dazu müssten Sie nur die genannte Zeile am Anfang in Ihr Plugin einfügen und um die gewünschte auszuführende Funktion ergänzen:

$plugins->add_hook("global_end", "foo_functionname");

Wie man sieht wird der Hook im ersten Parameter angegeben und der Funktionsname im zweiten Argument. An die add_hook-Methode können zwei weitere Optionale Parameter übergeben werden: die Priorität und eine weitere Datei, die eingebunden werden soll:

$plugins->add_hook("global_end", "foo_functionname", 5, "anotherfile.php");

Die Priorität gibt an in welcher Reihenfolge Plugins an einem Hook ausgeführt werden. Eine Funktion mit einem niedrigen Prioritätswert wird vor einer Funktion mit einem höheren Wert ausgeführt. So wird zum Beispiel eine Funktion mit der Priorität 0 vor einer Funktion mit der Priorität 1 aufgerufen. Der Standardwert ist 10. Im Normalfall muss keine Priorität angegeben werden, es sei denn zwei Funktionen kollidieren an einem Hook. Wird eine Datei angegeben, wird diese einmalig vor der Ausführung der Funktion eingebunden.
Als nächstes werfen wir einen Blick auf die Hooks mit Argumenten. Diese werden wie folgt angesprochen:

$contents = $plugins->run_hooks("pre_output_page", $contents);

Dabei sind diese Dinge zu beachten: Die Variable ist ein Argument für den Hook pre_output_page und muss deshalb auch an die Funktionsdefinition in der Plugindatei übergeben werden:

function foo_functionname($contents)
{
}

Der Rückgabewert der Funktion wird wieder in die Variable geschrieben. Deshalb muss Ihre Funktion diese wieder zurückgeben (per return), da die Variable sonst leer ist. Ansonsten Arbeiten die Hooks genau so wie die ohne Argumente.