AGENTS.md

1# AGENTS.md
2 
3## Project Overview
4 
5QloApps 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.
6 
7## Purpose of this File
8 
9This 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.
10 
11## Technology Stack
12 
13- **Language:** PHP 8.1–8.4 (backend), Smarty 3.x (templates), JavaScript/jQuery (frontend)
14- **Database:** MySQL 5.7, 8.0+; MariaDB 10.5, 10.6, 10.11, 11.0, 11.2, 11.4
15- **Architecture:** MVC with hook-based module system
16- **License:** OSL-3.0 (core), AFL-3.0 (modules)
17- **Required PHP Extensions:** PDO_MySQL, cURL, OpenSSL, SOAP, GD, SimpleXML, DOM, Zip, Phar
18 
19## Environment Setup
20 
21Install dependencies:
22```bash
23composer install
24```
25 
26Clear caches:
27```bash
28rm -rf cache/smarty/compile/* cache/smarty/cache/*
29rm -f cache/class_index.php
30```
31 
32Clear class cache after adding or modifying overrides.
33 
34## Project Structure
35 
36```
37.
38├── classes/              # Core models extending ObjectModel
39├── controllers/          # Front and admin controllers
40│   ├── admin/
41│   └── front/
42├── modules/              # Feature modules with isolated functionality
43├── override/             # Core class and controller overrides
44├── themes/               # Smarty templates (.tpl files)
45├── config/               # Configuration files (settings.inc.php contains secrets)
46├── cache/                # Generated cache files
47├── tests/                # PHPUnit test suite
48```
49 
50**QloApps Agent Skills:** Install reusable development skills using:
51```bash
52npx skills add Qloapps/agent-skills
53```
54Available skills: module-development, payment-module-development, stats-module-development. Check installed skills before implementing new functionality.
55 
56## Architecture Overview
57 
58**MVC Pattern**
59- Models: classes/ extending ObjectModel
60- Controllers: FrontController or AdminController
61- Views: Smarty templates (.tpl)
62 
63**Modules**
64- Located in modules/<modulename>/
65- Provide isolated functionality
66- Integrate using hooks
67 
68**Overrides**
69- Located in override/
70- Extend core classes using the Core suffix
71- Clear class cache after creating overrides
72 
73**Context**
74- Access runtime objects using Context::getContext()
75 
76## Core vs Module Development Rules
77 
78**When working on a module:**
791. Never modify core files directly
802. Use **hooks** to integrate module functionality into core features
813. If no suitable hook exists, create a **custom hook** — but only if the hook placement is generic and useful for other modules too
824. Use **overrides** only as a last resort — overrides can conflict with other module override files and require manual resolution
83 
84**When working on a core feature:**
85- Make changes directly in core files
86- Do not use hooks or overrides for core-to-core changes
87 
88## Coding Conventions
89 
90**Classes:** PascalCase — `HotelBookingData`
91**Methods:** camelCase — `getBookingDetails()`
92**Variables:** camelCase — `$hotelId`
93**Constants:** UPPER_SNAKE_CASE — `BOOKING_STATUS_CONFIRMED`
94**Database Tables:** _DB_PREFIX_ + lowercase_snake — `qlo_hotel_booking`
95**Config Keys:** MODULENAME_SETTING — `HOTELRESERVATION_ENABLED`
96**Files:** One class per file, filename matches class name
97**Templates:** lowercase-hyphens.tpl — `booking-form.tpl`
98 
99Add PHPDoc blocks to all classes and methods.
100 
101## Translation
102 
103Never hardcode user-facing English strings — always wrap them in the appropriate translation method.
104 
105| Context | Method |
106|---------|--------|
107| Module main file | `$this->l('string')` |
108| Module admin controller | `$this->l('string')` |
109| Module front controller | `$this->module->l('string', 'controllerName')` |
110| Module classes | `$objModule->l('string', 'ClassName')` |
111| Core admin controller | `$this->l('string')` |
112| Core front controller | `Tools::displayError('string')` |
113| Smarty template (core) | `{l s='string'}` |
114| Smarty template (module) | `{l s='string' mod='modulename'}` |
115 
116## Multi-language
117 
118- Always include `id_lang` in queries that return translatable content
119- Use `Context::getContext()->language->id` for the current language
120 
121## Module Development Guidelines
122 
123**Module Location:** modules/<modulename>/
124 
125**Required Files:**
126- <modulename>.php — Main class extending Module
127- config.xml — Module metadata
128 
129**Optional Directories:**
130- classes/ — Module-specific models
131- controllers/ — Module controllers
132- views/templates/ — Smarty templates
133- upgrade/ — Version migration scripts
134 
135**Hook Integration:**
136- Register hooks in install() method
137- Unregister hooks in uninstall() method
138- Keep hook handlers lightweight
139 
140**Configuration:**
141- Store settings using Configuration::updateValue()
142- Retrieve settings using Configuration::get()
143- Prefix config keys with module name
144 
145## Database Rules
146 
147**Table Prefix:** Always use _DB_PREFIX_ constant instead of hardcoding the table prefix
148 
149**Escaping:**
150- Strings: pSQL($value)
151- Integers: (int)$value
152- Table/column names: bqSQL($name)
153 
154**Preferred Access:** Use ObjectModel for CRUD operations instead of raw SQL queries
155 
156**Prohibited:** Never concatenate raw user input into SQL queries.
157 
158## Security Guidelines
159 
160**Input Handling**
161- Use Tools::getValue() for request parameters
162- Cast numeric values to (int)
163- Escape strings using pSQL()
164- Validate input using Validate class methods
165 
166**Output Escaping**
167- Use Tools::safeOutput() in PHP
168- Use Smarty escape modifiers in templates
169 
170**Sensitive Data**
171- Never expose config/settings.inc.php
172- Never commit API keys, passwords, or tokens
173 
174**Authorization**
175- Verify permissions before performing admin operations
176 
177## Testing
178 
179Testing infrastructure is being configured. Check tests/ directory for available tests before running.
180 
181## AI Agent Workflow
182 
1831. Check installed agent skills before implementing new functionality
1842. Search codebase for similar implementations before creating new code
1853. Extend existing classes rather than duplicating functionality
1864. Follow patterns established in surrounding code
1875. Reuse existing utilities: Tools, Validate, Db, Configuration classes
1886. Prioritize consistency with existing codebase over new approaches
189 
190After making changes:
191- Clear caches if modifying templates or overrides
192- Add PHPDoc to new methods
193 
194## Safety Rules
195 
196**Agents must not:**
197- Delete files unless explicitly instructed
198- Run git commands automatically
199- Modify composer.json without approval
200- Modify config/settings.inc.php
201- Execute DROP, TRUNCATE, or destructive SQL
202- Modify core files directly when working on a module (use hooks or override system)
203 
204**Agents must:**
205- Use pSQL() for strings and (int) for IDs in SQL
206- Use Tools::getValue() for request parameters
207- Escape all output
208- Check installed agent skills before implementing new functionality
209- Follow project naming conventions
210- Validate inputs before processing
211 
212**Agents should ask before:**
213- Deleting any files
214- Running git commands
215- Changing dependencies
216- Modifying database schema
217- Altering payment or booking logic
218 
219---
220 
221**Resources:**
222- Documentation: https://docs.qloapps.com
223- Forum: https://forums.qloapps.com
224- GitHub: https://github.com/Qloapps/QloApps
225- Security Issues: support@qloapps.com
226