For the complete documentation index, see llms.txt. This page is also available as Markdown.

Developer Guide

This guide helps contributors run OpenCATS locally and mirror the current CI test workflow.

Prerequisites

  • Git

  • Docker with Docker Compose v2

  • PHP 8.4.1 or later within PHP 8 if running tests directly on the host

  • Composer 2

Project CI currently tests PHP 8.4.1 and PHP 8.5.

Clone and install dependencies

git clone https://github.com/opencats/OpenCATS.git
cd OpenCATS
composer install

Do not use --no-dev for development, because PHPUnit, Behat, and related tools are development dependencies.

Prepare the Docker test environment

The local test workflow mirrors CI:

cp test/config.php ./config.php
touch ./INSTALL_BLOCK
cd docker/
docker compose -f docker-compose-test.yml up -d --build

The test Docker setup defaults to PHP 8.4.1. To build the test stack with another CI-supported PHP version, for example PHP 8.5:

The test Docker setup uses two MariaDB 10.7 databases:

  • opencatsdb on port 3306 for functional and Behat testing.

  • integrationtestdb on port 3307 for disposable PHPUnit integration tests.

Install dependencies inside the PHP container if needed:

Run tests

From the OpenCATS repository, unit tests can be run directly with:

From the docker/ directory, the Docker-backed suites are:

Current CI runs PHPUnit unit tests, Docker-backed PHPUnit integration tests, the default Behat suite, and the security Behat suite for both PHP 8.4.1 and PHP 8.5. CI also performs a PHP syntax check over src/ and a Composer audit. The audit is currently non-blocking so legacy dependency advisories can be reviewed without stopping all builds.

Pull request title format

OpenCATS pull request titles must use:

Allowed types are:

  • chore

  • docs

  • feat

  • fix

  • refactor

  • security

  • test

Scopes are not currently allowed. For example, use fix: correct login redirect, not fix(auth): correct login redirect.

Development notes

  • Do not commit local credentials or production config.php changes.

  • Reuse existing OpenCATS helpers and conventions rather than introducing duplicate utility code.

  • Use the Docker test stack when changing database, authorization, upload, import, installer, or PHP-version-sensitive behavior.

  • Add or update tests when changing application behavior.

  • Shut down the test stack when finished:

Last updated