Skip to content

AGENTS.md

Latest commit

 

History

History
225 lines (169 loc) · 7.19 KB

AGENTS.md

File metadata and controls

225 lines (169 loc) · 7.19 KB

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:

composer install

Clear caches:

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:

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: