WordPress Shortcodes verstehen: Eigene Shortcodes erstellen, anpassen und in PHP verwenden

• Was sind Shortcodes in WordPress?
• Wo kann man WordPress Shortcodes verwenden?
• Eigenen Shortcode in WordPress anlegen
• Shortcode mit Attributen erstellen
• Shortcode in Beiträgen und Seiten verwenden
• Shortcodes in PHP verwenden: Theme, Child Theme, functions.php
• Shortcode in PHP ausgeben
• Shortcode Inhalt in einer Variable speichern
• Output Buffering für Shortcodes, die echo statt return nutzen
• Shortcodes anpassen und erweitern
• Vor- und Nachteile von WordPress Shortcodes
• Sicherheit und Best Practices für eigene Shortcodes

Wenn du dich länger mit WordPress beschäftigst, kommst du um Shortcodes kaum herum. Egal ob Kontaktformular, Galerie, Slider oder spezielle Boxen für Hinweise – oft steckt hinter diesen Funktionen ein kurzer Code in eckigen Klammern.

In diesem Beitrag zeige ich dir, was WordPress Shortcodes sind, wie du eigene Shortcodes erstellst, wie du sie in Beiträgen und Seiten einsetzt und wie du Shortcodes direkt in PHP in deinem Theme oder Child Theme verwenden kannst. Außerdem schauen wir uns Vor- und Nachteile von Shortcodes an und ein paar Best Practices, damit dein Code später noch wartbar bleibt.

Was sind Shortcodes in WordPress?

Shortcodes sind kleine Platzhalter in eckigen Klammern, zum Beispiel:

[gallery]
[contact-form-7 id="123"]
[mein_shortcode foo="bar"]

WordPress erkennt solche Shortcodes beim Rendern des Inhalts und ersetzt sie durch HTML Code oder andere Ausgaben. Die eigentliche Logik steckt in PHP Funktionen, die über die Shortcode API registriert werden.

Kurz gesagt:
Shortcodes sind eine Abkürzung, um komplexe Funktionen in WordPress Beiträge und Seiten einzubauen, ohne dass der Redakteur PHP schreiben muss.

Typische Beispiele für WordPress Shortcodes:

• Kontaktformulare
• Bildergalerien und Slider
• Info Boxen, Buttons, Akkordeons
• dynamische Listen, zum Beispiel neueste Beiträge oder Produkte

Wo kann man WordPress Shortcodes verwenden?

Shortcodes beschränken sich nicht nur auf Beiträge oder Seiten. Du kannst sie an vielen Stellen in deinem WordPress Projekt nutzen.

Ort	Beispiel	Hinweis
Beiträge und Seiten (Gutenberg)	Shortcode Block mit [mein_shortcode]	Über den Block „Shortcode“ einfügen
Classic Editor	Direkt in den Inhalt schreiben	Shortcode wird beim Rendern ersetzt
Widgets	Text oder HTML Widget mit [mein_shortcode]	Je nach Theme müssen Shortcodes in Widgets aktiviert sein
PHP Templates	echo do_shortcode('[mein_shortcode]');	Ideal in Theme oder Child Theme
Page Builder / Custom Fields	Viele Builder verarbeiten Shortcodes automatisch	Abhängig vom Plugin

Damit sind Shortcodes flexibel und vor allem dort praktisch, wo du Funktionen wiederverwenden oder an verschiedenen Stellen einbinden möchtest.

Eigenen Shortcode in WordPress anlegen

Eigene Shortcodes legst du mit der Funktion add_shortcode() an. Dabei vergibst du einen Namen und eine Callback Funktion, die die Ausgabe erzeugt.

Ein sehr einfaches Beispiel sieht so aus:

// In die functions.php deines Child Themes oder in ein eigenes Plugin
add_shortcode('my_shortcode', function ($atts) {
    $result = 1 + 1;

    return $result;
});

Ein paar wichtige Punkte dabei:

• Der Shortcode Name ist hier my_shortcode. Du rufst ihn später mit [my_shortcode] auf.
• Die Callback Funktion sollte einen String returnen und nicht direkt echo verwenden.
• So kannst du den Shortcode später auch in einer Variable speichern und flexibel weiterverwenden.

Shortcode mit Attributen erstellen

In der Praxis willst du oft Parameter übergeben, zum Beispiel:

[box color="red" title="Hinweis"]
Mein Box Inhalt
[/box]

Dafür kannst du shortcode_atts() nutzen, um Standardwerte zu definieren und Attribute sauber zu verarbeiten:

add_shortcode('my_box', function ($atts, $content = '') {

    $atts = shortcode_atts([
        'color' => 'blue',
        'title' => '',
    ], $atts, 'my_box');

    $color = esc_attr($atts['color']);
    $title = esc_html($atts['title']);

    ob_start();
    ?>
    <div class="my-box my-box-<?php echo $color; ?>">
        <?php if ($title) : ?>
            <h3 class="my-box-title"><?php echo $title; ?></h3>
        <?php endif; ?>
        <div class="my-box-content">
            <?php echo do_shortcode($content); ?>
        </div>
    </div>
    <?php
    return ob_get_clean();
});

Hier siehst du, wie du:

• Attribute mit Standardwerten versiehst
• die Ausgabe mit esc_attr und esc_html absicherst
• für längere HTML Blöcke Output Buffering nutzt (ob_start() und ob_get_clean())

So bleibt der Code sauber und gut erweiterbar.

Shortcode in Beiträgen und Seiten verwenden

Angenommen du hast den Shortcode my_box aus dem Beispiel oben angelegt. In einem Beitrag oder auf einer Seite kannst du ihn so verwenden:

[my_box color="green" title="Info"]
Das ist eine grüne Box mit einem Info Titel.
[/my_box]

Im Gutenberg Editor gehst du so vor:

1. Beitrag oder Seite bearbeiten
2. Auf das Plus Symbol klicken
3. Nach „Shortcode“ suchen
4. Shortcode Block einfügen
5. Den Shortcode Text eintragen, zum Beispiel [my_box color="green"]Inhalt[/my_box]
6. Beitrag speichern oder veröffentlichen

WordPress ersetzt den Shortcode dann beim Aufruf der Seite automatisch durch den HTML Code aus deiner Funktion.

Shortcodes in PHP verwenden: Theme, Child Theme, functions.php

Manchmal möchtest du Shortcodes direkt in PHP Templates verwenden, zum Beispiel in single.php, page.php oder einem benutzerdefinierten Template.

Dafür gibt es do_shortcode().

Shortcode in PHP ausgeben

Wenn du einen Shortcode direkt im Template ausgeben willst, kannst du ihn so einbauen:

echo do_shortcode('[my_box color="red" title="Achtung"]Inhalt aus dem Template[/my_box]');

• do_shortcode() verarbeitet den Shortcode und gibt einen String zurück
• mit echo gibst du das Ergebnis im Template aus

Shortcode Inhalt in einer Variable speichern

Du kannst das Ergebnis eines Shortcodes auch in einer Variable speichern und weiterverwenden. Das ist zum Beispiel hilfreich, wenn du den Inhalt an mehreren Stellen brauchst oder erst noch bearbeiten möchtest.

Aus deinen Notizen:

$shortcode_content = do_shortcode('[my_shortcode]');

Damit liegt die Ausgabe in $shortcode_content und du kannst sie später ausgeben oder weiter verarbeiten.

Output Buffering für Shortcodes, die echo statt return nutzen

Eigentlich sollten Shortcodes immer mit return arbeiten. In der Realität gibt es aber Plugins, die innerhalb des Shortcodes direkt echo verwenden. In so einem Fall kannst du mit Output Buffering arbeiten:

ob_start();
do_shortcode('[inconvenient_shortcode]');
$shortcode_content2 = ob_get_clean();

• ob_start() startet den Output Buffer
• alles, was der Shortcode ausgibt, landet im Buffer
• mit ob_get_clean() holst du den Inhalt als String in eine Variable und leerst den Buffer

So bekommst du auch bei „unbequemen“ Shortcodes den Inhalt in eine Variable.

Shortcodes anpassen und erweitern

In vielen Projekten möchtest du nicht nur neue Shortcodes schreiben, sondern auch bestehende Shortcodes anpassen oder erweitern, zum Beispiel:

• zusätzliche CSS Klassen ergänzen
• Standardwerte ändern
• die HTML Struktur anpassen

Grundsätzlich hast du zwei Möglichkeiten:

• Einen eigenen Shortcode mit neuem Namen erstellen
• Einen bestehenden Shortcode entfernen und neu registrieren

Beispiel zum Entfernen eines Shortcodes:

add_action('init', function () {
    remove_shortcode('old_shortcode');
});

Danach kannst du mit add_shortcode('old_shortcode', 'meine_neue_funktion'); deine eigene Implementierung hinterlegen. Das solltest du aber nur machen, wenn du genau weißt, welche Auswirkungen das auf bestehende Inhalte hat.

Vor- und Nachteile von WordPress Shortcodes

Shortcodes sind praktisch, aber nicht perfekt. Besonders seit es den Block Editor gibt, lohnt sich ein Blick auf die Vor- und Nachteile.

Vorteil	Nachteil
Einfache Nutzung ohne Programmierkenntnisse	Inhalte sind stark von Theme oder Plugins abhängig
Komplexe Funktionen mit kurzem Text nutzbar	Wenn ein Plugin deaktiviert wird, bleiben Shortcode Fragmente wie [shortcode] im Inhalt
Funktioniert in Beiträgen, Seiten, Widgets und PHP Templates	Viele Shortcodes im Text können den Editor unübersichtlich machen
Ideal für wiederverwendbare Bausteine	Shortcodes sind weniger zukunftssicher als native Blöcke
Einfach in eigene Themes und Child Themes integrierbar	Aufwendige Shortcodes können Performance Probleme verursachen

Für neue Projekte lohnt es sich, zu überlegen, ob ein Gutenberg Block nicht die bessere Lösung ist. Shortcodes sind aber weiterhin sinnvoll, vor allem:

• für kleinere Helfer Funktionen
• in Kombination mit bestehenden Themes und Plugins
• wenn du Funktionen sowohl im Editor als auch in Templates nutzen möchtest

Sicherheit und Best Practices für eigene Shortcodes

Damit deine WordPress Shortcodes sicher und performant bleiben, solltest du ein paar Grundregeln beachten.

1. Eindeutige Namen und Präfixe verwenden Verwende am besten ein Präfix, zum Beispiel deinen Blog Namen oder dein Projektkürzel: add_shortcode('cosci_box', 'cosci_box_shortcode'); So reduzierst du Konflikte mit anderen Themes oder Plugins.
2. Attribute validieren und Ausgaben escapen
   • Attribute über shortcode_atts() mit sinnvollen Standardwerten versehen
   • Ausgabe mit esc_html, esc_attr oder wp_kses absichern
3. Shortcodes sollten return statt echo verwenden Wenn dein Shortcode immer einen String zurückgibt, kannst du ihn in Beiträgen, Seiten, Varianten, Bedingungen und Templates verwenden, ohne Workarounds mit Output Buffering.
4. Performance im Blick behalten Wenn ein Shortcode aufwendige Datenbankabfragen oder externe API Calls macht, kann das bei vielen Vorkommen auf einer Seite zur Bremse werden. Hier helfen Caching, Transients oder eine clevere Abfrage Logik.
5. Shortcodes lieber in ein Plugin auslagern Wenn du deine eigenen Shortcodes in ein kleines Plugin packst, überleben sie auch einen Theme Wechsel. So bleibt dein Projekt langfristig flexibler.