diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..87643113d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,225 @@ +# AGENTS.md + +## Project Overview + +QloApps is an open-source hotel reservation and property management platform. It enables hotels to manage rooms, bookings, guests, and payments through a web-based system. + +## Purpose of this File + +This document provides guidance for AI coding agents contributing to the QloApps project. It defines conventions, safety rules, and workflows to ensure consistent and secure code generation. + +## Technology Stack + +- **Language:** PHP 8.1–8.4 (backend), Smarty 3.x (templates), JavaScript/jQuery (frontend) +- **Database:** MySQL 5.7, 8.0+; MariaDB 10.5, 10.6, 10.11, 11.0, 11.2, 11.4 +- **Architecture:** MVC with hook-based module system +- **License:** OSL-3.0 (core), AFL-3.0 (modules) +- **Required PHP Extensions:** PDO_MySQL, cURL, OpenSSL, SOAP, GD, SimpleXML, DOM, Zip, Phar + +## Environment Setup + +Install dependencies: +```bash +composer install +``` + +Clear caches: +```bash +rm -rf cache/smarty/compile/* cache/smarty/cache/* +rm -f cache/class_index.php +``` + +Clear class cache after adding or modifying overrides. + +## Project Structure + +``` +. +├── classes/ # Core models extending ObjectModel +├── controllers/ # Front and admin controllers +│ ├── admin/ +│ └── front/ +├── modules/ # Feature modules with isolated functionality +├── override/ # Core class and controller overrides +├── themes/ # Smarty templates (.tpl files) +├── config/ # Configuration files (settings.inc.php contains secrets) +├── cache/ # Generated cache files +├── tests/ # PHPUnit test suite +``` + +**QloApps Agent Skills:** Install reusable development skills using: +```bash +npx skills add Qloapps/agent-skills +``` +Available skills: module-development, payment-module-development, stats-module-development. Check installed skills before implementing new functionality. + +## Architecture Overview + +**MVC Pattern** +- Models: classes/ extending ObjectModel +- Controllers: FrontController or AdminController +- Views: Smarty templates (.tpl) + +**Modules** +- Located in modules// +- Provide isolated functionality +- Integrate using hooks + +**Overrides** +- Located in override/ +- Extend core classes using the Core suffix +- Clear class cache after creating overrides + +**Context** +- Access runtime objects using Context::getContext() + +## Core vs Module Development Rules + +**When working on a module:** +1. Never modify core files directly +2. Use **hooks** to integrate module functionality into core features +3. If no suitable hook exists, create a **custom hook** — but only if the hook placement is generic and useful for other modules too +4. Use **overrides** only as a last resort — overrides can conflict with other module override files and require manual resolution + +**When working on a core feature:** +- Make changes directly in core files +- Do not use hooks or overrides for core-to-core changes + +## Coding Conventions + +**Classes:** PascalCase — `HotelBookingData` +**Methods:** camelCase — `getBookingDetails()` +**Variables:** camelCase — `$hotelId` +**Constants:** UPPER_SNAKE_CASE — `BOOKING_STATUS_CONFIRMED` +**Database Tables:** _DB_PREFIX_ + lowercase_snake — `qlo_hotel_booking` +**Config Keys:** MODULENAME_SETTING — `HOTELRESERVATION_ENABLED` +**Files:** One class per file, filename matches class name +**Templates:** lowercase-hyphens.tpl — `booking-form.tpl` + +Add PHPDoc blocks to all classes and methods. + +## Translation + +Never hardcode user-facing English strings — always wrap them in the appropriate translation method. + +| Context | Method | +|---------|--------| +| Module main file | `$this->l('string')` | +| Module admin controller | `$this->l('string')` | +| Module front controller | `$this->module->l('string', 'controllerName')` | +| Module classes | `$objModule->l('string', 'ClassName')` | +| Core admin controller | `$this->l('string')` | +| Core front controller | `Tools::displayError('string')` | +| Smarty template (core) | `{l s='string'}` | +| Smarty template (module) | `{l s='string' mod='modulename'}` | + +## Multi-language + +- Always include `id_lang` in queries that return translatable content +- Use `Context::getContext()->language->id` for the current language + +## Module Development Guidelines + +**Module Location:** modules// + +**Required Files:** +- .php — Main class extending Module +- config.xml — Module metadata + +**Optional Directories:** +- classes/ — Module-specific models +- controllers/ — Module controllers +- views/templates/ — Smarty templates +- upgrade/ — Version migration scripts + +**Hook Integration:** +- Register hooks in install() method +- Unregister hooks in uninstall() method +- Keep hook handlers lightweight + +**Configuration:** +- Store settings using Configuration::updateValue() +- Retrieve settings using Configuration::get() +- Prefix config keys with module name + +## Database Rules + +**Table Prefix:** Always use _DB_PREFIX_ constant instead of hardcoding the table prefix + +**Escaping:** +- Strings: pSQL($value) +- Integers: (int)$value +- Table/column names: bqSQL($name) + +**Preferred Access:** Use ObjectModel for CRUD operations instead of raw SQL queries + +**Prohibited:** Never concatenate raw user input into SQL queries. + +## Security Guidelines + +**Input Handling** +- Use Tools::getValue() for request parameters +- Cast numeric values to (int) +- Escape strings using pSQL() +- Validate input using Validate class methods + +**Output Escaping** +- Use Tools::safeOutput() in PHP +- Use Smarty escape modifiers in templates + +**Sensitive Data** +- Never expose config/settings.inc.php +- Never commit API keys, passwords, or tokens + +**Authorization** +- Verify permissions before performing admin operations + +## Testing + +Testing infrastructure is being configured. Check tests/ directory for available tests before running. + +## AI Agent Workflow + +1. Check installed agent skills before implementing new functionality +2. Search codebase for similar implementations before creating new code +3. Extend existing classes rather than duplicating functionality +4. Follow patterns established in surrounding code +5. Reuse existing utilities: Tools, Validate, Db, Configuration classes +6. Prioritize consistency with existing codebase over new approaches + +After making changes: +- Clear caches if modifying templates or overrides +- Add PHPDoc to new methods + +## Safety Rules + +**Agents must not:** +- Delete files unless explicitly instructed +- Run git commands automatically +- Modify composer.json without approval +- Modify config/settings.inc.php +- Execute DROP, TRUNCATE, or destructive SQL +- Modify core files directly when working on a module (use hooks or override system) + +**Agents must:** +- Use pSQL() for strings and (int) for IDs in SQL +- Use Tools::getValue() for request parameters +- Escape all output +- Check installed agent skills before implementing new functionality +- Follow project naming conventions +- Validate inputs before processing + +**Agents should ask before:** +- Deleting any files +- Running git commands +- Changing dependencies +- Modifying database schema +- Altering payment or booking logic + +--- + +**Resources:** +- Documentation: https://docs.qloapps.com +- Forum: https://forums.qloapps.com +- GitHub: https://github.com/Qloapps/QloApps +- Security Issues: support@qloapps.com diff --git a/admin/themes/default/template/controllers/modules/configure.tpl b/admin/themes/default/template/controllers/modules/configure.tpl index 24b6560a0..3d3f0d1b9 100644 --- a/admin/themes/default/template/controllers/modules/configure.tpl +++ b/admin/themes/default/template/controllers/modules/configure.tpl @@ -60,7 +60,7 @@
  • -
    {l s='Back'}
    + {l s='Back'}