# Repository Guidelines

## Project Structure & Module Organization
- `podlove.php` and `plugin.php` are the plugin entry points.
- PHP source lives in `includes/` and `lib/`; templates in `templates/`; view helpers in `views/`.
- Client assets are split between legacy JS in `js/` and the newer app in `client/`.
- Static assets are in `css/`, `images/`, and `fonts/`.
- Tests live in `tests/phpunit/` with suites under `integration/` and `rest/`.
- Build artifacts are staged in `dist/` (generated by `make build`).

## Build, Test, and Development Commands
- `make install`: installs PHP tooling and prefixed dependencies (uses PHP-Scoper).
- `make format`: runs PHP-CS-Fixer to format PHP code.
- `npm run wp-env:start`: starts the local WordPress development environment on port 8888.
- `npm run wp-env:stop`: stops the development `wp-env` environment.
- `npm run wp-env:test:start`: starts the dedicated test `wp-env` environment on port 8889.
- `npm run wp-env:test:stop`: stops the dedicated test environment.
- `npm run test`: runs PHPUnit inside the dedicated test config's `cli` container (start it first).
- DB quick query (read-only): `npx wp-env run cli -- wp db query "SELECT * FROM wp_options LIMIT 5;"`
- Legacy JS dev: `cd js && npm install && npm run serve`.
- Client dev: `cd client && npm install && npm run dev` (set `WORDPRESS_URL=...` for isolated dev).
- Tool runtime: this repo defines tool versions in `mise.toml` (`php = 8.4`, `node = 25`). Prefer running PHP and other pinned tools through `mise`, for example `mise exec -- php -l path/to/file.php`, instead of assuming `php` is available on `PATH`.

## Coding Style & Naming Conventions
- Indentation: 2 spaces (see `.editorconfig`), LF line endings, max line length 120.
- PHP formatting is enforced with PHP-CS-Fixer (`.php-cs-fixer.dist.php`).
- Before completing a task, format any touched PHP files with the repo formatter. `make format` runs PHP-CS-Fixer for the whole repo; prefer the equivalent targeted command for only the files you changed, for example `mise exec -- vendor-bin/php-cs-fixer/vendor/friendsofphp/php-cs-fixer/php-cs-fixer fix path/to/file.php --config .php-cs-fixer.dist.php`.
- Use descriptive, WordPress-appropriate names for hooks and filters; keep filenames lowercase with underscores where applicable.

## Testing Guidelines
- PHPUnit is configured in `phpunit.xml.dist` and bootstraps via `tests/phpunit/bootstrap.php`.
- Integration and REST tests live under `tests/phpunit/integration/` and `tests/phpunit/rest/`.
- Run tests with `npm run wp-env:test:start` followed by `npm run test`.

## Commit & Pull Request Guidelines
- Commit messages follow a lightweight conventional style (examples: `feat: ...`, `fix: ...`, `chore: ...`, `change: ...`).
- Changelog entries belong in `readme.txt` under the `== Changelog ==` header.
- PRs should include a clear description, linked issues if applicable, and notes on how changes were tested (commands and environment).

## Configuration Tips
- Local WordPress uses `wp-env`; see `README.md` for ports and default credentials.
- For release builds, use `make build` to generate a clean `dist/` directory.
- Read-only database queries are allowed without asking for permission.
- If a required runtime is missing from `PATH`, use `mise exec -- ...` from the repository root so commands run with the versions declared in `mise.toml`.