# LibreBooking - Copilot Agent Instructions This file contains essential information for AI coding agents working on the LibreBooking repository. Following these guidelines will help you work efficiently and maintain code quality. ## Project Overview **LibreBooking** is an open-source resource scheduling and booking system written in PHP. It's a fork of Booked Scheduler that has evolved significantly since 2020. - **Primary Language**: PHP (>=8.2) - **Database**: MySQL >= 8.0 (2018) or MariaDB >= 10.6 (2021) - **Architecture**: Model-View-Presenter (MVP) pattern - **Template Engine**: Smarty (version 5.8+) - **Frontend**: Bootstrap 5, jQuery - **Main Branch**: `develop` (not `main` or `master`) - **License**: GPL-3.0 ## Repository Structure ```text /config Application configuration files /Controls Reusable page control objects /database_schema SQL scripts for database setup and upgrades /Domain Domain entities, repositories, services /Access Database abstraction layer /Events Domain events /Values Value objects /Jobs Scheduled tasks (cron jobs) /lang Translation files (30+ languages) /lib Application supporting objects /Application Application logic (admin, auth, reservations, etc.) /Common Shared utilities (dates, localization, etc.) /Database Database access and abstractions /Email Email services /external Third-party libraries (DO NOT MODIFY) /Pages Page binding and workflow logic /Presenters Application logic and page population /plugins Plugin architecture (various types) /tests PHPUnit test suite /tpl Smarty templates /tpl_c Template cache (auto-generated, not tracked) /Web User-facing pages and assets /scripts JavaScript files /css Stylesheets /WebServices REST API implementation ``` ## Development Environment Setup ### Prerequisites - PHP >= 8.2 with extensions: ctype, curl, fileinfo, json, ldap, mbstring, mysqli, openssl, pdo, pdo_mysql, tokenizer, xml - Optional PHP extensions: bcmath, gd - Composer for dependency management - MySQL >= 8.0 (2018) or MariaDB >= 10.6 (2021) for database - Git for version control ### Initial Setup 1. **Clone the repository**: ```bash git clone https://github.com/LibreBooking/librebooking.git cd librebooking ``` 2. **Install dependencies**: ```bash composer install ``` **⚠️ Known Issue - Composer Authentication Error**: If you encounter `Could not authenticate against github.com` during `composer install`, this is a known issue in certain CI/sandboxed environments. **Workarounds**: - The error typically occurs when Composer tries to download packages from GitHub without proper authentication - If in a CI environment, ensure GitHub tokens are properly configured - In some cases, packages may already be cached and installation can proceed despite the error - If the error persists and blocks progress, note this limitation and proceed with tasks that don't require vendor dependencies 3. **Configure the application**: ```bash cp config/config.dist.php config/config.php # Edit config.php with your database settings ``` 4. **Set up the database** (if needed): - Use Phing tasks: `composer build` (requires MySQL credentials) - Or manually run SQL scripts in `/database_schema/` ### Preflight Check Run the preflight checker to validate your environment: ```bash composer preflight # Or: php lib/preflight.php ``` This script checks PHP version, required extensions, permissions, and optional database connectivity. ## Code Quality Tools ### Linting **PHP Syntax Check**: ```bash ./ci/ci-phplint ``` This uses parallel processing to lint all PHP files (excluding vendor, tmp, node_modules). **PHP-CS-Fixer** (PSR-12 compliance): ```bash # Check code style (dry-run, no changes) composer phpcsfixer:lint # Fix code style issues automatically composer phpcsfixer:fix ``` Configuration: `.php-cs-fixer.dist.php` - Follows PSR-12 standards - Uses short array syntax - Enforces single quotes - Cache: `var/cache/.php-cs-fixer.cache` ### Static Analysis **PHPStan** (level 2): ```bash # Run base analysis composer phpstan # Run with stricter rules composer phpstan_next ``` Configuration files: - `phpstan.neon` - Base configuration (level 2) - `phpstan_next.neon` - Stricter analysis for progressive improvements Output format: `prettyJson` Cache directory: `var/cache/phpstan/` ### Testing **PHPUnit** (version 11.5+): ```bash # Run all tests (excludes integration tests) composer phpunit # Or: ./vendor/bin/phpunit # Run specific test suite composer phpunit -- --testsuite domain composer phpunit -- --testsuite application # Run integration tests (requires database) composer test:integration ``` Configuration: `phpunit.xml.dist` Test suites available: - `all` - All tests except integration (default) - `application` - Application layer tests - `domain` - Domain layer tests - `plugins` - Plugin tests - `presenters` - Presenter tests - `webservice` / `webservices` - API tests - `integration` - Integration tests (requires database setup) **Important**: Integration tests require a configured database. Set up config.php before running. ### Combined Testing Run both tests and linting: ```bash composer test ``` ### Documentation Generate API documentation with PHPDocumentor: ```bash # Install phive tools first composer install-tools # Generate docs (output: .phpdoc/build/) ./tools/phpdoc ``` Configuration: `phpdoc.dist.xml` ### Building Releases Build a distributable release package: ```bash composer build # Uses Phing, output: build/librebooking.zip ``` Configuration: `build.xml` ## Coding Standards and Conventions ### PHP Code Style 1. **Follow PSR-12** - The codebase strictly follows PSR-12 standards 2. **Use PHP 8.2+ features** where appropriate (enums, readonly properties, constructor property promotion, etc.) 3. **Type hints** - Use strict typing where possible 4. **Documentation** - Add PHPDoc blocks for classes and complex methods 5. **No trailing whitespace** - EditorConfig enforces this 6. **LF line endings** - Unix-style line endings (see `.editorconfig`) 7. **4-space indentation** for PHP, 2-space for YAML files 8. **Single quotes** for strings (unless interpolation is needed) 9. **Short array syntax** - Use `[]` not `array()` 10. **No magic numbers** - Use named constants, enums, or class constants instead of raw numeric literals. For example, use `CustomAttributeTypes::CHECKBOX` instead of `4`. Code reviews should flag any unexplained numeric literals as magic numbers ### Design Patterns **Model-View-Presenter (MVP)**: - **Pages** (`/Pages/*.php`) - Thin abstraction to template engine, minimal logic - **Presenters** (`/Presenters/*.php`) - Orchestrate interactions, fetch/transform data - **Domain** (`/Domain/`) - Business logic, entities, repositories **File Organization**: - Each page should have a corresponding template in `/tpl` - Each page should have a class in `/Pages` - Each page class should have a presenter in `/Presenters` - Related code grouped in directories with `namespace.php` for easy inclusion ### Naming Conventions - **Classes**: PascalCase (e.g., `ReservationService`, `UserRepository`) - **Methods**: camelCase (e.g., `getUserById`, `validateReservation`) - **Variables**: camelCase - **Constants**: UPPER_SNAKE_CASE - **Files**: Match class names (e.g., `ReservationService.php`) ### Database - Uses MySQL/MariaDB - Entity Relationship Diagram: `docs/source/ERD.svg` - Schema management via Phing tasks or manual SQL scripts - Migration scripts in `/database_schema/upgrades/` ## Git Workflow ### Branch Strategy **Important**: The main development branch is `develop`, NOT `main` or `master`. - **develop** - Active development, latest beta code - **master** - Stable releases only - Feature branches: `feature/description-of-feature` - Bugfix branches: `bugfix/issue-number-description` ### Commit Message Format Follow conventional commits format: ```text ():