Entwicklung #

owncloud.online ist Dateiablage, Freigabe und Zusammenarbeit auf dem eigenen Server, gebaut für PHP 8.4 und gepflegt von der BW-Tech GmbH.

Der Quelltext liegt unter https://github.com/BWTECH-github/owncloud.online, fertige Pakete unter https://github.com/BWTECH-github/owncloud.online/releases. Die aktuelle Version ist 11.0.25 (version.php).

Aufbau des Repositorys #

Voraussetzungen #

Nötig sind die PHP-Erweiterungen aus dem require-Block der composer.json: apcu, ctype, curl, exif, fileinfo, gd, iconv, imagick, intl, json, libxml, mbstring, memcached, pdo, posix, simplexml, zip. Dazu kommt der Treiber der Datenbank, die Sie benutzen; für den Anfang genügt pdo_sqlite.

Für die JavaScript-Tests brauchen Sie zusätzlich Firefox: tests/karma.config.js startet FirefoxHeadless.

Abhängigkeiten holen #

git clone https://github.com/BWTECH-github/owncloud.online.git
cd owncloud.online
make install-composer-deps

make install-composer-deps ruft composer install einschließlich der Entwicklungsabhängigkeiten auf und legt alles unter lib/composer/ ab. Dort liegt danach auch PHPUnit (lib/composer/phpunit/phpunit/phpunit), das die Testziele benutzen.

Die Prüfwerkzeuge kommen aus eigenen Installationen unter vendor-bin/:

make vendor-bin-deps

Damit liegen php-cs-fixer, PHP_CodeSniffer, Phan, PHPStan und Behat bereit. Genau diese beiden Aufrufe macht auch der Codestil-Job (.github/workflows/lint-and-codestyle.yml).

Für JavaScript-Tests und die Minifizierer:

make install-nodejs-deps

Das führt yarn install im Verzeichnis build/ aus.

make ohne Ziel holt Composer- und Node-Abhängigkeiten in einem Schritt. make help listet die gebräuchlichen Ziele auf; vendor-bin-deps, minify-assets, check-minified und test-js-browser stehen nicht darin. make clean entfernt Abhängigkeiten, Testergebnisse und Bauverzeichnis.

Eine Instanz zum Entwickeln #

Installieren lässt sich der Checkout direkt über occ:

php8.4 occ maintenance:install \
  --database sqlite \
  --admin-user admin \
  --admin-pass 'BitteEigenesPasswortWaehlen' \
  --data-dir "$(pwd)/data"

SQLite reicht für die tägliche Arbeit. Für MySQL, MariaDB oder PostgreSQL kommen --database-host, --database-name, --database-user und --database-pass hinzu; so richtet es auch die CI ein (.github/workflows/php-unit.yml).

Die mitgelieferten Apps schalten Sie einzeln ein. Dieselbe Auswahl benutzt die CI:

php8.4 occ app:enable files_sharing
php8.4 occ app:enable files_trashbin
php8.4 occ app:enable files_versions
php8.4 occ app:enable provisioning_api
php8.4 occ app:enable federation
php8.4 occ app:enable federatedfilesharing

Zum Ausprobieren im Browser genügt der eingebaute Server von PHP:

php8.4 -S localhost:8080 -t .

Das ist nur ein Entwicklungsserver. Der Upgrade-Job der CI prüft eine Instanz auf demselben Weg (.github/workflows/upgrade-test.yml): status.php und /index.php/login müssen mit 200 antworten, und in der Ausgabe des PHP-Servers darf kein fataler PHP-Fehler (PHP Fatal, Uncaught) stehen.

Zwei Schlüssel in config/config.php helfen beim Entwickeln:

'debug' => true,
'loglevel' => 0,

debug zeigt Ausnahmen samt Aufrufliste in der Weboberfläche. config.sample.php warnt davor, das auf einem Produktivsystem zu setzen: Eine Aufrufliste kann Passwörter im Klartext enthalten. loglevel 0 schreibt auch Debug-Meldungen ins Protokoll, siehe Serverprotokoll und Fehlermeldungen.

Zustand prüfen:

php8.4 occ status
php8.4 occ app:list

Apps aus dem Marktplatz ergänzen #

Alles, was nicht im Repository liegt, kommt aus dem Marktplatz (marketplace.owncloud.online): in der Weboberfläche über das App-Menü → Markt oder auf der Kommandozeile.

php8.4 occ market:install <app_id>

Ein Paket, das Ihnen als .tar.gz vorliegt, etwa ein selbst gebautes Plugin, spielen Sie ohne den Umweg über den Marktplatz ein:

php8.4 occ market:install --local /pfad/zu/app.tar.gz

Auf einer Serverinstallation lautet derselbe Aufruf:

sudo -u www-data php8.4 occ market:install <app_id>

Manche Apps zeigt der Marktplatz nur mit API-Schlüssel. Den Schlüssel erhalten Sie von der BW-Tech GmbH. Näheres zur Verwaltung von Apps und zum Schlüssel steht unter Apps und Marketplace.

Tests #

Eine einzelne Testdatei, mit der in make help genannten Form:

make test-php-unit TEST_DATABASE=mysql TEST_PHP_SUITE=path/to/testfile.php

Die CI führt die Unit-Tests gegen SQLite, MySQL 8.0, MariaDB 10.6 und 10.11 sowie PostgreSQL 16 aus. Die Läufe außer SQLite beschränken sich auf die Gruppe DB; alles andere prüft der SQLite-Lauf.

Die Behat-Ziele brauchen eine laufende Instanz mit der App testing, die dieses Repository nicht mitliefert. Kein CI-Job führt sie aus. Ohne TEST_SERVER_URL startet tests/acceptance/run.sh einen eigenen PHP-Entwicklungsserver.

Neben den Testzielen laufen in der CI noch zwei Prüfungen, die leicht übersehen werden (.github/workflows/lint-and-codestyle.yml):

• composer audit --locked für das Repository selbst sowie für apps/oco_mcp und apps-external/market. Eine neue oder angehobene Abhängigkeit mit bekanntem Sicherheitshinweis (Advisory) bringt die CI zu Fall.
• die eigenständigen Sicherheitstests der App oco_mcp (apps/oco_mcp/tests/basic_auth_test.php und security_test.php). Sie laufen ohne Instanz und lassen sich lokal genauso aufrufen.

Änderungen an der Market-App #

apps-external/market/ wird nicht in diesem Repository bearbeitet. Die Market-App hat ihr eigenes Repository, BWTECH-github/market; hier liegt eine Kopie davon, weil sie ins Release-Paket gehört. Welcher Stand das ist, hält build/market.ref fest. Eine Änderung an der Market-App läuft deshalb so:

1. im Market-Repository ändern, testen, committen und pushen
2. hier build/sync-market.sh <commit> ausführen; das übernimmt genau diesen Stand nach apps-external/market/ und schreibt build/market.ref neu
3. beides hier committen

Das Skript übernimmt alle versionierten Dateien des Market-Repositorys außer .github/, .gitignore und tests/. Der Job market-copy in .github/workflows/lint-and-codestyle.yml vergleicht bei jedem Push auf main und in jedem Pull Request die Kopie mit dem festgehaltenen Stand (build/sync-market.sh --check) und wird rot, wenn jemand die Kopie direkt bearbeitet hat.

build/market.ref übernimmt das Skript dabei nicht blind: repo= muss https://github.com/BWTECH-github/market.git sein, commit= eine volle Commit-ID (40 Hex-Zeichen) und ein <ref>-Argument ein Commit, Tag oder Zweig ohne führendes -. Sonst endet es mit dem Rückgabewert 2, ohne etwas abzurufen oder zu ändern. --check verlangt außerdem, dass der Commit im Market-Repository von main oder einem Tag aus erreichbar ist. Liegt der Stand nur in einem Pull Request oder auf einem anderen Zweig, endet das Skript ebenfalls mit 2. Führen Sie die Änderung also erst im Market-Repository zusammen und übernehmen Sie sie dann.

MARKET_REPO=<URL oder Pfad> holt den Stand beim Übernehmen aus einer anderen Quelle, etwa einem lokalen Klon. Zusammen mit --check bricht das Skript mit 2 ab; geprüft wird immer gegen GitHub. bash tests/build/sync_market_test.sh prüft diese Regeln ohne Netz und läuft im selben Job vor dem Vergleich. Zusätzlich baut .github/workflows/market-bundle.yml bei Änderungen unter apps-external/market/ die Datei js/market.bundle.js aus src/ nach und lässt den Job scheitern, wenn das eingecheckte Bündel davon abweicht.

Codestil #

Maßgeblich ist php-cs-fixer mit dem Regelsatz aus vendor-bin/owncloud-codestyle, konfiguriert in .php-cs-fixer.dist.php. Geprüft werden der Kern und die mitgelieferten Apps außer oco_mcp; apps-external, build, data und lib/composer sind ausgenommen.

make test-php-style      # prüft, ändert nichts
make test-php-style-fix  # korrigiert, was sich automatisch korrigieren lässt

Beide Ziele setzen --allow-risky yes. Rufen Sie php-cs-fixer von Hand ohne diese Option auf, weicht das Ergebnis von dem der CI ab.

Zwei Regeln, die der Formatierer nicht durchsetzt:

• Neue Methoden in lib/public/ brauchen eine @since-Angabe. build/OCPSinceChecker.php läuft in make test-php-style und zusätzlich am Anfang jedes build/autotest.sh-Laufs.
• Code und Bezeichner auf Englisch; für PHP 8.4 gelten die Punkte unter Kompatibilität mit PHP 8.4.

Minifizierte Geschwisterdateien #

TemplateLayout::preferMinified() liefert eine foo.min.js aus, sobald sie neben foo.js liegt, begrenzt auf Pfade unterhalb des Serververzeichnisses (OC::$SERVERROOT). Wer eine .js- oder .css-Datei ändert und die .min-Datei daneben stehen lässt, ändert damit nichts an dem, was der Server ausliefert.

Führen Sie deshalb nach jeder Änderung an JavaScript oder CSS diesen Befehl aus und checken Sie das Ergebnis mit ein:

make minify-assets

Das Ziel ruft build/minify-assets.sh auf und erzeugt die Geschwisterdateien für core/js, settings/js, apps/*/js sowie die entsprechenden CSS-Verzeichnisse; tests/ und vendor/ bleiben außen vor.

Die CI hat dafür ein eigenes Tor, den Job Minified assets up to date: Er ruft make minify-assets auf und lässt den Lauf scheitern, sobald danach

git status --porcelain -- '*.min.js' '*.min.css'

irgendetwas ausgibt. Denselben Vergleich macht der Release-Bau. Lokal erledigt make check-minified beides in einem Schritt und bricht bei einer Abweichung ab; die neu erzeugten Dateien bleiben im Arbeitsverzeichnis liegen.

Benutzen Sie dieselben Minifizierer wie die CI, sonst entstehen andere Bytes:

npm install -g terser@5.49.1 clean-css-cli@5.6.3

make install-nodejs-deps bringt beide in denselben Versionen mit (build/package.json). Das Skript bevorzugt die Installation unter build/node_modules und greift erst danach auf global installierte zurück. Findet es gar keinen Minifizierer, kopiert es die Originaldatei auf den .min-Namen. Der Checkout bleibt dann funktionsfähig, aber das Ergebnis weicht von dem der CI ab, und das Tor wird rot.

Dokumentation #

Die Seiten unter docs/ sind die Quelle der veröffentlichten Dokumentation auf https://docs.owncloud.online. Die Navigation steht im nav-Block der mkdocs.yml; eine neue Seite ohne Eintrag dort erscheint in der Navigation nicht. Ausnahme sind die Plugin-Seiten unter docs/plugins/apps/, die ohne Eintrag im Bereich Plugins erscheinen.

Bauen und prüfen:

python3 -m pip install -r requirements-docs.txt
python3 -m mkdocs build --strict

Genau diesen Aufruf macht .github/workflows/docs.yml. Mit --strict scheitert der Bau schon an einer einzigen Warnung, etwa an einem Verweis auf eine Seite, die es nicht gibt.

Änderungen, die nur docs/, mkdocs.yml, requirements-docs.txt, changelog/ oder Markdown-Dateien betreffen, lösen die übrigen CI-Läufe nicht aus: ci.yml und lint-and-codestyle.yml nehmen sie unter paths-ignore aus.

Einen Beitrag einreichen #

Der ausführliche Text steht in .github/CONTRIBUTING.md, hier das Wesentliche:

1. Einen eigenen Zweig von main anlegen, ein Thema pro Pull Request.
2. Tests ergänzen, wo sich Verhalten ändert.
3. Bei Änderungen an .js oder .css: make minify-assets laufen lassen und das Ergebnis mitcommitten.
4. Einen Changelog-Eintrag nach changelog/unreleased/ legen, aufgebaut wie changelog/TEMPLATE. Die erste Zeile beginnt mit einem der Typen Bugfix, Change, Enhancement oder Security.
5. Commit-Nachrichten im Format Conventional Commits. Ein eigener CI-Job prüft das. Gültige Typen: feat, fix, docs, style, refactor, test, build, perf, ci, chore, revert; andere lehnt die Prüfung ab.
6. Den Pull Request öffnen und begründen, warum die Änderung nötig ist. Die Vorlage .github/PULL_REQUEST_TEMPLATE.md fragt Umgebung und tatsächlich durchgespielte Fälle ab; „sollte funktionieren“ ist keine Prüfung.

Fehler, die Sie nicht selbst beheben, melden Sie über die Issues des Repositorys. Sicherheitslücken gehören nicht in ein Issue; dafür gilt der vertrauliche Weg aus .github/SECURITY.md.

Ein Pull Request muss diese Prüfungen bestehen: Commit-Format, PHP-Codestil, PHPStan, Phan, Composer-Audit, die oco_mcp-Sicherheitstests, das Tor für die minifizierten Dateien, den Abgleich der Market-Kopie, die JavaScript-Tests, die Unit-Tests auf allen vier Datenbanksystemen und den Upgrade-Test, der eine bestehende Installation der letzten beiden Releases auf den neuen Stand hebt. Ändert der Pull Request etwas unter apps-external/market/, prüft market-bundle.yml zusätzlich das JavaScript-Bündel der Market-App.

Was ein Release enthält #

Ein Tag der Form v<version> stößt .github/workflows/release-owncloud-online.yml an. Vor dem Packen prüft der Lauf dasselbe Tor wie die CI: Sind die .min-Geschwisterdateien nicht aktuell, bricht er ab. Danach entstehen diese Dateien, zu finden unter https://github.com/BWTECH-github/owncloud.online/releases:

Fehlersuche #

Weitere Seiten für Entwickler: Kompatibilität mit PHP 8.4 und Ein Release bauen.