Getting started

Getting started

This guide covers setting up the LiturgicalCalendar project for local development. There are two approaches: native PHP or Docker Compose.

Prerequisites

Native PHP

• PHP 8.4+ with the following extensions: intl, zip, calendar, yaml, gettext
• Composer for dependency management
• PostgreSQL (optional, only needed for RBAC/authentication features)

Docker

• Docker and Docker Compose
• No local PHP installation required

Cloning the repository

git clone https://github.com/Liturgical-Calendar/LiturgicalCalendarAPI.git
cd LiturgicalCalendarAPI
composer install

Environment configuration

Copy the example environment file and adjust as needed:

cp .env.example .env.local

The key variables for local development are:

• API_PROTOCOL, API_HOST, API_PORT — where the API server listens (defaults: http, localhost, 8000)
• APP_ENV — set to development
• JWT_SECRET — for authentication (a default is provided for development)

See .env.example for the full list of configuration options with documentation.

Running the API server

Option A: Native PHP

The API requires a multi-worker setup (6 workers) because it uses PHP's built-in server:

composer start    # Starts the server on localhost:8000
composer stop     # Stops the server

Alternatively, use the shell script directly:

./start-server.sh

If using VS Code, you can start the server via Ctrl+Shift+B (the project includes a tasks.json configuration).

Option B: Docker Compose

The docker-compose.yml in the API repository provides the full infrastructure stack:

• Zitadel — OIDC identity provider
• Login V2 — Zitadel login UI
• OpenFGA — fine-grained authorization
• PostgreSQL — database
• Mailpit — email testing
• Adminer — database UI

docker compose up -d

See infrastructure/README.md in the API repository for detailed setup instructions, port assignments, and troubleshooting.

Running tests

# Run all tests (requires the API server to be running for integration tests)
composer test

# Run only fast unit tests (no server needed)
composer test:quick

# Run a single test file
vendor/bin/phpunit phpunit_tests/Services/RateLimiterTest.php

See How to write unit tests for details on the test infrastructure.

Code quality

composer lint          # Check code style (phpcs, PSR-12)
composer lint:fix      # Auto-fix code style
composer analyse       # PHPStan static analysis (level 10)
composer parallel-lint # PHP syntax checking
composer lint:md       # Markdown linting

Frontend setup

The frontend is a separate repository. To set it up alongside the API:

git clone https://github.com/Liturgical-Calendar/LiturgicalCalendarFrontend.git
cd LiturgicalCalendarFrontend
composer install
cp .env.example .env.development

Start the frontend development server (ensure the API is running first):

php -S localhost:3000

The frontend repository also has its own docker-compose.yml that orchestrates the full stack including the API, frontend, and test interface. See the Frontend README for details.

WebSocket test server

The liturgical event test interface uses a WebSocket server:

composer ws:start    # Start the WebSocket test server
composer ws:stop     # Stop the WebSocket test server

See Unit Test server and interface for details.

Further reading

• API README — full project description, data sources, and characteristics
• Infrastructure README — Docker Compose stack details and troubleshooting
• Source data — how the liturgical calendar source data is organized
• Translating — contributing translations via Weblate