Nachdem der Kopfbereich einer Plugin-Datei (mein-plugin.php) angelegt wurde, kann mit der Entwicklung begonnen werden.

Sehr oft werden Sie jedoch eine Pfadangabe zu bestimmten Dateien oder Verzeichnissen benötigen. Dazu gehören zum Beispiel andere PHP-Dateien, die per include oder require eingebunden werden.

Eine unvorteilhafte Idee ist es deshalb, diese Pfadangaben “hart” in den Quellcode zu programmieren. Schließlich kann WordPress auch so konfiguriert werden, dass Pfade anders lauten als bei Ihnen.

WordPress bringt schon einige sehr gute Funktionen mit, die Sie benutzen können, um Pfade zu konstruieren. Diese sind nachfolgend aufgeführt.

Lokaler Plugin-Pfad

Ein lokaler Pfad ist nichts anderes als ein „Link” auf eine Datei auf einem Rechner. Nützlich genau dann, wenn Sie eine PHP-Datei per include einfügen möchten. Denn nichts ist wohl unterschiedlicher als der lokale Pfad einer WordPress-Installation. Um den aktuellen Pfad zu Ihrem Plugin herauszufinden, können Sie folgende Funktion nutzen:

<?php
$mm_pfad = plugin_dir_path( __FILE__ );
?>

Die PHP-Konstante __FILE__ gibt dabei den aktuellen Pfad Ihrer mein-plugin.php-Datei zurück. Die Funktion plugin_dir_path() filtert dann lediglich den Dateinamen weg und hängt am Ende einen Slash (/) an. In der Variable $pfad wäre also ein möglicher Rückgabewert der folgende:

/var/www/mm/wordpress/wp-content/mein-plugin/

Um also eine weitere PHP-Datei per require einzufügen, könnten Sie wie folgt vorgehen:

<?php
$mm_pfad = plugin_dir_path( __FILE__ );

require $mm_pfad . 'includes/zweite-datei.php';
?>

Das bedeutet, dass die Datei /var/www/mm/wordpress/wp-content/mein-plugin/includes/zweite-datei.php eingebunden wird.

Da der Pfad zum Plugin-Verzeichnis öfter benötigt wird, empfiehlt es sich, eine eigene Konstante anzulegen.

<?php
define( 'MM_PLUGIN_DIR_PATH', plugin_dir_path( __FILE__ ) );

require MM_PLUGIN_DIR_PATH . 'includes/zweite-datei.php';
?>

Auf Github ansehen

Auch hier gilt: Vergessen Sie bei Variablen und Konstanten nie, das von Ihnen festgelegte Präfix anzufügen.

Plugin-URL

Neben dem Pfad zum Plugin-Verzeichnis ist mitunter auch die genaue URL interessant. Sie dient beispielsweise der Darstellung von Bildern.

<?php
$mm_plugin_url = plugins_url( $path, $plugin );
?>

Die Funktion erfordert zwei Parameter:

• $path (string)
  Eine eventuelle Pfadangabe.
• $plugin (string)
  Die Pfadangabe, auf die sich $path beziehen soll.

Beispiel

<?php
$mm_plugin_url = plugins_url( '', __FILE__ );
?>

Dabei könnte folgendes ausgegeben werden:

http://beispiel.de/wp-contents/plugins/mein-plugin

Zu beachten ist, dass die plugins_url()-Funktion am Ende keinen Slash anhängt. Um dies dennoch zu tun, können Sie die Funktion trailingslashit() benutzen. Außerdem wäre es auch hier sinnvoll, eine eigene Konstante zu definieren.

<?php
$mm_plugin_url = trailingslashit( plugins_url( '', MM_PLUGIN_DIR_PATH ) );
?>

Die Ausgabe wäre dementsprechend:

http://beispiel.de/wp-contents/plugins/mein-plugin/

Ohne Parameter gibt die Funktion die URL zum Plugin-Verzeichnis zurück, in dem alle Plugins liegen:

<?php
$mm_plugin_url = plugins_url();
// ergibt: http://beispiel.de/wp-contents/plugins
?>

Bei Angabe eines Pfades wird dieser angehängt:

<?php
$mm_plugin_url = plugins_url( 'images/mein-bild.jpg', MM_PLUGIN_DIR_PATH );
// ergibt: http://beispiel.de/wp-contents/plugins/mein-plugin/images/mein-bild.jpg
?>

Weitere Funktionen für Pfade und URLs

plugin_dir_url( $file )

Ähnlich wie plugins_url() gibt diese Funktion die URL zum Plugin-Verzeichnis zurück. Eine Pfadangabe ist nicht möglich. Achtung: Hier wird am Ende wieder ein finaler Slash angehängt. Als $file muss der Pfad zum Plugin angegeben werden.

<?php
$mm_plugin_dir_url = plugin_dir_url( __FILE__ );
// ergibt: http://beispiel.de/wp-contents/plugins/mein-plugin/
?>

plugin_basename( $file )

Gibt den Pfad relativ zum Plugin-Verzeichnis zurück. Achtung: Auch diese Funktion hängt am Ende sowie am Anfang keine Slashes an. Als $file muss der Pfad zum Plugin angegeben werden.

<?php
$mm_plugin_basename = plugin_basename( __FILE__ );
// ergibt: mein-plugin/mein-plugin.php
?>

admin_url( $path = ”, $scheme = ‘admin’ )

Gibt die URL zum Administrationsverzeichnis zurück. Ein Slash wird am Ende angehängt. Der Parameter $path erlaubt das Anhängen eines Pfades relativ zur URL. Der Standardwert für $scheme ist admin. Er gibt der URL einen genauen Kontext. Möglich sind darüber hinaus https, http, login, login_post, relative oder natürlich null.

<?php
$mm_admin_url = admin_url();
// ergibt: http://beispiel.de/wp-admin/
?>

site_url( $path = ”, $scheme = null )

Gibt die URL zur aktuellen WordPress-Installation zurück. Dieser Wert stimmt mit der Angabe unter “Einstellungen” » “Allgemein” » “WordPress Adresse (URL)” überein. Der Parameter $path erlaubt das Anhängen eines Pfades relativ zur URL. Der Standardwert für $scheme ist null.

<?php
$mm_site_url = site_url();
// ergibt: http://beispiel.de
?>

content_url( $path = ” )

Gibt die URL zum wp-content Verzeichnis zurück. Achtung: Auch hier wird kein Slash am Ende angehängt. Der Parameter $path erlaubt das Anhängen eines Pfades relativ zur URL.

<?php
$mm_content_url = content_url();
// ergibt: http://beispiel.de/wp-content
?>

includes_url( $path = ” )

Gibt die URL zum wp-includes Verzeichnis zurück. Achtung: Auch hier kein Slash am Ende. Der Parameter $path erlaubt das Anhängen eines Pfades relativ zur URL.

<?php
$mm_includes_url = includes_url();
// ergibt: http://beispiel.de/wp-includes
?>

wp_upload_dir( $time = null )

Gibt ein Array mit folgenden Werten zurück:

• path
  Absoluter Pfad zum wp-content Verzeichnis. Falls “Organisiere Uploads in monats- und jahresbasierten Ordnern” unter “Einstellungen” » “Medien” aktiviert wurde, wird am Ende noch das Jahr sowie der Monat als Zahl angehängt. Wird $time im Format YYYY/MM angegeben, wird jeweils der Ordner für dieses Datum zurückgegeben. Falls $time null ist, wird die Zahl des aktuellen Jahres inklusive Monat zurückgegeben.
• url
  Verhält sich wie die path-Angabe mit dem Unterschied, dass die URL zurückgegeben wird.
• subdir
  Das Unterverzeichnis, falls “Organisiere Uploads in monats- und jahresbasierten Ordnern” aktiviert wurde. Beispiel: /2014/01.
• basedir
  Der Pfad ohne subdir.
• error
  Wird auf false gesetzt, wenn alles ok ist. Ansonsten gibt WordPress hier eine Fehlermeldung zurück, falls kein wp-content-Verzeichnis existiert oder es nicht angelegt werden konnte.

Beispiel:

<?php
$mm_wp_upload_dir = wp_upload_dir();

/**
 * $mm_wp_upload_dir ist ein Array und enthält folgenden Schlüssel und Werte:
 *	path     => /var/www/mm/wordpress/wp-content/uploads/2014/01
 *	url      => http://beispiel.de/wp-content/uploads/2014/01
 *	subdir   => /2014/01
 *	basedir  => /var/www/mm/wordpress/wp-content/uploads
 *	baseurl  => http://beispiel.de/wp-content/uploads
 *	error    => false
 */
?>

home_url( $path = ”, $scheme = null )

Gibt zurück, was unter “Einstellungen” » “Allgemein” » “Seiten-Adresse (URL)” angegeben wurde. Der Parameter $path erlaubt das Anhängen eines Pfades relativ zur URL. Der Standardwert für $scheme ist null.

<?php
$mm_home_url = home_url();
// ergibt: http://beispiel.de
?>

Beachten Sie, dass diese Funktion in den meisten Fällen dasselbe zurückgibt wie site_url. Nur wenn die Startseite in einem anderen Verzeichnis als die WordPress-Installation liegt, gibt home_url etwas anderes zurück.

Pfade und URLs für Themes

Unter http://codex.wordpress.org/DeterminingPluginandContentDirectories finden Sie eine Sammlung aller möglichen Funktionen, die entweder Pfade oder URLs zurückgeben. So gibt es separate Funktionen für das Entwickeln von Themes, die in diesem Buch allerdings nicht besprochen werden.

Pfade und URLS für Multisite-Instanzen

Darüber hinaus gibt es auch Funktionen zum Abruf von Multisite-URLs und Pfaden. Diese können meist mit get_* oder network_* Präfix aufgerufen werden.

• get_admin_url( $blog_id = null, $path = '', $scheme = 'admin' )
  Wie admin_url jedoch mit erforderlicher Angabe der Blog ID.
• get_home_url( $blog_id = null, $path = '', $scheme = null )
  Wie home_url() jedoch mit Angabe der Blog ID.
• get_site_url( $blog_id = null, $path = '', $scheme = null )
  wie site_url jedoch mit Angabe der Blog ID.
• network_admin_url( $path = '', $scheme = 'admin' )
  wie admin_url() jedoch bezogen auf den Netzwerk-Administrationsbereich.
• network_site_url( $path = '', $scheme = null )
  wie site_url() jedoch bezogen auf den Netzwerk-Blog (in der Regel der erste Blog, der angelegt wurde).
• network_home_url( $path = '', $scheme = null )
  wie home_url() jedoch bezogen auf den Netzwerk-Blog (in der Regel der erste Blog, der angelegt wurde).

Plugin-Aktivierung

Nicht selten kommt es vor, dass Plugins bereits bei der Aktivierung bestimmte Aufgaben erledigen sollen. Ein Beispiel wäre das zusätzliche Anlegen einer Datenbanktabelle oder das Setzen von Standard-Einstellungen. Genau für diesen Fall gibt WordPress Ihnen die Möglichkeit, per register_activation_hook( $file, $function ) eine Funktion anzugeben, die Aktivierungs-Aufgaben durchführt.

<?php
define( 'MM_PLUGIN_FILE', __FILE__ );

register_activation_hook( MM_PLUGIN_FILE, 'mm_activation' );

function mm_activation(){
	// mach etwas
}
?>

Auf Github ansehen

Wie Sie sehen benötigt der erste Parameter die Pfadangabe zum aktuellen Plugin, die wir über __FILE__ bzw. die Konstante MM_PLUGIN_FILE übergeben. Der zweite Parameter benötigt den Namen der Funktion, die bei Aktivierung ausgeführt werden soll.

Plugin-Deaktivierung

Genauso wie die Plugin-Aktivierung funktioniert auch die Plugin-Deaktivierung. Die Funktion register_deactivation_hook() erwartet dieselben Parameter.

<?php
define( 'MM_PLUGIN_FILE', __FILE__ );

register_deactivation_hook( MM_PLUGIN_FILE, 'mm_deactivation' );

function mm_deactivation(){
// mach etwas
}
?>

Auf Github ansehen

Diese Funktion sollte übrigens nicht dazu benutzt werden, das Plugin zu deinstallieren. Das soll heißen: Keine Dateien, Einstellungen oder Tabellen, die das Plugin zur Aktivierung angelegt hat, sollen mit der Deaktivierung gelöscht werden.

Warum sollen bei der Deaktivierung keine Daten gelöscht werden?

Ein Plugin zu deaktivieren bedeutet nicht gleich, es zu deinstallieren. Installiert man WordPress beispielsweise als „normalen“ Blog und aktiviert erst später die Multisite-Funktionalität, wird man aufgefordert, vorher alle Plugins zu deaktivieren.

Erst nach der Umstellung auf Multisite kann man alle Plugins wieder aktivieren. Es wäre recht unerfreulich, wenn man später merkt, dass plötzlich alle Einstellungen eines Plugins verschwunden sind. Für den Endbenutzer bedeutet das Frust pur.

Die Deinstallation sollte über die uninstall.php geschehen. Doch dazu gleich mehr.

Plugin-Deinstallation

Wenn ein Plugin Daten oder Dateien bei der Installation anlegt, sollte man dafür sorgen, dass diese beim Löschen auch wieder passend entfernt werden. WordPress kümmert sich nicht automatisch darum, denn es führt nicht Buch darüber, welche Daten von Ihrem Plugin hinzugefügt werden.

Denken Sie dabei immer an sich selbst. Sie möchten auch gerne, dass eine Software alle Teile, die sie bei der Installation angelegt hat, bei der Deinstallation wieder entfernt. Sie möchten nicht, dass etwas übrig bleibt. Immerhin sollte der Speicher auch wieder freigegeben werden, wenn er nicht mehr benötigt wird.

Grundsätzlich gibt es zwei Möglichkeiten, ein Plugin zu deinstallieren:

uninstall.php

Die erste Methode behandelt die Deinstallation mittels uninstall.php. Wie weiter oben bereits angedeutet, muss sich diese Datei im Stammverzeichnis Ihres Plugins befinden. Sie wird dann ausgeführt, wenn das Plugin aus der Liste der Plugins gelöscht wird. Und hier liegt auch gleich der Hund begraben. “Löschen” bedeutet nämlich nicht auch sofort “Deinstallieren”. Viele WordPress-User klicken nicht auf den Löschen-Link, sondern entfernen Plugins direkt per FTP. Damit wird die Deinstallations-Routine gar nicht erst aufgerufen. Nichtsdestotrotz sollte man Gebrauch davon machen.

<?php
// uninstall.php

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

if ( ! WP_UNINSTALL_PLUGIN ) {
	exit();
}

// entferne etwas
?>

Auf Github ansehen

Wie Sie sehen, muss die Konstante WP_UNINSTALL_PLUGIN zuerst überprüft werden. Nur wenn sie existiert, wird die Deinstallation ausgeführt.

Vorsicht ist geboten, wenn Sie Zugriff auf Funktionen benötigen, die sich im Plugin befinden. Es wird nämlich während der Deinstallation nicht geladen. Wird eigener Plugin-Code benötigt, sollte man stattdessen auf die Funktion register_uninstall_hook() zurückgreifen.

register_uninstall_hook()

Die register_uninstall_hook()-Funktion wird dann aufgerufen, wenn keine uninstall.php gefunden werden konnte.

Hier gilt: Mitunter kann es zu Problemen kommen, wenn Sie in Ihrer Plugin-Datei Quellcode ausführen lassen, der sich nicht innerhalb einer Funktion bzw. eines Hooks befindet. Generell sollte ausführbarer Code immer innerhalb von Funktionen (oder Methoden) stehen. Der Grund ist, dass WordPress das Plugin laden muss, bevor der Uninstall-Hook ausgeführt werden kann. Das bedeutet, dass ein anderer Plugin-Code möglicherweise mit ausgeführt wird, falls er nicht innerhalb einer Funktion steht. Das wiederum kann dafür sorgen, dass das Plugin nicht deinstalliert wird.

<?php
register_activation_hook( __FILE__, 'mm_activation' );

function mm_activation() {
	register_uninstall_hook( __FILE__, 'mm_uninstall' );
}

function mm_uninstall() {
	/* Ihr Code */
}
?>

Auf Github ansehen

Wie Sie sehen, wird im obigen Beispiel die Funktion mm_uninstall nur einmalig bei Plugin-Aktivierung registriert. Das sorgt dafür, dass WordPress die Funktion nicht immer lädt, wenn eine Admin-Seite aufgerufen wird.

Hinweis zum Testen:

Wundern Sie sich nicht, wenn die Deinstallations-Routine nicht aufgerufen wird, wenn das Plugin noch nie aktiviert wurde. Das Plugin muss mindestens einmal aktiviert worden sein, bevor die von Ihnen registrierte Funktion zur Deinstallation aufgerufen werden kann.

3. http://de.wikipedia.org/wiki/GNUGeneralPublicLicense Stand: 2. Januar 2014 Stand: 2. Januar 2014 ↩︎
4. http://www.phpbench.com/ Stand: 2. Januar 2014. ↩︎
5. http://www.php.net/ChangeLog-5.php#5.3.0 Stand: 3. Januar 2014 ↩︎
6. http://www.php.net/ChangeLog-5.php#5.5.0 Stand: 3. Januar 2014 ↩︎