Setting Up Your Local Environment/de: Difference between revisions

Latest revision as of 05:39, 28 May 2024

Tutorial - Wie eine lokale Entwicklungsumgebung für Joomla! 4 eingerichtet wird

Joomla!

4.x

Mit Joomla! 4 wurde der Entwicklungsprozess verändert. Es ist nicht länger möglich, das Repository zu klonen und so Joomla! zu installieren. Im Folgenden ist nach aktuellen Erfahrungswerten ein funktionaler Weg zur Installation beschrieben.

Schnellstart-Anweisungen

Abhängig vom Betriebssystem unterscheidet sich die Einrichtung der Entwicklungsumgebung. Es ist leider nicht möglich, den Vorgang für die verschiedenen Betriebssysteme zu dokumentieren. Die bevorzugte Suchmaschine wird hier weiterhelfen.

Benötigte Werkzeuge

PHP - im Wesentlichen dasselbe wie beim Betreiben einer Joomla!-Seite, allerdings brauchst du eine spezielle Version, die PHP CLI (Kommandozeileneingabe) (beachte auch die Seite Einrichten eines LAMPP-Servers für die PHP-Entwicklung)
Composer - um die Abhängigkeiten von Joomla!s PHP zu verwalten. Hilfe bei der Installation von Composer bietet die Dokumentation auf https://getcomposer.org/doc/00-intro.md
Node.js - um JavaScript- und SASS-Dateien für Joomla! zu kompilieren - Hilfe bei der Installation von Node.js bieten die Anweisungen, die auf https://nodejs.org/en/ erhältlich sind. Hinweis: Für die Installation von Joomla wird mindestens NodeJS 12 benötigt.
Git - für die Versionsverwaltung.

Schritt für Schritt zur Installation der lokalen Entwicklungsumgebung

Das Repository klonen
Zum Branch der aktuellen Version wechseln (derzeit 4.3-dev)
Die Installation von composer install im Stammverzeichnis des Git-Repositorys ausführen. (Man kann --ignore-platform-reqs hinzufügen, wenn man das PHP-LDAP nicht lokal installiert hat und es nicht benötigt.)
Im Stammverzeichnis des Git-Repositorys npm ci ausführen. (Bitte beachten, dass dafür npm 6.13.4 oder höher benötigt wird. Um die npm-Version auf die LTS-Version zu aktualisieren, sollte npm install -g npm@lts ausgeführt werden. Für Joomla 5 wird npm 10.1.0 oder höher benötigt. Tipp: Mit nvm (Node Version Manager) kann man leicht zu anderen npm-Versionen wechseln).

Linux und OSX Benutzer können den folgenden Bash-Alias nutzen und ihn in der ~/.bashrc-Datei setzen:

alias jclean="rm -rf administrator/templates/atum/css; \
rm -rf templates/cassiopeia/css; \
rm -rf administrator/templates/system/css; \
rm -rf templates/system/css; \
rm -rf media/; \
rm -rf node_modules/; \
rm -rf libraries/vendor/; \
rm -f administrator/cache/autoload_psr4.php; \
rm -rf installation/template/css"
alias jinstall="jclean; composer install; npm ci"

Das wird alle kompilierten Dateien im System löschen und eine neue Installation über den Befehl jinstall innerhalb der Joomla-Installation starten. Man kann auch den Befehl jclean verwenden, um zu einem Joomla 3.x Branch zurückzuwechseln

Die etwas längere Startanleitung

Joomla ähnelt vielen anderen Web-Tools dieser Tage. Es hat einen großen PHP-Anteil und es hat mehr und mehr JavaScript-Code. Während die PHP-Codierung nicht so viel Vorbereitung benötigt, muss man bei JavaScript eine Menge Tools verwenden. Der Hauptgrund ist, dass niemand Code so schreibt, dass ihn jeder Browser versteht, also muss der Code z.B. von ES6 in eine kompatible Version von JavaScript umgesetzt werden. Das Gleiche gilt für CSS. Für Joomla verwenden wir SASS und das wird in natives CSS umgewandelt, sodass jeder Browser es versteht. Auf der anderen Seite ist das Einrichten einer Entwicklungsumgebung etwas komplizierter, aber das Instrumentarium macht das Programmieren bequemer. Dank der Wächter und dem automatischen Reload des Browsers, können Änderungen in Echtzeit verfolgt werden.

PHP

Es sollte reichen, composer install auszuführen. Dies wird die PHP-Abhängigkeiten, die in der Datei composer.lock gespeichert sind, installieren. Man kann dies beliebig oft wiederholen, es werden nur neue Pakete installiert, wenn die composer.lock Datei verändert wird. Bitte composer update nicht ausführen, da dadurch alle Pakete auf neuere Versionen und die composer.lock Datei aktualisiert werden.

Hinweis: Möglicherweise muss composer install mit der Option --ignore-platform-reqs ausgeführt werden, um die in Composer angegebenen Plattformanforderungen zu ignorieren. Das gilt, falls die PHP-LDAP-Erweiterung nicht installiert ist.

Node/npm Skripte

Node.js wird mit dem Paketmanager „NPM“ ausgeliefert (gewissermaßen vergleichbar zu Composer). NPM hat einen run-Befehl und wir haben einige Skripte vorbereitet, um die Arbeit zu erleichtern. Die Befehle müssen im Stammverzeichnis des Repositorys ausgeführt werden, sobald JS- oder SASS-Dateien geändert wurden. Zuvor muss man einmalig npm ci ausführen, um die Abhängigkeiten zu installieren.

npm run build:css

Kompiliert SASS Dateien nach CSS und erzeugt die komprimierten Dateien.

npm run build:js

Es kompiliert und übersetzt die JavaScript-Dateien in das richtige Format und erstellt sogenannte Minified-Dateien.

npm run watch

Dieser Befehl entspricht dem Befehl build:js, erkennt jedoch Änderungen und erstellt automatisch aktualisierte Dateien im Medienverzeichnis. SASS-Dateien sind noch nicht enthalten.

npm run lint:js

Damit wird eine Syntaxprüfung aller ES6-JavaScript-Dateien gegen den JavaScript-Codestandard durchgeführt (für weitere Informationen zum Joomla 4-Codestandard, bitte das Codestandard-Handbuch lesen).

npm run test

Dies wird eine JavaScript Testsuite ausführen.

Mögliche Probleme

Beim Installieren des Composers kann es zu folgenden Fehlern kommen:

Problem 1
    - Installation request for joomla/ldap 2.0.0-beta -> satisfiable by joomla/ldap[2.0.0-beta].
    - joomla/ldap 2.0.0-beta requires ext-ldap * -> the requested PHP extension ldap is missing from your system.
Problem 2
    - Installation request for symfony/ldap v5.1.5 -> satisfiable by symfony/ldap[v5.1.5].
    - symfony/ldap v5.1.5 requires ext-ldap * -> the requested PHP extension ldap is missing from your system.

Die Lösung ist, die Composer-Installation mit der Option --ignore-platform-reqs auszuführen, um die in Composer angegebenen Plattformanforderungen zu ignorieren. Das heißt, wenn die LDAP-Erweiterung von PHP nicht installiert ist.

composer install --ignore-platform-reqs

Wenn ein Anmeldefehler, wie unten abgebildet, angezeigt wird, sollte die Datei administrator/cache/autoload_psr4.php, wie im zweiten Bild gezeigt, gelöscht werden.

@@ Line 1: / Line 1: @@
 <noinclude><languages /></noinclude>
-{{Top portal heading|color=white-bkgd|icon=magic|icon-color=#5091cd|size=3x|text-color=#333|title=Tutorial<br />
+{{Top portal heading|color=white-bkgd|icon=magic|icon-color=#5091cd|size=3x|text-color=#333|title=Tutorial - Wie eine lokale Entwicklungsumgebung für Joomla! 4 eingerichtet wird}}
-Handbuch für die Einrichtung von Joomla! 4 an die eigene Umgebung}}
 <noinclude>{{Joomla version|version=4.x}}</noinclude>
 {{-}}
-Mit Joomla! 4 haben wir den Entwicklungsprozess verändert, es ist nicht länger möglich, die Paketquellen zu klonen und damit eine verwendbare Joomla! Installation zu erhalten. Wir richten uns hier an die besten Erfahrungen und haben einen Bauvorgang für das CMS eingefügt.
+Mit Joomla! 4 wurde der Entwicklungsprozess verändert. Es ist nicht länger möglich, das Repository zu klonen und so Joomla! zu installieren. Im Folgenden ist nach aktuellen Erfahrungswerten ein funktionaler Weg zur Installation beschrieben.
-==Schnellstartanweisungen==
+==Schnellstart-Anweisungen==
-Es hängt von deinem Betriebssystem ab, was du alles tun musst, die Entwicklungsumgebung zu installieren. Wir können leider keine Dokumentation für alle Betriebssystem schreiben, daher solltest du deine bevorzugte Suchmaschine nach einer Anleitung fragen.
+Abhängig vom Betriebssystem unterscheidet sich die Einrichtung der Entwicklungsumgebung. Es ist leider nicht möglich, den Vorgang für die verschiedenen Betriebssysteme zu dokumentieren. Die bevorzugte Suchmaschine wird hier weiterhelfen.
-=== Tools you need ===
+=== Benötigte Werkzeuge===
-# PHP - basically the same as you need for running a Joomla Site, but you need the PHP CLI (command line interface) Version (see the [[S:MyLanguage/Configuring_a_LAMPP_server_for_PHP_development|Configuring a LAMPP server for PHP development]] page)
+# PHP - im Wesentlichen dasselbe wie beim Betreiben einer Joomla!-Seite, allerdings brauchst du eine spezielle Version, die PHP CLI (Kommandozeileneingabe) (beachte auch die Seite [[S:MyLanguage/Configuring_a_LAMPP_server_for_PHP_development|Einrichten eines LAMPP-Servers für die PHP-Entwicklung]])
-# Composer - for managing Joomla's PHP Dependencies - for help installing Composer read the documentation at https://getcomposer.org/doc/00-intro.md
+# Composer - um die Abhängigkeiten von Joomla!s PHP zu verwalten. Hilfe bei der Installation von Composer bietet die Dokumentation auf https://getcomposer.org/doc/00-intro.md
-# Node.js - for compiling Joomla's JavaScript and SASS files - for help installing Node.js please follow the instructions available on https://nodejs.org/en/
+# Node.js - um JavaScript- und SASS-Dateien für Joomla! zu kompilieren - Hilfe bei der Installation von Node.js bieten die Anweisungen, die auf https://nodejs.org/en/ erhältlich sind. Hinweis: Für die Installation von Joomla wird mindestens NodeJS 12 benötigt.
-# Git - for version management
+# Git - für die Versionsverwaltung.
-=== Steps to setup the local environment ===
+===Schritt für Schritt zur Installation der lokalen Entwicklungsumgebung===
-# Clone the repository
+# Das Repository klonen
-# run <tt>composer install</tt> from the root of the git repo (you can add --ignore-platform-reqs if you don't have the PHP-LDAP locally installed and you don't need it)
+# <span class="mw-translate-fuzzy">Zum Branch der aktuellen Version wechseln (derzeit ''4.3-dev'')</span>
-# run <tt>npm install</tt> from the root of the git repo
+# Die Installation von <tt>composer install</tt> im Stammverzeichnis des Git-Repositorys ausführen. (Man kann ''--ignore-platform-reqs'' hinzufügen, wenn man das PHP-LDAP nicht lokal installiert hat und es nicht benötigt.)
+# <span class="mw-translate-fuzzy">Im Stammverzeichnis des Git-Repositorys <tt>npm ci</tt> ausführen. (Bitte beachten, dass dafür npm 6.13.4 oder höher benötigt wird. Um die npm-Version auf die LTS-Version zu aktualisieren, sollte <tt>npm install -g npm@lts</tt> ausgeführt werden. Für Joomla 5 wird npm 10.1.0 oder höher benötigt. '''Tipp:''' Mit nvm (Node Version Manager) kann man leicht zu anderen npm-Versionen wechseln).</span>
+Linux und OSX Benutzer können den folgenden Bash-Alias nutzen und ihn in der ''~/.bashrc''-Datei setzen:
-== The a bit longer start guide ==
+<syntaxhighlight lang="bash">
-Joomla is not different to many other web tools these days. It has a large PHP part and it has more and more JavaScript code. While PHP coding doesn't need so much preparation, JavaScript needs a lot tooling around. The main reason is that nobody writes code in a way that every browser understands, so the code needs transpiling from e.g. ES6 to a compatible version of JavaScript. The same is true for CSS, for Joomla we are using SASS and this will be converted to native CSS so that any browser understands it. As downside setting up a dev environment is a bit more complicated but the tooling make coding also more convenient. Thanks to watchers and browser auto reload you can see your change in real time.
+alias jclean="rm -rf administrator/templates/atum/css; \
+rm -rf templates/cassiopeia/css; \
+rm -rf administrator/templates/system/css; \
+rm -rf templates/system/css; \
+rm -rf media/; \
+rm -rf node_modules/; \
+rm -rf libraries/vendor/; \
+rm -f administrator/cache/autoload_psr4.php; \
+rm -rf installation/template/css"
+alias jinstall="jclean; composer install; npm ci"
+</syntaxhighlight>
+Das wird alle kompilierten Dateien im System löschen und eine neue Installation über den Befehl <tt>jinstall</tt> innerhalb der Joomla-Installation starten. Man kann auch den Befehl <tt>jclean</tt> verwenden, um zu einem Joomla 3.x Branch zurückzuwechseln
+==Die etwas längere Startanleitung==
+Joomla ähnelt vielen anderen Web-Tools dieser Tage. Es hat einen großen PHP-Anteil und es hat mehr und mehr JavaScript-Code. Während die PHP-Codierung nicht so viel Vorbereitung benötigt, muss man bei JavaScript eine Menge Tools verwenden. Der Hauptgrund ist, dass niemand Code so schreibt, dass ihn jeder Browser versteht, also muss der Code z.B. von ES6 in eine kompatible Version von JavaScript umgesetzt werden. Das Gleiche gilt für CSS. Für Joomla verwenden wir SASS und das wird in natives CSS umgewandelt, sodass jeder Browser es versteht. Auf der anderen Seite ist das Einrichten einer Entwicklungsumgebung etwas komplizierter, aber das Instrumentarium macht das Programmieren bequemer. Dank der Wächter und dem automatischen Reload des Browsers, können Änderungen in Echtzeit verfolgt werden.
 === PHP ===
-It should be enough to run <tt>composer install</tt> as this will install PHP dependencies saved in the composer.lock file. You can do this as many times as you like, it will only install new packages when the composer.lock file is changed. Don't run <tt>composer update</tt> as this will update all packages to newer versions and update the composer.lock file.
+Es sollte reichen, <tt>composer install</tt> auszuführen. Dies wird die PHP-Abhängigkeiten, die in der Datei composer.lock gespeichert sind, installieren. Man kann dies beliebig oft wiederholen, es werden nur neue Pakete installiert, wenn die composer.lock Datei verändert wird. Bitte <tt>composer update</tt> nicht ausführen, da dadurch alle Pakete auf neuere Versionen und die composer.lock Datei aktualisiert werden.
+'''Hinweis:''' Möglicherweise muss <tt>composer install</tt> mit der Option <tt>--ignore-platform-reqs</tt> ausgeführt werden, um die in Composer angegebenen Plattformanforderungen zu ignorieren. Das gilt, falls die PHP-LDAP-Erweiterung nicht installiert ist.
-Note: You may need to run <tt>composer install</tt> with the <tt>--ignore-platform-reqs</tt> option to ignore platform requirements specified in Composer, i.e. if you do not have PHP's LDAP extension installed.
+===Node/npm Skripte===
-=== Node/npm scripts ===
+Node.js wird mit dem Paketmanager „NPM“ ausgeliefert (gewissermaßen vergleichbar zu Composer). NPM hat einen <tt>run</tt>-Befehl und wir haben einige Skripte vorbereitet, um die Arbeit zu erleichtern. Die Befehle müssen im Stammverzeichnis des Repositorys ausgeführt werden, sobald JS- oder SASS-Dateien geändert wurden. Zuvor muss man einmalig <tt>npm ci</tt> ausführen, um die Abhängigkeiten zu installieren.
-Node.js comes with a package manager called NPM (in some way the same as Composer). NPM has a <tt>run</tt> command and we have prepared some scripts to make your life easier. You have to run the commands for the root of the repository.
-==== npm run build:css ====
+====npm run build:css====
-<noinclude>It will compile SASS files to CSS and also create the minified files.</noinclude>
+Kompiliert SASS Dateien nach CSS und erzeugt die komprimierten Dateien.
 ==== npm run build:js ====
-It will compile and transpile the JavaScript files to the correct format and create minified files
+Es kompiliert und übersetzt die JavaScript-Dateien in das richtige Format und erstellt sogenannte Minified-Dateien.
-==== npm run watch:css ====
+==== npm run watch ====
-This is the same as the <tt>build:css</tt> command but will watch for changes and automatically build updated files.
+Dieser Befehl entspricht dem Befehl <tt>build:js</tt>, erkennt jedoch Änderungen und erstellt automatisch aktualisierte Dateien im Medienverzeichnis. SASS-Dateien sind noch nicht enthalten.
-==== npm run watch:js ====
-This is the same as the <tt>build:js</tt> command but will watch for changes and automatically build updated files.
 ==== npm run lint:js ====
-This will make a syntax check on JavaScript files.
+Damit wird eine Syntaxprüfung aller ES6-JavaScript-Dateien gegen den JavaScript-Codestandard durchgeführt (für weitere Informationen zum Joomla 4-Codestandard, bitte das [https://developer.joomla.org/coding-standards/introduction.html| Codestandard-Handbuch] lesen).
 ==== npm run test ====
-This will run other JavaScript testing suite.
+Dies wird eine JavaScript Testsuite ausführen.
+==Mögliche Probleme==
+Beim Installieren des Composers kann es zu folgenden Fehlern kommen:
+<syntaxhighlight lang="bash">
+Problem 1
+    - Installation request for joomla/ldap 2.0.0-beta -> satisfiable by joomla/ldap[2.0.0-beta].
+    - joomla/ldap 2.0.0-beta requires ext-ldap * -> the requested PHP extension ldap is missing from your system.
+Problem 2
+    - Installation request for symfony/ldap v5.1.5 -> satisfiable by symfony/ldap[v5.1.5].
+    - symfony/ldap v5.1.5 requires ext-ldap * -> the requested PHP extension ldap is missing from your system.
+</syntaxhighlight>
+Die Lösung ist, die Composer-Installation mit der Option <tt>--ignore-platform-reqs</tt> auszuführen, um die in Composer angegebenen Plattformanforderungen zu ignorieren. Das heißt, wenn die LDAP-Erweiterung von PHP nicht installiert ist.
+<syntaxhighlight lang="bash">composer install --ignore-platform-reqs</syntaxhighlight>
+Wenn ein Anmeldefehler, wie unten abgebildet, angezeigt wird, sollte die Datei <tt>administrator/cache/autoload_psr4.php</tt>, wie im zweiten Bild gezeigt, gelöscht werden.
+[[File:Install-error.png|border|center|400px|Login After Install Error]]
 <noinclude>

J4.x