Die wichtigsten URL und Dateipfad Funktionen für WordPress Theme Entwickler im Überblick

Als Einsteiger in die WordPress Theme Entwicklung können die vielfältigen Funktionen zur Rückgabe der Theme Ordner URL bzw. des Dateipfads am Anfang etwas verwirrend sein. In diesem Beitrag möchte ich deshalb einen Überblick über die verschiedenen URL und Pfad Funktionen in WordPress und ihre Verwendung geben.

Unterschied zwischen URL und Pfad

In WordPress gibt es sowohl Funktionen zur Rückgabe des absoluten Pfads zum Theme Ordner, als auch Funktionen zur Ausgabe der Theme Ordner URL. Beide Arten sind für Theme Entwickler wichtig.

Den absoluten Pfad kann man sich als lokalen Speicherort der Theme Dateien auf dem Webserver vorstellen (z.B.  /home/user/public_html/wp-content/themes/). Dieser wird beispielsweise benötigt, um PHP Dateien im Theme zu laden und intern auf dem Server auszuführen.

JavaScript-, CSS- und Bild-Dateien werden üblicherweise mit der URL eingebunden (z.B. https://domain.com/wp-content/themes/), anstatt einen internen Pfad zu verwenden. Der Grund: Die Dateien werden nicht wie PHP Dateien auf dem Server verarbeitet, sondern von außen vom Browser geladen und von diesem verwendet.

WordPress URL und Pfad Funktionen im Überblick

WordPress hat vier Standard-Funktionen für die Rückgabe der Theme URL bzw. des Theme Pfads, welche sich seit Urzeiten (Version 1.5) im Core befinden.

get_stylesheet_directory und get_stylesheet_directory_uri

Die beiden get_stylesheet_directory Funktionen geben den Pfad/URL des derzeit aktivierten Themes der WordPress Installation zurück. Falls ein Child Theme verwendet wird, verweisen diese Funktionen damit auf den Ordner des Child Themes.

get_stylesheet_directory()
absoluter Pfad zum Child Theme Ordner
z.B. /home/user/public_html/wp-content/themes/child-theme

get_stylesheet_directory_uri()
URL zum Child Theme Ordner
z.B. https://domain.com/wp-content/themes/child-theme

get_template_directory und get_template_directory_uri

Die beiden get_template_directory Funktionen hingegen beziehen sich immer auf das Parent Theme.

get_template_directory()
absoluter Pfad zum Parent Theme Ordner
z.B. /home/user/public_html/wp-content/themes/parent-theme

get_template_directory_uri()
URL zum Parent Theme Ordner
z.B. https://domain.com/wp-content/themes/parent-theme

Anmerkung: In der WordPress Dokumentation ist manchmal auch die Rede von stylesheet directory und template directory. Mit Ersterem ist aufgrund der Funktionen der Ordner des Child Themes gemeint, mit Letzterem der Parent Theme Ordner.

Häufiges Problem: Verwendung eines Child Themes

Ohne Child Theme verweisen alle vier Funktionen auf den gleichen Ordner – den des aktuellen Themes. Es tauchen daher keine Fehler auf, egal ob get_template_directory oder get_stylesheet_directory bzw. deren URL Funktionen verwendet werden.

Häufig wird es erst dann problematisch, wenn ein Child Theme aktiviert wird.

Dann müssen die richtigen Funktionen verwendet werden, um die Dateien zu laden. Mit Verwendung der falschen Funktion wird womöglich auf den falschen Theme Ordner zurückgegriffen, in welchem die Dateien nicht existieren.

Anwendung der Funktionen im WordPress Theme

Wann welche Funktion verwendet wird ist immer situationsbedingt. Im Folgenden möchte ich die typischen Anwendungsfälle zeigen.

Laden von PHP Dateien

Die Funktionen eines WordPress Themes befinden sich in der functions.php. Die meisten Themes sind aber etwas umfangreicher und teilen Funktionen zur besseren Übersichtlichkeit in mehrere Dateien auf.

Deshalb werden in vielen Themes am Ende der functions.php noch weitere Dateien geladen.

require get_template_directory() . '/inc/template-tags.php';
require get_template_directory() . '/inc/customizer.php';

Für das Laden von PHP Dateien benötigen wir den absoluten Pfad, nicht die URL.

Die korrekte Einbindung der Dateien vom (Parent) Theme Ordner erhalten wir daher mit get_template_directory(). Damit funktioniert das Einbinden der Dateien auch noch, wenn Nutzer ein Child Theme erstellen. Mit der Funktion wird weiterhin im Parent Theme nach der Datei gesucht.

Falls du ein Child Theme erstellt und dort eine neue PHP Datei angelegt hast, welche geladen werden soll, musst du folglich get_stylesheet_directory() für die Rückgabe des Pfads des Child Theme Ordners verwenden.

require get_stylesheet_directory() . '/child-theme-options.php';

Es spielt übrigens keine Rolle, ob die Funktionen im Child oder Parent Theme verwendet werden. Der Unterschied zwischen Child & Parent bezieht sich auf den Rückgabewert der Funktionen, nicht in welchem Kontext diese ausgeführt werden.

Exkurs: Für das Laden von Template Dateien stellt WordPress extra Funktionen wie get_template_part() bereit, welche ich bald in einem extra Beitrag vorstellen möchte. Deshalb sollten nur Funktionsdateien auf diese hier beschriebene Weise eingebunden werden.

Einbinden von JavaScript und CSS Dateien

Für externe Dateien, die vom Browser geladen werden, verwenden wir analog die URI Funktionen. Typisch sind hier das Einbinden von JavaScript und CSS Dateien.

wp_enqueue_script( 'custom-script', get_template_directory_uri() . '/js/custom-script.js' );
wp_enqueue_style( 'genericons', get_template_directory_uri() . '/genericons/genericons.css' );

Auch hier nutzen wir wieder get_template_directory_uri, weil sich die entsprechenden JS und CSS Dateien im Parent Theme befinden. Häufig besteht ein Child Theme ja nur aus style.css, functions.php und wenigen Template Dateien.

Falls aber neue CSS und JS Dateien im Child Theme hinzugefügt werden, kann stattdessen die Funktion get_stylesheet_directory_uri verwendet werden.

Laden von Bildern

Zur Vollständigkeit halber erwähne ich auch noch das Laden von statischen Bildern, was ich persönlich eher selten in meinen Themes brauche. Ebenfalls wieder mit URL Funktion.

<img src="<?php echo get_template_directory_uri(); ?>/images/image.png" />

Spezielle Funktion für die style.css

Für die Einbindung der style.css kennt WordPress noch eine spezielle Funktion: get_stylesheet_uri()

Diese verknüpft eigentlich nur get_stylesheet_directory() mit dem String /style.css. Trotzdem sollte immer die spezielle Funktion verwendet werden, weil diese den Filter stylesheet_uri bereit stellt und damit Plugins Zugriff auf das Laden der style.css gibt.

wp_enqueue_style( 'twentysixteen-style', get_stylesheet_uri() );

Neue Funktionen in WordPress 4.7

Mit WordPress 4.7 wurden erst kürzlich vier neue Funktionen eingeführt, welche die alten Funktionen ergänzen und teilweise ersetzen. Diese stelle ich nächste Woche in einem eigenen Beitrag vor.