RoWaWorld

Eine ältere Version des Dokuments wurde geladen! Beim Speichern wird eine neue Version des Dokuments mit diesem Inhalt erstellt.

<WRAP rww-back>
[[werkzeuge:start|←]] [[werkzeuge:start|Werkzeuge]]
</WRAP>

</WRAP>

===== Was ist WP-CLI? =====
WP-CLI ist eine Möglichkeit, WordPress über die Kommandozeile zu bedienen.

Statt eine Aufgabe im WordPress-Backend mit Maus und Menüs auszuführen, gebe ich einen Befehl im Terminal ein. WP-CLI führt diesen Befehl anschließend direkt in meiner WordPress-Installation aus.

Der Name steht für **WordPress Command Line Interface** – also eine Kommandozeilenschnittstelle für WordPress.

Für mich ist WP-CLI noch Neuland. Bis vor Kurzem hatte ich davon noch nie gehört. Diese Seite dokumentiert deshalb nicht nur Befehle, sondern auch meinen praktischen Einstieg und die Dinge, die ich dabei lerne.
===== Warum beschäftige ich mich damit? =====
Auf WP-CLI bin ich im Zusammenhang mit meinen WordPress-Projekten gestoßen.

Anfangs wirkte die Arbeit über die Kommandozeile eher ungewohnt. Inzwischen sehe ich darin aber ein Werkzeug, mit dem sich bestimmte Aufgaben schneller und kontrollierter erledigen lassen.

Besonders interessant ist WP-CLI für mich, wenn Arbeiten wiederholt werden müssen oder Änderungen direkt an einer lokalen WordPress-Installation durchgeführt werden sollen.

Mein Ziel ist nicht, möglichst viele WP-CLI-Befehle auswendig zu lernen. Ich möchte verstehen, welche Befehle mir bei meiner praktischen Arbeit wirklich helfen – und genau diese hier dokumentieren.
===== Wie funktioniert WP-CLI grundsätzlich? =====
WP-CLI arbeitet über die Kommandozeile. Ich öffne ein Terminal, wechsle in das Verzeichnis meiner WordPress-Installation und gebe dort einen WP-CLI-Befehl ein.

Das Grundprinzip ist:

Terminal → WordPress-Verzeichnis → WP-CLI-Befehl → Ergebnis

Ein einfacher Befehl sieht zum Beispiel so aus:

<code>
wp core version
</code>

WP-CLI erkennt anhand der WordPress-Installation, mit welcher Website gearbeitet wird, führt den Befehl aus und zeigt das Ergebnis direkt im Terminal an.

Wichtig für mich: Ein WP-CLI-Befehl ist keine „Zauberei“. Er erledigt lediglich eine bestimmte Aufgabe in WordPress, die ich sonst teilweise über das Backend oder auf anderem Weg durchführen würde.

{{:rww:infografiken:infografik_wp-cli_grundprinzip.png|Infografik – WP-CLI Grundprinzip}}

===== Meine Umgebung =====
WP-CLI verwende ich derzeit hauptsächlich in meiner lokalen WordPress-Entwicklungsumgebung unter Windows.

Meine Umgebung:

* **Betriebssystem:** Windows
  * **Lokaler Webserver:** XAMPP
  * **Webserver:** Apache
  * **PHP:** über XAMPP
  * **Datenbank:** MariaDB / MySQL
  * **WordPress:** lokale Entwicklungsinstallationen
  * **Terminal:** Windows-Kommandozeile bzw. Terminal
  * **WP-CLI:** lokal installiert und über die Kommandozeile aufrufbar

Für die Arbeit mit einer WordPress-Installation wechsle ich im Terminal zunächst in deren Stammverzeichnis.

Beispiel:

<code>
cd E:\\xampp\\htdocs\\thecruiserblog
</code>

Anschließend kann ich dort die WP-CLI-Befehle für diese WordPress-Installation ausführen.
===== Installation und Einrichtung =====
==== Meine Installation unter Windows ====

Meine funktionierende WP-CLI-Installation liegt in einem eigenen Ordner innerhalb meiner XAMPP-Installation:

<code>
E:\xampp\wp-cli\
</code>

Dort befinden sich die beiden Dateien:

Installierte WP-CLI-Version:

==== Ordnerstruktur ====

Für WP-CLI habe ich innerhalb von XAMPP einen eigenen Ordner angelegt:

<code>
E:\xampp\wp-cli\
</code>

Die Struktur sieht so aus:

<code>
E:\xampp\wp-cli\
├── wp-cli.phar
└── wp.bat
</code>

Die Datei ''wp-cli.phar'' enthält WP-CLI selbst.

Die Datei ''wp.bat'' dient unter Windows als Starter. Dadurch kann ich WP-CLI später einfach mit dem Befehl ''wp'' aufrufen.

==== Die Datei wp.bat ====

Die Datei ''wp.bat'' stellt unter Windows den kurzen Befehl ''wp'' bereit.

Ihr Inhalt lautet:

<code>
@echo off
"E:\xampp\php\php.exe" "E:\xampp\wp-cli\wp-cli.phar" %*
</code>

Dabei passiert Folgendes:

* ''@echo off'' verhindert, dass der eigentliche Batch-Befehl zusätzlich im Terminal ausgegeben wird.
  * ''E:\xampp\php\php.exe'' startet PHP aus meiner XAMPP-Installation.
  * ''E:\xampp\wp-cli\wp-cli.phar'' startet WP-CLI.
  * ''%*'' übergibt alle Angaben, die ich hinter ''wp'' eingebe, an WP-CLI.

Wenn ich zum Beispiel eingebe:

<code>
wp core version
</code>

wird intern sinngemäß ausgeführt:

<code>
"E:\xampp\php\php.exe" "E:\xampp\wp-cli\wp-cli.phar" core version
</code>

==== PATH-Einträge ====

Damit ich WP-CLI im Terminal einfach mit ''wp'' aufrufen kann, sind die benötigten Verzeichnisse in der Windows-Umgebungsvariable ''PATH'' eingetragen.

Für meine XAMPP- und WP-CLI-Umgebung sind insbesondere diese Einträge wichtig:

<code>
E:\xampp\php
E:\xampp\mysql\bin
E:\xampp\wp-cli
</code>

Dadurch kann Windows die jeweiligen Programme finden, ohne dass ich jedes Mal den vollständigen Pfad eingeben muss.

Für WP-CLI bedeutet das konkret:

<code>
E:\xampp\wp-cli
</code>

Da sich dort die Datei ''wp.bat'' befindet, genügt im Terminal der kurze Aufruf:

==== Funktionstest ====

Nach der Einrichtung kann ich im Terminal prüfen, ob WP-CLI korrekt gefunden und ausgeführt wird.

Zuerst prüfe ich, wo Windows den Befehl ''wp'' findet:

<code>
where wp
</code>

In meiner Installation lautet die Ausgabe:

<code>
E:\xampp\wp-cli\wp.bat
</code>

Anschließend prüfe ich die installierte WP-CLI-Version:

<code>
wp cli version
</code>

Aktuelle Ausgabe:

Damit ist bestätigt, dass Windows die Datei ''wp.bat'' findet und WP-CLI über PHP erfolgreich ausgeführt werden kann.

==== Praxis-Hinweis ====

WP-CLI kann zwar grundsätzlich von überall im Terminal aufgerufen werden, viele WordPress-bezogene Befehle müssen jedoch im Stammverzeichnis der jeweiligen WordPress-Installation ausgeführt werden.

Beispiel:

<code>
cd E:\xampp\htdocs\thecruiserblog
</code>

Erst dort weiß WP-CLI eindeutig, mit welcher WordPress-Installation gearbeitet werden soll.

----
WP-CLI muss auf dem Rechner installiert und so eingerichtet sein, dass der Befehl ''wp'' im Terminal aufgerufen werden kann.

In diesem Abschnitt dokumentiere ich meine eigene Installation unter Windows – einschließlich der notwendigen Pfade und Einstellungen.

Wichtig ist mir dabei nicht nur, **was** eingerichtet werden muss, sondern auch **warum**. So kann ich die Einrichtung später nachvollziehen oder auf einem anderen Rechner wiederholen.
===== Meine ersten Befehle =====
==== Wie ist ein WP-CLI-Befehl aufgebaut? ====

Ein WP-CLI-Befehl beginnt grundsätzlich mit:

Danach folgt der Bereich, mit dem ich arbeiten möchte, und anschließend die gewünschte Aktion.

Beispiel:

<code>
wp core version
</code>

Dabei bedeutet:

* ''wp'' → WP-CLI aufrufen
  * ''core'' → mit dem WordPress-Core arbeiten
  * ''version'' → die installierte Version anzeigen

Vereinfacht kann ich mir den Aufbau so merken:

<code>
wp [Bereich] [Aktion]
</code>

Je nach Befehl können anschließend weitere Angaben und Optionen folgen.

==== WordPress-Version anzeigen ====

Mein erster einfacher Informationsbefehl:

<code>
wp core version
</code>

Der Befehl zeigt die Version der WordPress-Installation an, in deren Verzeichnis ich mich gerade befinde.

Er verändert nichts an der Installation und eignet sich deshalb gut, um den grundsätzlichen Ablauf mit WP-CLI auszuprobieren.

==== WP-CLI-Version anzeigen ====

Mit diesem Befehl kann ich prüfen, welche Version von WP-CLI installiert ist:

<code>
wp cli version
</code>

Der Befehl zeigt die installierte WP-CLI-Version an.

Er verändert nichts an WordPress und eignet sich gut, um zu prüfen, ob WP-CLI grundsätzlich aufgerufen werden kann.

==== Website-Adresse anzeigen ====

Mit diesem Befehl kann ich die in WordPress hinterlegte Website-Adresse anzeigen:

<code>
wp option get siteurl
</code>

WP-CLI liest dabei den Wert der WordPress-Option ''siteurl'' aus.

Der Befehl verändert nichts an der Installation. Er ist für mich besonders praktisch, um schnell zu kontrollieren, mit welcher WordPress-Installation ich gerade arbeite.

----

Meine ersten WP-CLI-Befehle sollen vor allem dabei helfen, mich mit der Arbeitsweise vertraut zu machen.

Ich beginne deshalb mit einfachen Befehlen, die Informationen anzeigen und möglichst noch nichts an der WordPress-Installation verändern.

So kann ich ausprobieren, wie WP-CLI reagiert, wie die Ausgabe im Terminal aussieht und wie ein Befehl grundsätzlich aufgebaut ist.
===== Befehle, die ich tatsächlich nutze =====
==== search-replace ====

Mit ''wp search-replace'' kann ich Zeichenfolgen direkt in der WordPress-Datenbank suchen und ersetzen.

Typischer Anwendungsfall bei einer lokalen Kopie einer WordPress-Seite:

<code>
wp search-replace "ALTE-ADRESSE" "NEUE-ADRESSE" --dry-run
</code>

Mit ''--dry-run'' wird zunächst nur geprüft, welche Änderungen durchgeführt würden. Die Datenbank wird dabei noch nicht verändert.

Das ist für mich der wichtigste erste Schritt, bevor ich einen echten Such- und Ersetzlauf ausführe.

=== Testlauf ===

Vor einer tatsächlichen Änderung prüfe ich den Befehl zunächst mit ''--dry-run'':

<code>
wp search-replace "ALTE-ADRESSE" "NEUE-ADRESSE" --dry-run
</code>

Dabei zeigt WP-CLI an, welche Ersetzungen vorgenommen würden, ohne die Datenbank zu verändern.

=== Tatsächliche Ersetzung ===
=== Mein Anwendungsfall ===

Ich habe ''wp search-replace'' beim Aufbau meiner lokalen WordPress-Entwicklungsumgebung verwendet.

Nach dem Import einer bestehenden WordPress-Installation enthielt die Datenbank noch Verweise auf die bisherige Website-Adresse.

Mit ''search-replace'' konnte ich diese Verweise auf die Adresse meiner lokalen Installation umstellen.

Dabei ist ''--dry-run'' besonders wichtig: Zuerst kontrolliere ich, welche Einträge betroffen wären. Erst danach führe ich die tatsächliche Ersetzung aus.

Erst wenn der Testlauf plausibel aussieht, entferne ich ''--dry-run'':

<code>
wp search-replace "ALTE-ADRESSE" "NEUE-ADRESSE"
</code>

Dann werden die gefundenen Werte tatsächlich in der Datenbank ersetzt.
----
Dieser Bereich wächst mit meiner praktischen Arbeit.

Hier sammle ich nur WP-CLI-Befehle, die ich selbst verwendet habe und deren Zweck ich nachvollziehen kann.

Zu jedem Befehl möchte ich möglichst festhalten:

* den Befehl
  * was er bewirkt
  * wann ich ihn einsetze
  * ein praktisches Beispiel
  * wichtige Hinweise oder Risiken

So entsteht nach und nach meine persönliche WP-CLI-Kurzreferenz – statt einer langen Liste von Befehlen, die ich vielleicht nie brauche.
===== Probleme & Lösungen =====
==== Deprecated-Hinweise beim Aufruf von WP-CLI ====

=== Was ist passiert? ===

Beim Aufruf eines WP-CLI-Befehls wurden vor der eigentlichen Ausgabe mehrere Hinweise angezeigt:

<code>
Deprecated: Using ${var} in strings is deprecated, use {$var} instead
</code>

Die Meldungen verweisen auf Dateien im Bereich:

<code>
wp-content\uploads\visualcomposer-assets\addons\themeEditor\
</code>

Der eigentliche WP-CLI-Befehl wurde anschließend trotzdem ausgeführt.
----
WP-CLI funktioniert nicht immer auf Anhieb. Gerade bei der Einrichtung oder bei Befehlen, die auf weitere Programme zugreifen, können Probleme auftreten.

Hier dokumentiere ich Fehler und Stolpersteine, die mir selbst begegnet sind.

Für jeden Fall möchte ich möglichst festhalten:

* Was wollte ich machen?
  * Was ist passiert?
  * Welche Fehlermeldung wurde angezeigt?
  * Was war die Ursache?
  * Wie habe ich das Problem gelöst?

So entsteht mit der Zeit eine persönliche Fehlersammlung, in der ich bei einem ähnlichen Problem schnell nachschauen kann.

Zusammenfassung