Development

🧑‍💻 Development

Tip

TL;DR make build builds everything in throwaway containers, make build && make rsync TARGET=/var/www/nextcloud/apps OCC=1 deploys to a test instance. The host needs only podman or Docker.

The app is built with ncmake. The Makefile in the repository is the ncmake bootstrap stub: on first use it fetches the shared ncmake Makefile into a per-machine cache and keeps it current from then on. make help lists every target, make help-<target> explains one.

🧰 Requirements

• podman (preferred) or Docker. Composer and npm run in throwaway containers, so the host needs neither PHP nor Node.
• For the unit tests that touch OCP/OC: a Nextcloud server with the app inside its apps/ directory (see Unit tests).

🔨 Building

make build

This is the complete build: composer install --no-dev for the runtime dependency (spomky-labs/otphp) and the Vite build of the three frontend entry points (personal settings, admin settings, login setup). vendor/, js/ and css/ are git-ignored, so a fresh clone needs make build before it runs. The ncmake wiki describes building and packaging in detail.

✅ Quality gates

make composer ARGS=install installs the PHP dev tools once: via the bamarni/composer-bin-plugin each tool lands in its own vendor-bin/<tool>/ namespace (php-cs-fixer, psalm, phpunit, rector, nextcloud/ocp), with its binary linked into vendor/bin/.

Command	Purpose
make composer ARGS=lint	php -l syntax check over all PHP files
make composer ARGS="cs:check"	code-style check (nextcloud/coding-standard)
make composer ARGS="cs:fix"	auto-fix code-style issues
make psalm	static analysis (errorLevel 4)
make composer ARGS="exec -- rector --dry-run"	show modernization suggestions (no changes)
make composer ARGS=rector	apply rector suggestions, then cs:fix
make npm ARGS="run lint"	eslint (run lint:fix to auto-fix)
make npm ARGS="run stylelint"	stylelint (run stylelint:fix to auto-fix)
make npm ARGS="run test"	vitest unit tests
make reuse	REUSE license compliance

Expected on a clean tree: lint clean, cs:check reports 0 of N files, psalm says No errors found (info-level notes such as MissingClassConstType are expected while the PHP floor is below 8.3, which introduced typed class constants), rector --dry-run reports no changes.

Every pull request runs these gates (except rector) as GitHub workflows, together with the frontend build and the PHPUnit suite on SQLite, MySQL, MariaDB, PostgreSQL and Oracle.

🧪 Unit tests

tests/bootstrap.php boots the surrounding Nextcloud when the app sits inside a real apps/ directory, and falls back to the app's own Composer autoloader otherwise. The OCRA test (tests/unit/Service/OcraTest.php) is pure PHP and runs in either case:

make composer ARGS="exec -- phpunit tests/unit/Service/OcraTest.php"

Tests that touch OCP/OC need a surrounding Nextcloud. On a Nextcloud server, symlink the checkout into its apps/ directory and run the suite there:

ln -s /path/to/twofactor_oath /var/www/nextcloud/apps/twofactor_oath
composer test:unit

The same symlink lets Nextcloud load and enable the app for manual testing.

🚀 Deploying to a test instance

make build && make rsync TARGET=/var/www/nextcloud/apps OCC=1

TARGET is the parent apps/ directory. OCC=1 disables the app, copies the shipped file set, sets the owner and enables the app again, so info.xml is re-read and migrations run. Over ssh, TARGET takes the form deploy@host:/var/www/nextcloud/apps; for a running container such as Nextcloud All-in-One:

make build && make cp TARGET=nextcloud-aio-nextcloud:/var/www/html/custom_apps OCC=1

All options are in the ncmake installation guide.

Schema changes

A new or altered column requires disabling the app, dropping the table and the oc_migrations row for twofactor_oath, then re-enabling so the migration runs again. There is no automatic down-migration.

🏷️ Releasing

main is protected (required checks and signed commits), so a version bump cannot be pushed to it directly. The version lives in appinfo/info.xml, composer.json and package.json; make version bumps all three, never edit them by hand. The release cycle (make version on a ncmake/release/X.Y.Z branch, make changelog, pull request, then make tag on main) is described on the ncmake wiki page Releasing.

From the tag you publish a GitHub release; the release workflow builds the tarball and attaches it as an asset. make publish GH=1 then submits the release to the App Store.

🔑 The OCRA test token

tools/ocra_device is a standalone software OCRA token used to test challenge-response without hardware. It reuses the app's own (RFC-vector-verified) Ocra class. See OCRA.

📜 Licensing / REUSE

Every file carries an SPDX header or is covered by REUSE.toml. make reuse runs the REUSE checker in a container.