ENDEES
Kontakt aufnehmen

Anleitung · 25. Mai 2025 · Claudia Uztzu

Ein WordPress-Plugin für die Propstack-API entwickeln

Ein Leitfaden für Entwickler: So bauen Sie ein Plugin, das Immobilienangebote über die Propstack-API abruft und auf Ihrer Website anzeigt.

Immobilien-Websites stehen und fallen mit ihren Angeboten. Wenn Sie Ihre Objekte in Propstack verwalten, Ihre öffentliche Website aber auf WordPress läuft, stehen Sie vor einer mühsamen Wahl: jedes Angebot von Hand übertragen oder eine Brücke zwischen beiden Systemen bauen.

In diesem Beitrag zeige ich, wie ich diese Brücke gebaut habe: ein WordPress-Plugin, das Angebote direkt aus der Propstack-API holt und auf Ihrer Website darstellt, automatisch und bei Bedarf.

Das Ziel

Das Plugin muss vier Dinge gut können:

  1. Sich an der Propstack-API authentifizieren und Objektdaten abrufen.
  2. Diese Daten zwischenspeichern, damit die Website schnell bleibt und die API nicht überlastet wird.
  3. Angebote über saubere Templates darstellen, die sich im Theme anpassen lassen.
  4. Sich von Website-Betreibern ohne technischen Hintergrund einrichten und nutzen lassen, ohne dass sie Code anfassen müssen.

Alles andere ist Detail. Gehen wir die einzelnen Teile durch.

Die Kommunikation mit der API

Propstack stellt eine REST-API (Version 2) unter https://api.propstack.de/v2 bereit. Die gesamte Integration ist um eine einzige Klasse PropstackAPI herum gebaut, die jede Anfrage an diesen Endpoint kapselt. Wenn der API-Zugriff in einer Klasse zentralisiert ist, liegen Authentifizierung, Fehlerbehandlung und Caching gebündelt an einer Stelle der Codebasis.

Propstack v2 authentifiziert über einen HTTP-Header, X-Api-Key, und der Schlüssel steht damit nicht in der URL. Das ist sicherer (Schlüssel landen weder in Serverlogs noch im Browserverlauf) und sauberer:

PHP

$args = array(
    'timeout' => 30,
    'headers' => array(
        'X-Api-Key'  => $this->api_key,
        'Accept'     => 'application/json',
        'User-Agent' => $this->get_user_agent(),
    ),
    'sslverify' => true,
);

$response = wp_remote_get($final_url, $args);

Beachten Sie, dass der Code für HTTP die WordPress-eigene Funktion wp_remote_get() verwendet. Das ist Absicht: Anders als direkte cURL-Aufrufe übernimmt die eingebaute HTTP-API die Filter, Proxy-Einstellungen und Fehlerbehandlung von WordPress und liefert aufgeräumte WP_Error-Objekte, die Sie mit is_wp_error() prüfen können. Zuverlässiges Networking bekommen Sie damit ohne Zusatzaufwand.

Caching: Die API nicht mit Anfragen überhäufen

Bei jedem einzelnen Seitenaufruf eine externe API anzufragen ist langsam für Ihre Besucher und verschwendet Ressourcen auf den Servern von Propstack. Das Plugin löst das mit WordPress-Transients, dem nativen Key-Value-Cache.

Jede API-Antwort wird unter einem Transient-Schlüssel mit konfigurierbarer Ablaufzeit gespeichert. Der Standard liegt bei fünf Minuten und ist als Einstellung im Admin-Bereich verfügbar, damit Website-Betreiber zwischen Aktualität und Geschwindigkeit abwägen können. Eine sinnvolle Untergrenze von 60 Sekunden sorgt dafür, dass niemand den Wert versehentlich auf null setzt und die API per DDoS lahmlegt:

PHP

// Minuten-Einstellung in Sekunden umrechnen, nie unter 60.
$this->cache_duration = max(60, intval($cache_setting) * 60);

Wiederkehrende Besucher bekommen sofort Ergebnisse aus dem Cache; die API wird erst angefragt, wenn der Cache abläuft.

Angebote mit Shortcodes darstellen

Der einfachste Weg, damit WordPress-Nutzer dynamische Inhalte an beliebiger Stelle platzieren können, ist der Shortcode. Das Plugin registriert mehrere:

  • [propstack_listings], ein paginiertes Raster von Objekten
  • [propstack_property], die Detailansicht eines einzelnen Objekts
  • [propstack_search], ein Suchformular mit Live-Ergebnissen per AJAX

Ein Website-Betreiber setzt einfach einen Shortcode in eine beliebige Seite oder einen Beitrag. Das Angebotsraster akzeptiert eine ganze Reihe von Attributen für Filter und Layout:

[propstack_listings limit="9" columns="3" city="Berlin" min_price="200000" max_price="800000"]

Intern wird jedes Attribut bereinigt und auf sichere Bereiche begrenzt, bevor es die API erreicht: columns wird auf 1 bis 4 festgelegt, limit auf 1 bis 50, Preise werden in Floats umgewandelt und so weiter. Eingaben aus Shortcodes ist grundsätzlich nicht zu trauen.

Für ein einzelnes Objekt:

[propstack_property id="123" show_gallery="true" show_contact="true"]

Templates, die sich im Theme anpassen lassen

Die Ausgabe läuft über PHP-Template-Dateien (ein Template für das Objektraster, eines für die Einzelansicht, ein Suchformular), getrennt von der Logik, die die Daten holt. Diese Trennung ist wichtig: Das aktive Theme kann das Markup überschreiben, ohne dass jemand das Plugin bearbeiten muss.

Das Plugin sucht zuerst im Theme-Verzeichnis und greift dann auf seine mitgelieferten Templates zurück:

  1. your-theme/propstack/property-card.php
  2. your-theme/propstack-property-card.php
  3. plugin/templates/property-card.php

Designer können Angebote komplett über das Theme neu gestalten, und ihre Änderungen überstehen Plugin-Updates.

Ein „Mehr laden“ ohne Neuladen der Seite

Paginierung über ein komplettes Neuladen der Seite wirkt altmodisch. Das Plugin registriert einen AJAX-Endpoint für angemeldete wie anonyme Besucher, der die nächste Seite mit Objekten abruft und an das Raster anhängt:

PHP

add_action('wp_ajax_load_more_properties', array($this, 'load_more_properties'));
add_action('wp_ajax_nopriv_load_more_properties', array($this, 'load_more_properties'));

Jede AJAX-Anfrage ist mit einer WordPress-Nonce gegen Cross-Site Request Forgery geschützt.

Nutzbar für Nicht-Entwickler

Eine gute Integration ist für die Person, die die Website betreibt, unsichtbar. Der Admin-Bereich umfasst:

  • Eine Einstellungsseite unter „Einstellungen“ mit dem Feld für den API-Schlüssel, der Cache-Dauer, dem Währungssymbol und Standardwerten für Bilder.
  • Einen Button „Test Connection“, der per AJAX eine Anfrage an Propstack schickt, sodass Sie sofort sehen, ob Ihr Schlüssel funktioniert, ohne Herumprobieren.
  • Hinweise im Admin-Bereich, die Sie daran erinnern, Ihren API-Schlüssel einzutragen, falls er fehlt.
  • Kontextbezogene Hilfe-Tabs, die Einrichtung und Shortcode-Nutzung genau dort erklären, wo Sie sie brauchen.

Ein guter Bürger im WordPress-Ökosystem

Der letzte Schliff unterscheidet ein Hobby-Plugin von einem wartbaren:

  • Prüfung der Voraussetzungen bei der Aktivierung. Das Plugin prüft auf PHP 7.4+ und WordPress 5.0+ und verweigert kontrolliert die Aktivierung, wenn diese nicht erfüllt sind, ohne fatale Fehler auszulösen.
  • Übersetzungsfertig. Jeder sichtbare Text steckt in den i18n-Funktionen von WordPress mit einer Text-Domain, sodass sich das Plugin lokalisieren lässt.
  • Sauberes Deinstallieren. Eine eigene uninstall.php entfernt beim Löschen des Plugins alle Optionen, zwischengespeicherten Transients und User-Meta-Daten, sodass kein verwaister Datenmüll in Ihrer Datenbank zurückbleibt.

Was sich übertragen lässt

Die Architektur lässt sich auf fast jede Integration einer Drittanbieter-API in WordPress übertragen:

  1. Kapseln Sie die API in einer Klasse, damit Authentifizierung und Caching an einer einzigen Stelle liegen.
  2. Setzen Sie auf native WordPress-APIs: wp_remote_get() für HTTP, Transients für das Caching, Shortcodes für die Platzierung.
  3. Trennen Sie Daten und Darstellung mit überschreibbaren Templates.
  4. Stellen Sie die Konfiguration über eine Einstellungsseite bereit, und räumen Sie bei der Deinstallation hinter sich auf.

Wenn diese vier Dinge stimmen, ist der Rest wirklich nur noch Templates. Das Ergebnis ist eine Immobilien-Website auf Basis von Propstack, die sich selbst aktualisiert: Ihre Angebote liegen an einem Ort, und Ihre Website bildet sie einfach ab.

→ Alle Beiträge