Development #

owncloud.online is file storage, sharing, and collaboration on your own server, built for PHP 8.4 and maintained by BW-Tech GmbH.

The source code is at https://github.com/BWTECH-github/owncloud.online, the release packages at https://github.com/BWTECH-github/owncloud.online/releases. The current version is 11.0.25 (version.php).

Repository layout #

Requirements #

You need the PHP extensions from the require block of composer.json: apcu, ctype, curl, exif, fileinfo, gd, iconv, imagick, intl, json, libxml, mbstring, memcached, pdo, posix, simplexml, zip. Add the driver for the database you use; pdo_sqlite is enough to get started.

The JavaScript tests also need Firefox: tests/karma.config.js starts FirefoxHeadless.

Getting the dependencies #

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

make install-composer-deps runs composer install including the development dependencies and puts everything into lib/composer/. That is also where PHPUnit ends up (lib/composer/phpunit/phpunit/phpunit), which the test targets use.

The check tools come from separate installations in vendor-bin/:

make vendor-bin-deps

This installs php-cs-fixer, PHP_CodeSniffer, Phan, PHPStan, and Behat. The code style job (.github/workflows/lint-and-codestyle.yml) runs exactly these two commands.

For JavaScript tests and the minifiers:

make install-nodejs-deps

This runs yarn install in the build/ directory.

make without a target fetches the Composer and Node dependencies in one step. make help lists the common targets; vendor-bin-deps, minify-assets, check-minified, and test-js-browser are not listed there. make clean removes dependencies, test results, and the build directory.

A development instance #

You can install the checkout directly with occ:

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

SQLite is enough for daily work. For MySQL, MariaDB, or PostgreSQL, add --database-host, --database-name, --database-user, and --database-pass; the CI sets it up the same way (.github/workflows/php-unit.yml).

Enable the bundled apps one by one. The CI uses the same selection:

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

PHP's built-in server is enough to try things in the browser:

php8.4 -S localhost:8080 -t .

This is a development server only. The CI's upgrade job checks an instance the same way (.github/workflows/upgrade-test.yml): status.php and /index.php/login must answer with 200, and the PHP server's output must not contain a fatal PHP error (PHP Fatal, Uncaught).

Two keys in config/config.php help during development:

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

debug shows exceptions with their stack trace in the web interface. config.sample.php warns against setting this on a production system: a stack trace can contain passwords in plain text. loglevel 0 also writes debug messages to the log, see Server log and error messages.

Check the state:

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

Adding apps from the Marketplace #

Everything that is not in the repository comes from the Marketplace (marketplace.owncloud.online): in the web interface through the app menu → Market, or on the command line.

php8.4 occ market:install <app_id>

If you have a package as a .tar.gz file, such as a plugin you built yourself, install it without going through the Marketplace:

php8.4 occ market:install --local /path/to/app.tar.gz

On a server installation, the same call is:

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

The Marketplace shows some apps only with an API key. You get the key from BW-Tech GmbH. Apps and Marketplace explains app management and where to enter the key.

Tests #

A single test file, in the form given by make help:

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

The CI runs the unit tests against SQLite, MySQL 8.0, MariaDB 10.6 and 10.11, and PostgreSQL 16. The runs other than SQLite are limited to the DB group; the SQLite run covers everything else.

The Behat targets need a running instance with the testing app, which this repository does not include. No CI job runs them. Without TEST_SERVER_URL, tests/acceptance/run.sh starts its own PHP development server.

Besides the test targets, the CI runs two more checks that are easy to miss (.github/workflows/lint-and-codestyle.yml):

• composer audit --locked for the repository itself and for apps/oco_mcp and apps-external/market. A new or upgraded dependency with a known security advisory fails the CI.
• The standalone security tests of the oco_mcp app (apps/oco_mcp/tests/basic_auth_test.php and security_test.php). They run without an instance, and you can run them locally the same way.

Changes to the Market app #

apps-external/market/ is not edited in this repository. The Market app has its own repository, BWTECH-github/market; this repository holds a copy because the app belongs in the release package. build/market.ref records which state that is. A change to the Market app therefore works like this:

1. Change, test, commit, and push in the Market repository.
2. Run build/sync-market.sh <commit> here. It copies exactly that state to apps-external/market/ and rewrites build/market.ref.
3. Commit both here.

The script copies all versioned files of the Market repository except .github/, .gitignore, and tests/. On every push to main and in every pull request, the market-copy job in .github/workflows/lint-and-codestyle.yml compares the copy with the recorded state (build/sync-market.sh --check) and turns red if someone edited the copy directly.

The script does not take build/market.ref on trust: repo= must be https://github.com/BWTECH-github/market.git, commit= a full commit ID (40 hex characters), and a <ref> argument a commit, tag, or branch without a leading -. Otherwise it exits with code 2 without fetching or changing anything. --check also requires that the commit is reachable from main or a tag in the Market repository. If the state exists only in a pull request or on another branch, the script also exits with 2. So merge the change in the Market repository first, then copy it.

MARKET_REPO=<URL or path> fetches the state from another source when copying, such as a local clone. Combined with --check, the script exits with 2; the check always runs against GitHub. bash tests/build/sync_market_test.sh tests these rules without network access and runs in the same job before the comparison. In addition, when files under apps-external/market/ change, .github/workflows/market-bundle.yml rebuilds js/market.bundle.js from src/ and fails the job if the checked-in bundle differs.

Code style #

The reference is php-cs-fixer with the rule set from vendor-bin/owncloud-codestyle, configured in .php-cs-fixer.dist.php. It checks the core and the bundled apps except oco_mcp; apps-external, build, data, and lib/composer are excluded.

make test-php-style      # checks, changes nothing
make test-php-style-fix  # fixes what can be fixed automatically

Both targets pass --allow-risky yes. If you run php-cs-fixer by hand without this option, your result differs from the CI's.

Two rules the formatter does not enforce:

• New methods in lib/public/ need an @since tag. build/OCPSinceChecker.php runs in make test-php-style and also at the start of every build/autotest.sh run.
• Code and identifiers in English; for PHP 8.4, the points in PHP 8.4 compatibility apply.

Minified sibling files #

TemplateLayout::preferMinified() serves foo.min.js as soon as it sits next to foo.js, limited to paths below the server directory (OC::$SERVERROOT). If you change a .js or .css file and leave the .min file next to it as it is, nothing changes in what the server delivers.

So the rule is: after every change to JavaScript or CSS, run

make minify-assets

and commit the result. The target calls build/minify-assets.sh and generates the sibling files for core/js, settings/js, apps/*/js, and the matching CSS directories; tests/ and vendor/ are skipped.

The CI has a dedicated gate for this, the Minified assets up to date job: it runs make minify-assets and fails as soon as

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

prints anything afterwards. The release build runs the same comparison. Locally, make check-minified does both in one step and stops when something differs; the newly generated files stay in your working tree.

Use the same minifiers as the CI, otherwise you get different bytes:

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

make install-nodejs-deps installs both in the same versions (build/package.json). The script prefers the installation in build/node_modules and only then falls back to global installations. If it finds no minifier at all, it copies the original file to the .min name. The checkout keeps working, but the result differs from the CI and the gate turns red.

Documentation #

The pages in docs/ are the source of the published documentation at https://docs.owncloud.online. The navigation is in the nav block of mkdocs.yml; a new page without an entry there does not appear in the navigation. Plugin pages in docs/plugins/apps/ are the exception: they appear in the Plugins section without an entry.

Build and check:

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

.github/workflows/docs.yml runs exactly this. With --strict, a single warning fails the build, for example a link to a page that does not exist.

Changes that only touch docs/, mkdocs.yml, requirements-docs.txt, changelog/, or Markdown files do not trigger the other CI runs: ci.yml and lint-and-codestyle.yml exclude them under paths-ignore.

Submitting a contribution #

The full text is in .github/CONTRIBUTING.md. The essentials:

1. Branch off main, one topic per pull request.
2. Add tests where behavior changes.
3. For changes to .js or .css: run make minify-assets and commit the result.
4. Add a changelog entry to changelog/unreleased/, structured like changelog/TEMPLATE. The first line starts with one of the types Bugfix, Change, Enhancement, or Security.
5. Write commit messages in the Conventional Commits format. A dedicated CI job checks this. Valid types: feat, fix, docs, style, refactor, test, build, perf, ci, chore, revert; the check rejects any other type.
6. Open the pull request and explain why the change is needed. The template .github/PULL_REQUEST_TEMPLATE.md asks for your environment and the cases you actually tried; "should work" is not a test.

To report a bug you do not fix yourself, use the repository's issues. Security vulnerabilities do not belong in an issue; follow the confidential process described in .github/SECURITY.md.

A pull request has to pass: commit format, PHP code style, PHPStan, Phan, Composer audit, the oco_mcp security tests, the gate for the minified files, the Market copy check, the JavaScript tests, the unit tests on all four database systems, and the upgrade test, which upgrades an existing installation of each of the last two releases to the new state. If the pull request changes anything under apps-external/market/, market-bundle.yml also checks the Market app's JavaScript bundle.

What a release contains #

A tag of the form v<version> triggers .github/workflows/release-owncloud-online.yml. Before packaging, the run checks the same gate as the CI: if the .min sibling files are not up to date, it stops. It then produces these files, available at https://github.com/BWTECH-github/owncloud.online/releases:

Troubleshooting #

More pages for developers: PHP 8.4 compatibility and Building a release.