dolibarr/.agents/AGENTS.md

# AGENTS.md (English Version)

## 🎯 Objective

This project contains the full sources of the Dolibarr ERP and CRM application.
Every modification must respect:
- Dolibarr's modular architecture
- Compatibility with upstream updates
- Modern PHP best practices

---

## ⚠️ Critical Rules (DO NOT VIOLATE)

- ❌ Do not break compatibility of PHP functions and methods
- ❌ Do not introduce external dependencies without validation
- ❌ Separate page actions in the `/* Actions */` section of the PHP code and the rendering part in the `/* Views */` section
- ❌ Never commit directly to `develop` or version branch matching regex `^\d+\.\d+$`
- ❌ Never use PHP native curl functions to call a GET or POST URL, but use instead the Dolibarr function getURLContent()
- ✅ Use Dolibarr hooks whenever possible
- ✅ Respect existing naming conventions
- ✅ All database table names must use the `llx_` prefix

---

## 📁 Expected Architecture

Module structure:
`htdocs/mymodule`
├── `core/`
├── `class/`
├── `lib/`
├── `sql/`
├── `tpl/`
└── `admin/`

A template of a module directory content can be found in the `htdocs/modulebuilder/template` folder of this project.

---

## 🔍 Before Coding

Before writing any code, the agent **must**:
- Search for existing similar functions in `htdocs/core/lib/` and `htdocs/core/class/`
- Check if the concerned object class extends `CommonObject` and use its built-in methods (fetch, create, update, delete, etc.)
- Review the module's `modMyModule.class.php` for declared permissions and constants
- Run a search to ensure no equivalent function already exists in the codebase

---

## 🧠 PHP Best Practices

- PHP >= 7.3 (minimum support); PHP 8.1+ recommended for new external modules
- ⚠️ When writing a **bug fix**, always target the lowest compatible PHP version
  of the branch being patched — do not use PHP 8.x syntax on a fix targeting v19 or v20
- Respect PSR-12, but **indentations must use Tabs, not Spaces**
- Write short, readable, and testable functions
- Avoid side effects
- Prefer typed properties and return types when PHP version allows

---

## 🗄️ Database

- Use Dolibarr database functions exclusively — never use PDO or MySQLi directly
    - In pages: use global `$db`
    - In classes: use `$this->db`
- ✅ SQL forged by PHP must escaped fields with `db->escape()`, `db->sanitize()`, or by casting values to `(int)` or `(float)`
- ✅ Always use `$db->query()` followed by `$db->fetch_object()` or `$db->fetch_array()` to retrieve results
- ✅ SQL scripts for table and index creation must be placed in `htdocs/install/mysql/tables/` (see existing files for examples)
- ❌ Never run SQL queries inside loops (avoid N+1 problem — use JOINs or batch queries instead)
- ✅ Always use `LIMIT` on list queries for performance

---

## 🔌 Hooks & Extensions

- Prioritize hooks over direct code overrides
- Before creating a new hook, verify it does not already exist:
  ```
  grep -r "executeHooks" htdocs/ | grep 'hookName'
  ```
- Call hooks using the standard pattern:
  ```php
  $hookmanager->executeHooks('actionName', $parameters, $object, $action);
  ```
- Name hooks clearly and descriptively (e.g., `formObjectOptions`, `addMoreActionsButtons`)

---

## 🌍 Internationalisation

- Never hardcode user-facing strings — always use `$langs->trans('Key')`
- Language files must be placed in `mymodule/langs/en_US/` (and other locales as needed)
- All code comments and variables or functions names must be in English.
- Language key names must use PascalCase (e.g., `MyModuleLabel`, not `monLibelléModule`)
- Load the language file at the top of the page: `$langs->load('mymodule@mymodule')`

---

## 🧪 Testing & Validation

Before any modification, verify:
- Creation / edition / deletion workflows
- User rights enforcement (`$user->hasRights("module", "permission")` or `$user->hasRights("module", "objectname", "permission")`)
- Multi-entity compatibility (add ` AND entity IN ('.getDolEntity("tablename").')`)

If possible:
- If doing an external module, add a PHPUnit test file in `yourmoduledir/test/phpunit/`
- If modifying the Dolibarr code project, add a PHPUnit test file into `test/phpunit/` and add the entry into file `test/phpunit/AllTests.php`.


---

## 🖥️ UI / UX

- Respect Dolibarr UI — no unsolicited redesigns
- Reuse existing components (buttons, forms, tables) from `htdocs/core/tpl/`
- ❌ No overly complex inline JS
- ✅ Place JavaScript in separate files under `mymodule/js/`

---

## 🔒 Security

- Always validate user inputs (`GET`, `POST`) via `GETPOST()` with a type parameter
- Prevent SQL injection (use `db->escape()` or cast into `(int)` or `(float)`)
- Prevent XSS injection by escaping HTML output (use `dolPrintHTML()`, `dolPrintHTMLForAttribute()`)
- Always include Dolibarr CSRF tokens in POST forms: `<input type="hidden" name="token" value="'.newToken().'">`

---

## ⚡ Performance

- Avoid SQL queries inside loops (N+1 problem)
- Use JOINs or batch queries instead of multiple sequential queries
- Apply `LIMIT` and proper indexes on list queries
- Cache repeated calls to `getDolGlobalString()` or `$conf->global->` in local variables

---

## 🧾 Logs & Debug

- Use `dol_syslog()` for all logging (with appropriate log level: `LOG_DEBUG`, `LOG_WARNING`, `LOG_ERR`)
- Do not leave `var_dump()`, `print_r()`, or `die()` in committed code
- Use Dolibarr's `setEventMessages()` to display user-facing messages

---

## 🚀 Git Workflow

- Branch strategy:
    - One branch per major version (bug fixes only)
    - `develop` branch for both fixes and new features
- ❌ Never commit directly to `main` or `develop` without a reviewed PR
- Commit message format: `TYPE: #issueNumber Short description`
    - Types: `NEW`, `FIX` or `CLOSE`
    - Example: `FIX: #1234 Correct VAT calculation on credit notes`
- Update the `ChangeLog` file with a summary of significant changes
- When fixing a bug, apply the patch on the **oldest affected branch first**,
  then cherry-pick forward to newer branches and `develop`
- Do not introduce new syntax or features unavailable in the branch's minimum PHP version

---

## 🧩 What the Agent MUST Do

- Read this file before any modification
- Check if an equivalent function already exists before writing new code
- Minimize the impact of changes
- Propose modular modifications that do not affect unrelated features

---

## ❗ What the Agent MUST NOT Do

- Perform massive refactoring without an explicit request
- Change the global architecture of existing modules
- Delete code without justification and a comment explaining why
- Add external dependencies (Composer packages, JS libraries) without prior validation
- Modify the `ChangeLog` file (this file will be updated by the maintainer during the release process)

---

## 💡 Key Principle

👉 Always prioritize:
**extension > modification**

---

## 📌 In Case of Doubt

- Keep it simple
- Be conservative
- Ask for confirmation before any critical or irreversible change