Fünf kampferprobte Techniken, die Ihr WordPress-API-Entwickler nicht verwendet

Eine der besten Möglichkeiten, Ihren Status als WordPress-Entwickler zumindest in den Augen Ihrer Kunden zu verbessern, besteht darin, sich im Umgang mit APIs zurechtzufinden. Hier ist ein gängiges Szenario für die WordPress-API-Implementierung: Ihr Kunde bittet Sie, ein Widget zu seiner Website hinzuzufügen – sagen wir zum Beispiel ein E-Mail-Abonnement-Widget. Sie holen sich einen Code von ihrem E-Mail-Dienst eines Drittanbieters – vielleicht ist es ein Skript-Tag oder ein iframe – fügen ihn in die Seite ein und antworten Ihrem Client: „Verstanden!“

Leider haben Sie es mit einem etwas anspruchsvolleren Kunden zu tun, dem folgende Mängel auffallen:

• Obwohl das Widget, wie der Rest der Seite, eine serifenlose Schriftart enthält, ist es nicht ganz die richtige. Das Widget verwendet Helvetica anstelle der von Ihnen installierten benutzerdefinierten Schriftart.
• Das Abonnementformular des Widgets löst das Laden einer neuen Seite aus, was störend sein kann, wenn es mitten in einem Artikel platziert wird.
• Das Widget scheint nach dem Rest der Seite einen zusätzlichen Moment zum Laden zu benötigen, was sich unangenehm und billig anfühlt.
• Der Kunde möchte, dass Abonnenten basierend auf dem Beitrag, den sie abonniert haben, mit Metadaten markiert werden, und das Widget bietet nichts, was dieser Funktionalität auch nur im Entferntesten ähnelt.
• Der Kunde findet es nervig, dass er nun zwei Dashboards verwalten muss (wp-admin und den Admin-Bereich für den E-Mail-Dienst).

An diesem Punkt könnte vernünftigerweise eines von zwei Dingen passieren. Sie könnten diese Dinge als „Nice-to-haves“ deklarieren und Ihren Kunden von den Vorzügen einer 80/20-Lösung überzeugen, oder Sie könnten diese Anforderungen erfüllen. Nach meiner persönlichen Erfahrung habe ich festgestellt, dass die Erfüllung solcher Anfragen – das heißt, die Beherrschung der Dienste von Drittanbietern zu demonstrieren – ein zuverlässiger Weg ist, den Kunden davon zu überzeugen, dass Sie eine Art WordPress-Zauberer sind. Außerdem macht es oft Spaß.

In den letzten zehn Jahren habe ich WordPress als Plattform für den API-Verbrauch gegen wahrscheinlich 50 verschiedene APIs verwendet. Einige der gängigsten APIs waren MailChimp, Google Analytics, Google Maps, CloudFlare und Bitbucket. Aber was ist, wenn Sie mehr tun müssen, was, wenn Sie eine kundenspezifische Lösung benötigen?

So entwickeln Sie einen WordPress-API-Client

In diesem Artikel werde ich gegen eine generische „E-Mail-Dienst“-API entwickeln und mein Bestes geben, um die Dinge so agnostisch wie möglich zu halten. Ich halte es jedoch für vernünftig anzunehmen, dass wir es mit einer JSON-REST-API zu tun haben. Hier sind einige Hintergrundthemen, die Ihnen helfen könnten, die technischen Punkte in diesem Artikel zu genießen:

• Die WordPress-HTTP-Funktionsfamilie
• JSON
• SICH AUSRUHEN

Wenn Sie sich mit diesen Themen nur geringfügig auskennen und daran interessiert sind, tiefer zu graben, machen Sie jetzt eine Pause und laden Sie die ausgezeichnete Postman-Anwendung herunter. Es ermöglicht Ihnen, mit APIs zu kommunizieren, ohne Code schreiben zu müssen.

Wenn Sie damit jedoch überhaupt nicht vertraut sind, lesen Sie trotzdem weiter. Ein technisches Publikum mit einem gewissen Maß an WordPress-Erfahrung wird das Beste aus diesem Artikel herausholen, aber ich werde darauf achten, den Wert jeder Technik auf weniger technische Weise zu erklären. Ein technisch nicht versierter Leser wird diesen Artikel in der Lage verlassen, den ROI jedes Punktes vor dem Sponsoring einzuschätzen und die Qualität der Implementierung nach der Lieferung zu beurteilen.

Hinweis: Falls du einen schnellen Auffrischungskurs benötigst, kannst du dir unseren WordPress-REST-API-Leitfaden ansehen.

Erlauben Sie mir, ohne weitere Präambel, eine Handvoll verschiedener Techniken mit Ihnen zu teilen, die ich bei fast allen APIs, Projekten und Teams, mit denen ich arbeite, schätze.

Transienten: Wann man sie hält, wann man sie faltet

In meinem einleitenden Absatz habe ich angemerkt, dass der Kunde es lästig fand, zwei Verwaltungsbereiche zu überspannen: wp-admin und das Dashboard für seinen E-Mail-Dienst. Eine gute Möglichkeit, dies zu lösen, wäre, ihnen ein Dashboard-Widget in wp-admin zur Verfügung zu stellen, um eine Zusammenfassung ihrer letzten Abonnentenaktivitäten anzuzeigen.

Andererseits könnte dies mehrere HTTP-Anforderungen an die Remote-API (die vom E-Mail-Dienst bereitgestellte API) erfordern, was zu langen Seitenladevorgängen führt. Die Lösung für dieses Leistungsproblem besteht darin, API-Aufrufe als Transienten zu speichern. Dieser Codex-Artikel bietet eine großartige Erklärung, die Sie unbedingt lesen sollten, aber ich fasse sie folgendermaßen zusammen:

1. Rufen Sie die Daten von der Remote-API ab.
2. Speichern Sie es mit set_transient() mit einer Ablaufzeit Ihrer Wahl, basierend auf Ihrem eigenen Urteil über Leistung, Ratenbegrenzungen und den Spielraum für Fehler bei der Anzeige veralteter Daten in dieser speziellen Anwendung.
3. Fahren Sie in Ihrer Geschäftslogik fort – verarbeiten Sie die Daten, geben Sie einen Wert zurück, was auch immer der Fall sein mag.
4. Wenn Sie die Daten erneut benötigen, z. B. beim Laden der nächsten Seite, suchen Sie mit get_transient() im transienten Cache danach, bevor Sie zu dem Schluss kommen, dass Sie sie von der API abrufen müssen.

Ich halte dies für eine hilfreiche und tragfähige Grundlage, aber Sie können noch einen Schritt weiter gehen, wenn Sie einen Moment über REST-Verben nachdenken. Von den fünf gängigsten Methoden (GET, POST, PATCH, PUT, DELETE) gehört nur eine davon in Ihren transienten Cache. Können Sie erraten, welche? Es ist ERHALTEN. In meinen Plugins habe ich fast immer eine PHP-Klasse, die dem Abstrahieren von Aufrufen an die betreffende Remote-API gewidmet ist, und ein Argument beim Instanziieren dieser Klasse ist die HTTP-Methode. Wenn es sich nicht um einen GET-Aufruf handelt, werde ich überhaupt keine Caching-Schicht aufrufen.

Wenn es sich außerdem nicht um einen GET-Aufruf handelt, liegt es nahe, dass ich etwas unternehme, um die entfernten Daten auf irgendeine Weise zu ändern, vielleicht indem ich einen E-Mail-Abonnenten hinzufüge, bearbeite oder entferne. Dies könnte ein guter Zeitpunkt sein, um den vorhandenen Cache für diese Ressource über delete_transient() ungültig zu machen.

Um zu unserem Beispiel einer WordPress-API für E-Mail-Abonnements zurückzukehren, hier ist, wie dies in der Praxis funktionieren würde:

• Ein Dashboard-Widget zum Anzeigen der letzten Abonnenten ruft den API-Endpunkt für /subscribers über eine GET-Anfrage auf. Da es sich um eine GET-Anforderung handelt, wird sie in meinem vorübergehenden Cache gespeichert.
• Ein Seitenleisten-Widget zum Abonnieren der E-Mail-Liste ruft den API-Endpunkt für /subscribers über eine POST-Anforderung auf. Da es sich um eine POST-Anforderung handelt, vermeidet sie nicht nur meinen transienten Cache, sondern veranlasst mich auch, den relevanten Teil meines transienten Cache zu löschen, damit das Dashboard-Widget diesen neuen Abonnenten widerspiegelt.
• Wenn ich Transienten benenne, organisiere ich sie oft, indem ich sie buchstäblich nach der Remote-API-URL benenne, die ich aufrufe. Dies ist eine praktische Methode, um den korrekten zu löschenden Transienten zu identifizieren. Wenn es sich um einen Endpunkt handelt, der Argumente akzeptiert, verkette ich diese zu einer Zeichenfolge und füge sie auch dem transienten Namen hinzu.

Als Kunde oder anderer weniger technischer Beteiligter sollten Sie jedes Mal, wenn die Anwendung Daten von einem Remotedienst abruft, ausdrücklich transientes Caching anfordern – oder zumindest eine Diskussion darüber. Sie sollten sich mit dem ausgezeichneten Query Monitor-Plugin vertraut machen, um einen Überblick über die Funktionsweise von Transienten zu erhalten. Es bietet Ihnen eine Schnittstelle zum Durchsuchen, welche Daten als Transient gespeichert werden, wie häufig und für wie lange.

Manchmal sind Transienten nicht gut genug

Einige Premium-WordPress-Hosting-Dienste erlauben es Ihnen tatsächlich nicht, Transienten in der Produktion zu verwenden. Auf ihnen läuft Code, vielleicht in Form eines MU-Plugins oder eines anderen Skripts, das Ihren Versuch, die Transients-API zu verwenden, abfängt und diese Informationen stattdessen über den Objektcache speichert. Die WP-Engine in ihrer gängigsten Konfiguration ist dafür ein Paradebeispiel.

Wenn Sie lediglich Daten speichern und abrufen, müssen Sie sich darüber eigentlich keine Gedanken machen und bemerken es möglicherweise gar nicht. Die gesamte Familie der *_transient() Funktionen liefert Ihnen das gleiche Endergebnis, nur gefiltert, um den Objekt-Cache anstelle des transienten Caches zu verwenden. Wo Sie jedoch auf Probleme stoßen könnten, ist der Versuch, Transienten zu löschen. Hier ist der Grund.

Wenn Ihre API-Integration komplex genug ist, um eine eigene Einstellungsseite zu verdienen, möchten Sie vielleicht eine Benutzeroberfläche einbinden, die es dem Admin-Benutzer ermöglicht , den gesamten vorübergehenden Cache für Ihr Plugin zu löschen . Die häufigste Verwendung für diese Schaltfläche wäre, wenn der Client einige Daten direkt auf dem Remotedienst ändert und den Cache ungültig machen möchte, den wir in WordPress speichern. Diese Schaltfläche kann auch nützlich sein, wenn der Client Kontoanmeldeinformationen oder API-Schlüssel ändert, oder einfach allgemein als Schaltfläche zum Zurücksetzen auf die Werkseinstellungen zum Debuggen.

Selbst wenn Sie schlau genug waren, alle Ihre transienten Schlüssel zu benennen, damit Sie eine gewisse Hoffnung haben, jeden von ihnen für delete_transient() zu identifizieren, beinhaltet das beste Szenario wahrscheinlich immer noch rohes SQL, das ich in WordPress immer zu vermeiden versuche:

 <?php // Purge all the transients associated with our plugin. function purge() { global $wpdb; $prefix = esc_sql( $this -> get_transient_prefix() ); $options = $wpdb -> options; $t = esc_sql( "_transient_timeout_$prefix%" ); $sql = $wpdb -> prepare ( " SELECT option_name FROM $options WHERE option_name LIKE '%s' ", $t ); $transients = $wpdb -> get_col( $sql ); // For each transient... foreach( $transients as $transient ) { // Strip away the WordPress prefix in order to arrive at the transient key. $key = str_replace( '_transient_timeout_', '', $transient ); // Now that we have the key, use WordPress core to the delete the transient. delete_transient( $key ); } } ?>

Nicht bequem, nicht effizient. Stattdessen erfordert diese Situation das Zwischenspeichern von Objekten , da das Zwischenspeichern von Objekten uns eine bequeme Möglichkeit bietet, zwischengespeicherte Werte zu gruppieren . Auf diese Weise ist es ein einfacher Einzeiler-Aufruf von wp_cache_delete( $key, $group ) , wenn Sie alle zwischengespeicherten Werte in Bezug auf Ihr Plugin leeren müssen.

Ich würde das alles zusammenfassen, indem ich sage: Sie können kein Experte für die Verwendung von APIs sein, wenn Sie noch kein Experte für die Verwaltung des Caches für diese Daten sind.

Als Kunde sollten Sie vor allem auf abweichendes Cache-Verhalten zwischen Staging- und Produktionsumgebungen achten. Mit anderen Worten, obwohl das Testen eines neuen Arbeitsstapels im Staging immer eine gute Praxis ist, muss das Caching auch in der Produktion mit der gleichen Sorgfalt getestet werden.

Die Remote-API kann helfen, Ihre PHP-Klassenhierarchie zu informieren

Bei der Gestaltung der verschiedenen PHP-Klassen für mein Plugin finde ich es oft hilfreich, die Definition der API-Endpunkte nachzuahmen – was scheinen zum Beispiel die folgenden Endpunkte gemeinsam zu haben?

• https://api.example-email-service.com/v1/subscribers.json
• https://api.example-email-service.com/v1/lists.json
• https://api.example-email-service.com/v1/campaigns.json

Sie alle geben collections zurück, womit ich das Ergebnis einer GET-Anforderung meine, die Null-zu-viele-Ergebnisse zurückgeben, wobei jedes Ergebnis ein Mitglied eines Arrays ist. Das mag ziemlich offensichtlich klingen, aber ich finde es eine hilfreiche Eingabeaufforderung für die folgende Klassenstruktur in meinem PHP-Code:

• class.collection.php , eine abstrakte Klasse
• class.subscribers.php erweitert die abstrakte Klasse Collection .
• class.lists.php erweitert die abstrakte Klasse Collection .
• class.campaigns.php erweitert die abstrakte Klasse Collection .

Die abstrakte Klasse würde als einziges Argument ein Array von Abfrageparametern annehmen: Dinge wie Paginierung, Sortierspalte, Sortierreihenfolge und Suchfilter. Es hätte Methoden für allgemeine Aufgaben wie das Aufrufen der Remote-API, das Behandeln von Fehlern und vielleicht das Morphen der Ergebnisse in ein HTML- <select> -Menü oder einen jQueryUI-AutoSuggest. Die Klassen, die die abstrakte Klasse instanziieren, sind möglicherweise recht kurz und tun möglicherweise kaum mehr als die Angabe der Zeichenfolge, die in der *.json API-Endpunkt-URL verwendet werden soll.

Was haben die folgenden Endpunkte gemeinsam?

• https://api.example-email-service.com/v1/subscribers/104abyh4.json
• https://api.example-email-service.com/v1/lists/837dy1h2.json
• https://api.example-email-service.com/v1/campaigns/9i8udr43.json

Sie alle geben ein Element zurück, womit ich genau ein bestimmtes, einzigartiges Mitglied einer Sammlung meine: Dinge wie einen bestimmten E-Mail-Abonnenten, eine E-Mail-Liste oder eine E-Mail-Kampagne. Daher verwende ich in meinem PHP-Code gerne folgende Struktur:

• class.item.php , eine abstrakte Klasse
• class.subscriber.php erweitert die abstrakte Klasse Item .
• class.list.php erweitert die abstrakte Klasse Item .
• class.campaign.php erweitert die abstrakte Klasse Item .

Die abstrakte Klasse würde als einziges Argument eine Zeichenfolge nehmen, um das spezifische angeforderte Element zu identifizieren. Auch hier können die zu instanziierenden Klassen ziemlich kurz sein und möglicherweise kaum mehr tun, als die zu verwendende Zeichenfolge in */duy736td.json .

Es gibt viele Ansätze zur Strukturierung der Klassenvererbung, aber selbst wenn Sie einen anderen Ansatz als den oben skizzierten wählen, besteht eine gute Chance, dass die Struktur der Remote-API dazu beitragen kann, die Struktur Ihrer Anwendung zu informieren.

Als Kunde ist es ein häufiges Symptom einer schlechten Architektur, wenn Sie immer wieder die gleiche Änderung für eine Anwendung anfordern müssen. Wenn Sie beispielsweise anfordern, dass Berichte 100 Ergebnisse pro Seite statt 10 zurückgeben, und Sie diese Anforderung für Abonnentenberichte, Kampagnenberichte, Abmeldeberichte usw. immer wieder wiederholen müssen, stellen Sie möglicherweise eine schlechte Klassenarchitektur fest. In dieser Situation lohnt es sich, Ihr Team zu fragen, ob es von einem Refactoring-Zyklus profitieren würde: Ein Arbeitspaket, bei dem das Ziel nicht darin besteht, das Verhalten des Produkts zu ändern, sondern den zugrunde liegenden Code zu verbessern, sodass es einfacher wird, das Verhalten zu ändern des Produkts in der Zukunft.

Der perfekte Anwendungsfall für WP_Error

Es ist mir peinlich zuzugeben, dass ich Jahre länger gebraucht habe, als es hätte sein müssen, um die WP_Error Funktionsfamilie in meinem Code richtig zu verwenden. Ich tendierte dazu, mich einfach durchzucodieren, entweder in der Annahme, dass es niemals Fehler geben würde, um die es sich zu kümmern lohnte, oder sie von Fall zu Fall behandelte. Die Arbeit mit Remote-APIs durchschneidet diese Mentalität wie ein Laserstrahl, da sie einen äußerst bequemen und leistungsstarken Anwendungsfall für die Verwendung von WP_Error .

Denken Sie daran, dass ich bereits erwähnt habe, dass ich oft eine PHP-Klasse habe, deren Zweck es ist, HTTP-Anforderungen an die Remote-API zu stellen. Wenn Sie alle Boilerplates, alle Datenmanipulationen und alle sekundären Bedenken zurückziehen, läuft diese Klasse wirklich darauf hinaus, wp_remote_request() , um ein HTTP-Antwortobjekt von der API zu erhalten. Praktischerweise gibt wp_remote_request() stattdessen einen WP_Error wenn der Aufruf aus irgendeinem Grund nicht ausgeführt werden kann, aber was ist, wenn der Aufruf erfolgreich eine HTTP-Antwort eines ungünstigen Typs zurückgibt?

Als Beispiel haben wir vielleicht den Endpunkt /lists.json , aber für dieses spezielle Konto sind noch keine Listen eingerichtet. Dies würde eine gültige HTTP-Antwort zurückgeben, jedoch mit einem Statuscode von 400. Das ist zwar per se kein schwerwiegender Fehler, aber aus der Perspektive eines Frontend-Codes, der diesen API-Aufruf in ein Dropdown-Menü umwandeln möchte, könnte ein 400 auch ein WSOD sein! Daher finde ich es hilfreich, das Ergebnis von wp_remote_request() zusätzlich zu parsen und möglicherweise doch einen WP_Error zurückzugeben:

 <?php function call() { $response = wp_remote_request( $this -> url, $this -> args ); $code = wp_remote_retrieve_response_code( $response ); $first_digit = $code[0]; $good_responses = array( 2, 3 ); if( ! in_array( $first_digit, $good_responses ) { $body = wp_remote_retrieve_body( $response ); $out = new WP_Error( $code, $body ); } else { $out = $response; } return $out; } ?>

Dieses Muster kann dabei helfen, den Code zu vereinfachen, der unsere Aufruferklasse aufruft, weil wir wissen, dass wir uns sicher auf is_wp_error() verlassen können, bevor wir mit unserer Ausgabe fortfahren.

Als Kunde sollten Sie gelegentlich die Rolle eines böswilligen Benutzers, eines verwirrten Benutzers und eines ungeduldigen Benutzers spielen. Verwenden Sie die App auf eine Weise, für die sie nicht vorgesehen ist. Tun Sie die Dinge, die Ihre Entwickler anscheinend nicht von Ihnen wollen. Beachten Sie, was passiert. Erhalten Sie hilfreiche Fehlermeldungen? Bekommst du überhaupt Fehlermeldungen? Wenn nicht, kann es sich lohnen, eine Reihe von Arbeiten zur besseren Fehlerbehandlung zu sponsern.

Die schöne Debugging-Power von ob_get_clean()

Das moderne programmierbare Web, in dem fast jede Website die APIs anderer Websites verwendet und selbst über ihre eigene API verwendet wird, ist zu einer unglaublich mächtigen Arena für Code geworden. Aber genau diese Eigenschaft kann ihn auch recht langsam machen.

Es ist üblich, dass Remote-HTTP-Anforderungen die zeitaufwändigsten Teile des Ladens einer bestimmten Seite sind. Aus diesem Grund werden viele API-gesteuerte Komponenten entweder über Ajax oder Cron ausgeführt. Beispielsweise sollte ein Autosuggest zum Durchsuchen einer Liste von E-Mail-Abonnenten wahrscheinlich die Remote-Datenquelle bei Bedarf bei jedem Tastendruck anpingen, anstatt alle 100.000 Abonnenten im DOM zu laden, wenn die Seite geladen wird. Wenn dies keine Option ist, könnte vielleicht eine große Abfrage bei einer nächtlichen Crontask synchronisiert werden, sodass die Ergebnisse von einem lokalen Spiegel und nicht von der Remote-API abgerufen werden können.

Das Problem bei diesem Ansatz ist, dass das Debuggen schwierig sein kann. Anstatt einfach WP_DEBUG und die Fehlermeldungen in Ihr Browserfenster rollen zu lassen, stecken Sie in der Browser-Netzwerkkonsole fest oder verfolgen eine Protokolldatei, während eine Cron-Task (hoffentlich?) ausgeführt wird. Ich finde das unangenehm.

Eine Möglichkeit, diese Situation zu verbessern, sind vorsichtige und strategische Aufrufe von error_log() . Andererseits besteht ein häufiges Problem bei der Protokollierung darin, dass Fehlerprotokolle bei großen oder ausgelasteten Anwendungen zu groß oder zu schnell werden können, um für die Überwachung oder Analyse nützlich zu sein. Daher müssen wir mit dem, was wir protokollieren, wählerisch sein und uns genauso viel Gedanken darüber machen, wie wir es mit unserer eigentlichen Anwendungslogik tun . Es ist schade, dass Sie sich die Zeit genommen haben, einen exotischen Grenzfallfehler zu protokollieren, der nur gelegentlich bei einer seltenen Cron-Aufgabe aufzutreten scheint, nur um festzustellen, dass Ihnen die wahre Natur des Fehlers wieder einmal entgangen ist, weil Sie es versäumt haben, ein bestimmtes Array-Mitglied zu protokollieren , sagen wir, des beleidigenden Wertes.

Daher ist meine Philosophie geworden, ich logge nicht immer, aber wenn ich es tue, logge ich alles . Mit anderen Worten, nachdem ich eine besonders besorgniserregende Funktion identifiziert habe, werde ich sie mit einem möglichst breiten Netz protokollieren:

 <?php function debug( $bug ) { ob_start(); var_dump( $bug ); $out = ob_get_clean(); error_log( $out ); } ?>

Dies läuft darauf hinaus, var_dump() den gesamten fehlerhaften Wert in einen einzigen Eintrag in der Fehlerprotokolldatei schreibt.

Als Kunde lohnt es sich, regelmäßig die Gesamtauslastung des Dateispeichers für Ihre Anwendung zu überprüfen. Wenn Sie bemerken, dass Sie plötzlich an die Speichergrenzen Ihres Hosting-Kontos stoßen, besteht eine gute Chance, dass ein wild gewordenes Fehlerprotokoll schuld ist. Ihre Entwickler werden von einem Arbeitszyklus profitieren, der sich auf eine bessere Protokollierung konzentriert – und Ihre Kunden auch!

Nicht gerade Clickbait, aber es reicht

Bitte verzeihen Sie die Listicle-Struktur dieses Artikels. Ich konnte diese Punkte nicht in ein einheitlicheres Artikelthema zwingen, da diese Muster sehr generisch sind: Sie gelten für jeden JSON-REST-Endpunkt und jede WordPress-Ausgabe .

Es sind die Muster, die ich immer wieder sehe, unabhängig davon, was die Remote-API ist oder wofür wir sie in WordPress verwenden. Ich bin so weit gegangen, all diese Prinzipien in einem Plugin-Boilerplate zu sammeln, das meine Arbeit enorm beschleunigt. Haben Sie ähnliche Punkte, die Sie für jedes Projekt behalten? Bitte teilen Sie sie, damit ich sie stehlen und zu meiner Boilerplate hinzufügen kann!