Skill Doli Dev

Dolibarr Development Best Practices (Core Agent Skill)

This skill guides agents on developing, modifying, and debugging code within the Dolibarr ERP/CRM codebase while strictly adhering to professional standards, security guidelines, and the project's established architecture.

Relationship with AGENTS.md

The instructions in this file are complementary to the instructions defined in AGENTS.md.

• AGENTS.md contains the general instructions and rules for the project.
• SKILLS.md contains additional instructions specific to skills.
• Unless explicitly stated otherwise, the instructions from both files apply.
• SKILLS.md does not replace or override AGENTS.md.
• If an instruction in SKILLS.md conflicts with AGENTS.md, follow the rules defined by AGENTS.md.

Core Principles: Non-Negotiable Mandatory Rules

These principles must be followed even before reviewing specific task details. Violation of these principles results in failed suggestions.

Security & Data Integrity

1. Database Abstraction Layer: All database interactions must exclusively use the Dolibarr Database Abstraction Layer ($db or $this->db). Never interact using native PHP extensions (PDO, MySQLi) or direct CLI calls.
2. Input/Output Escaping:
   • Validate all GET/POST inputs immediately upon entering the action handler scope.
   • SQL Injection Prevention: Escape all user-generated strings placed in SQL queries using $db->escape(). For integers, use explicit casting: ((int) $var); for floats, use (float) $var.
3. Variable Safety Naming: When constructing dynamic SQL, the resulting variable holding the entire query string MUST be clearly prefixed (e.g., $sqlWhereClause, $queryParams). This pattern helps static analysis tools detect unsafe assignments.

Code Structure & Quality

1. Coding Standard: All new and modified committed code must strictly adhere to PSR-12 (enforceable by using phpcbf and phpcs).All properties and all function arguments and return value need detailed PHPDoc (e.g., array<string,array{key1?:?type,...}>).Variables expected to exist in view files require both a PHPDoc declaration and the use of '@phan-var-force'; declarations near the HEAD of the file for strict static analysis tracking.
2. Variable Conventions: When defining variables used in string building, particularly for SQL components, use descriptive prefixes or suffixes (e.g., $sql_select, $actionSuffix). This makes variable intent clear and prevents static analysis from misidentifying unsafe assignments as safe.
3. Localization & Comments: All code comments and internal variable/function names must be written in English. Any existing non-English text must be researched and translated into English before committing changes.
4. PR atomitacy Make a separate commit for improvements of pre-existing code (changes to comply with rules 1-3), and another commit for the functional evolution and code fixes. Do not apply rules 1-3 to existing code in backports (i.e., non-functional changes not applied to a (fork of) the develop branch.

Workflow & Architecture

1. PHP version: 7.2+
2. Action/View Separation: Always clearly separate page action logic (executed on POST) from pure rendering (the HTML view).

Workflow and Tasks Guidance

This section guides the agent through common development tasks.

Code Investigation / Searching / Database analysis

• Use pre-commit to run tools (php-cbf, php-cs, shellcheck, php-lint - example:pre-commit run php-cbf --files RELATIVEFILEPATH) when the git hook is installed as local direct installations differ across systems.
• IMPORTANT: Always use git grep instead of find for searching the codebase. find searches all directories including .git which is very slow. Use:

  git grep -n "pattern" -- "*.php"
  git grep -n "function_name" htdocs/core/lib/ -- "*.php"

• When investigating a feature or bug: Start with git grep -n across targeted directories for efficient, rapid code searches. Using $db->prefix() consistently is the first step in tracing data flows.
• Dependency Check: Before modifying a file, search both htdocs/core/lib/ and htdocs/core/class/ to ensure similar methods or utilities are not already in use. Always check if the concern object extends CommonObject, favouring its built-in methods (fetch(), create(), update(), etc.).
• Dolibarr Function & Method Arguments: Check the function signature before implementing a call - the parameter order is not consistent across dolibarr functions that have the same name.
• When you need to access the database for analysis, use php, example:

  php <<'EOPHP'
  <?php
  error_reporting(E_ALL); ini_set('display_errors', 1);
  require_once 'htdocs/master.inc.php'; // *NOT* main.inc.php
  global $db;
  $result = $db->query('SELECT * FROM ' . $db->prefix() . 'actioncomm');
  print_r($result);
  EOPHP