132 lines
4.8 KiB
Markdown
132 lines
4.8 KiB
Markdown
# Kimai Core Agent Guide
|
|
|
|
Use this file when working in the Kimai core repository.
|
|
|
|
## Stack
|
|
|
|
- Kimai is a professional open source time-tracking application
|
|
- PHP versions: 8.2, 8.3, 8.4, 8.5
|
|
- Main framework: Symfony 6.4
|
|
- Core libraries: Doctrine, Twig
|
|
- API libraries: FOSRestBundle, NelmioApiDocBundle
|
|
- Frontend: Bootstrap with Tabler.io
|
|
- Frontend build: Webpack Encore via `symfony/webpack-encore`
|
|
- Package managers: Composer and Yarn
|
|
- Tests: PHPUnit
|
|
- Code styles: PhpCsFixer
|
|
- Static analysis: PHPStan
|
|
- Project information in README.md
|
|
- Translations managed with Weblate online service
|
|
|
|
## Scope
|
|
|
|
- This guide applies to Kimai core only
|
|
- Work in `var/plugins/` is out of scope unless explicitly requested
|
|
- Each subdirectory in `var/plugins/` is a separate Kimai plugin and its own Git repository
|
|
- In fresh installations, `var/data/` and `var/plugins/` are empty
|
|
|
|
## Repository Map
|
|
|
|
- `.docker/` Docker image build files
|
|
- `.github/` GitHub Actions and repository metadata
|
|
- `assets/` JavaScript and Sass sources
|
|
- `bin/` executable entry points, especially `bin/console`
|
|
- `config/` Symfony configuration and bundle setup
|
|
- `migrations/` Doctrine migrations for installs and upgrades
|
|
- `public/` web root with `index.php`
|
|
- `public/build/` generated frontend assets
|
|
- `public/bundles/` generated public bundle assets
|
|
- `src/` core PHP source code
|
|
- `src/API/` the JSON API
|
|
- `templates/` Twig templates
|
|
- `tests/` PHPUnit tests
|
|
- `translations/` XLIFF files named `<component>.<locale>.xlf`
|
|
- `var/` runtime storage and generated content
|
|
- `vendor/` Composer dependencies
|
|
|
|
## Never Touch
|
|
|
|
- Do not read from or write to `var/cache/`, it is Symfony-managed internal state
|
|
- Do not modify `vendor/`
|
|
- Do not modify `var/data/`
|
|
- Do not modify `var/log/`
|
|
- Do not modify `public/build/`, generated frontend assets
|
|
- Do not modify `public/bundles/`, frintend assets from plugins
|
|
- Do not modify plugins in `var/plugins/` unless explicitly asked
|
|
|
|
## Agent Workflow
|
|
|
|
- Read the surrounding code before editing
|
|
- Follow existing local patterns before introducing new abstractions
|
|
- Keep changes small and targeted
|
|
- Keep code, identifiers, comments, branches, commit text, and documentation in English
|
|
- Ask before touching security-sensitive areas such as authentication, authorization, or permissions
|
|
|
|
## Architecture Rules
|
|
|
|
- Do not introduce new composer packages without prior discussion
|
|
- Prefer services over static helper classes
|
|
- Keep business logic out of controllers
|
|
- Use Twig templates for HTML output
|
|
- Preserve backward compatibility for upgrades
|
|
|
|
## Database Rules
|
|
|
|
- Doctrine entity changes affecting the schema require a migration file
|
|
- Generate migration with `bin/console doctrine:migrations:diff`
|
|
- Prefer `Doctrine\DBAL\Schema` in migrations over inline SQL
|
|
|
|
## Frontend and Translation Rules
|
|
|
|
- Build on existing Bootstrap and Tabler patterns
|
|
- Do not introduce new frontend frameworks without prior discussion
|
|
- Keep English translations updated whenever translations change
|
|
- English is the Weblate default language and Kimai fallback language
|
|
- Use Twig `|trans` for user-facing text instead of hardcoded strings
|
|
- Use FontAwesome 6 names for icons
|
|
|
|
## Testing Rules
|
|
|
|
- Every PHP class in `src/`, except interfaces, should have a matching PHPUnit test
|
|
- Map `src/<directory>/<ClassName>.php` to `tests/<directory>/<ClassName>Test.php`
|
|
- Cover all public methods with tests
|
|
- Follow the existing test style in the target area such as controller, event, voter, or service tests
|
|
|
|
## Validation
|
|
|
|
- Always run `./php-cs-fixer.sh core`
|
|
- Run `./phpstan.sh core` for changes in `src/`
|
|
- Run `./phpstan.sh test` for changes in `tests/`
|
|
- For focused checks, run `vendor/bin/phpunit tests/<directory>/<TestClassName>.php`
|
|
- Use `composer tests-unit` for broader validation without expensive end-to-end coverage
|
|
- Use `composer tests` when the change justifies running the full suite
|
|
- If tests fail, remove stale cache with `rm -r ./var/cache/test/` to cause a rebuild
|
|
|
|
## Git Rules
|
|
|
|
- Avoid working directly on `main`
|
|
- Small fixes should target the active `release-x.y.z` branch
|
|
- Larger changes should go to descriptive `snake_case` feature branches
|
|
- Agents may create branches when needed
|
|
- Agents must not create commits unless explicitly asked
|
|
- Commits are normally created by the maintainer
|
|
|
|
## Coding Conventions
|
|
|
|
- Use strict comparisons such as `===` and `!==`
|
|
- Prefer constructor promotion for dependency injection
|
|
- Use PHP attributes for routing, mapping, and configuration where established
|
|
- Use `camelCase` for variables and methods
|
|
- Use 4-space indentation
|
|
- Use single quotes for strings in PHP, JavaScript, and CSS unless the local code style requires otherwise
|
|
- Use modern HTML5, Twig, and ES6+ syntax
|
|
|
|
## Security Focus
|
|
|
|
- Prevent XSS
|
|
- Prevent CSRF issues
|
|
- Prevent SQL or command injection patterns
|
|
- Prevent auth bypasses
|
|
- Prevent open redirects
|
|
- Apply Rate-Limiting in authentication flows
|