<?php
/**
 * Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
 *
 * SPDX-License-Identifier: GPL-3.0-or-later
 *
 * FILE INFORMATION
 * DEFGROUP: MokoPlatform.Stubs
 * INGROUP: MokoPlatform
 * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokocli
 * PATH: /templates/stubs/dolibarr.php
 * BRIEF: PHPStan stub declarations for Dolibarr core classes
 *
 * These are declaration-only stubs (no implementations) that let PHPStan resolve
 * Dolibarr types in module source code without requiring a full Dolibarr installation.
 * Only the most commonly used classes, properties, and methods are declared.
 */

// ── Dolibarr globals (set at runtime by main.inc.php) ─────────────────────────
/** @global DoliDB      $db */
/** @global Conf        $conf */
/** @global User        $user */
/** @global Translate   $langs */
/** @global HookManager $hookmanager */

// ── Core constants ─────────────────────────────────────────────────────────────
if (!defined('DOL_DOCUMENT_ROOT')) {
    define('DOL_DOCUMENT_ROOT', '');
}
if (!defined('DOL_URL_ROOT')) {
    define('DOL_URL_ROOT', '');
}
if (!defined('MAIN_DB_PREFIX')) {
    define('MAIN_DB_PREFIX', 'llx_');
}

// ── Class stubs ────────────────────────────────────────────────────────────────

class DoliDB
{
    /** @param array<mixed> $params */
    public function query(string $sql, bool $usesavepoint = false, string $type = 'auto', int $result_mode = 0): mixed {}
    public function num_rows(mixed $resultset): int {}
    /** @return array<string,mixed>|false */
    public function fetch_array(mixed $resultset): array|false {}
    /** @return object|false */
    public function fetch_object(mixed $resultset): object|false {}
    public function free(mixed $resultset): bool {}
    public function escape(string $stringtoescape): string {}
    public function escapeLike(string $stringtoescape): string {}
    public function lasterror(): string {}
    public function lasterrno(): string|int {}
    public function iferror(mixed $resql): bool {}
    public function last_insert_id(string $tab, string $fieldid = 'rowid'): int {}
    public function begin(): void {}
    public function commit(string $log = ''): int {}
    public function rollback(string $log = ''): int {}
}

class Conf
{
    public object $global;
    public object $db;
    public object $file;
    /** @var array<string,object> */
    public array $modules = [];
    public int $entity = 1;
    public string $currency = 'USD';
    public string $format_date_short = '%d/%m/%Y';
    public string $format_date_text = '%d %B %Y';
}

class User extends CommonObject
{
    public string $login = '';
    public string $pass = '';
    public string $email = '';
    public string $firstname = '';
    public string $lastname = '';
    public int $admin = 0;
    /** @var array<string,array<string,int>> */
    public array $rights = [];

    public function getRights(string $module): object {}
    public function hasRight(string $module, string $perms, string $subperms = ''): int {}
    public function isInGroup(int|string $group): bool {}
}

class Translate
{
    /** @param array<mixed> $param */
    public function trans(string $key, ...$param): string {}
    public function transnoentities(string $key, string ...$param): string {}
    public function transnoentitiesnoconv(string $key, string ...$param): string {}
    public function load(string $domain): int {}
    public function loadLangs(array $domains): int {}
    public string $defaultlang = 'en_US';
    public string $charset_output = 'UTF-8';
}

class HookManager
{
    /** @param array<mixed> $parameters */
    public function initHooks(array $contextarray): void {}
    /** @param array<mixed> $parameters */
    public function executeHooks(string $method, array $parameters = [], object &$object = null, string &$action = ''): int {}
    public string $resPrint = '';
    public int $resArray = 0;
}

class CommonObject
{
    public ?DoliDB $db = null;
    public string $error = '';
    /** @var string[] */
    public array $errors = [];
    public int $id = 0;
    public string $ref = '';
    public string $element = '';
    public string $table_element = '';
    public string $module = '';
    public string $picto = '';
    public int $ismultientitymanaged = 0;
    public int $isextrafieldmanaged = 0;
    /** @var array<string,mixed> */
    public array $array_options = [];
    public int $status = 0;
    public string $statut = '';

    public function __construct(DoliDB $db) {}
    public function fetch(int $id, string $ref = null): int {}
    /** @return array<int,static>|int */
    public function fetchAll(string $sortorder = '', string $sortfield = '', int $limit = 0, int $offset = 0): array|int {}
    public function create(User $user, bool $notrigger = false): int {}
    public function update(User $user, bool $notrigger = false): int {}
    public function delete(User $user, bool $notrigger = false): int {}
    public function call_trigger(string $triggerName, User $user): int {}
    public function setStatut(int $status, int $elementId = null, string $elementpath = '', string $trigkey = '', string $fieldstatus = 'fk_statut'): int {}
    public function getNomUrl(int $withpicto = 0, string $option = '', int $notooltip = 0, string $morecss = '', int $save_lastsearch_value = -1): string {}
    public function getLibStatut(int $mode = 0): string {}
    public function getLabelStatus(int $mode = 0): string {}
    public function initAsSpecimen(): int {}
    public function insertExtraFields(string $trigger = '', User $userused = null): int {}
    public function updateExtraField(string $key, string $trigger = '', User $userused = null): int {}
    public function deleteExtraFields(): int {}
    public function info(int $id): int {}
    public function isObjectUsed(int $id = 0, int $entity = 0): int {}
    public function load_previous_next_ref(string $filter, string $fieldid, int $nodbprefix = 0): int {}
    public function setError(string $msg): void {}
    /** @return array<string,mixed>|int */
    public function fetchObjectLinked(int $sourceid = null, string $sourcetype = '', int $targetid = null, string $targettype = '', string $clause = 'OR', int $alsolinkedto = 0, string $orderby = ''): array|int {}
    public function add_object_linked(string $origin = null, int $origin_id = null, User $f_user = null, int $notrigger = 0): int {}
    /** @return int[] */
    public function getIdContact(string $source, string $code, int $status = 0): array {}
    /** @param int[]|string $categories */
    public function setCategories(array|string $categories, string $type = ''): void {}
}

class CommonObjectLine
{
    public int $id = 0;
    public int $fk_object = 0;
    public float $qty = 0.0;
    public float $price = 0.0;
    public string $label = '';
    public string $description = '';
    public int $rang = 0;
    public float $total_ht = 0.0;
    public float $total_tva = 0.0;
    public float $total_ttc = 0.0;
}

// ── Common utility functions ────────────────────────────────────────────────────

/** @param array<mixed> $object */
function dol_syslog(string $message, int $level = LOG_DEBUG, int $ident = 0, string $suffixinfilename = '', string $restricttologhandler = '', mixed $logcontext = null): void {}
function dol_print_error(DoliDB $db = null, string $error = '', array $errors = null): void {}
function dol_now(string $mode = 'auto'): int {}
function dol_mktime(int $hour, int $minute, int $second, int $month, int $day, int $year, mixed $gm = false, int $check = 1): int {}
function dol_print_date(int $time, string $format = '', mixed $tzoutput = 'auto', Translate $outputlangs = null, bool $encodetooutput = false): string {}
function price(float $amount, int $form = 0, Translate $outlangs = null, int $trunc = 1, int $rounding = -1, int $forcerounding = -1, string $currency_code = ''): string {}
function img_picto(string $titlealt, string $picto, string $moreatt = '', bool $pictoisfullpath = false, int $srconly = 0, int $notitle = 0, string $alt = '', string $morecss = '', string $marginleftonlyshort = null): string {}
function dol_escape_htmltag(string $stringtoescape, int $keepb = 0, int $keepn = 0, string $noescapetags = '', int $escapeonlyhtmltags = 0, int $cleanalsojavascript = 0): string {}
function dol_sanitizeFileName(string $str, string $newstr = '_', int $unaccent = 1): string {}
function newToken(): string {}
function checkToken(): bool {}
function currentToken(): string {}
function dol_get_fiche_head(array $links, string $active = '', string $title = '', int $notab = 0, string $picto = '', int $pictoisfullpath = 0, string $morehtmlright = '', string $morecss = '', int $limittoshow = 0, string $moretabssuffix = ''): string {}
function dol_get_fiche_end(int $notab = 0): string {}
function dol_banner_tab(CommonObject $object, string $paramid, string $morehtml = '', int $shownav = 1, string $fieldid = 'rowid', string $fieldref = 'ref', string $morehtmlref = '', string $moreparam = '', int $nodbprefix = 0, string $morehtmlleft = '', string $moredivright = '', int $morehtmlstatus = 0, string $onlybanner = 0): void {}
function load_fiche_titre(string $titre, string $morehtmlright = '', string $picto = 'generic', int $pictoisfullpath = 0, string $id = '', string $morecssontable = '', string $morehtmlcenter = ''): string {}
function print_fiche_titre(string $titre, string $morehtmlright = '', string $picto = 'generic', int $pictoisfullpath = 0, string $id = ''): void {}
function llxHeader(string $head = '', string $title = '', string $help_url = '', string $target = '', int $disablejs = 0, int $disablehead = 0, array $arrayofjs = [], array $arrayofcss = [], string $morequerystring = '', string $morecssonbody = '', string $replacemainareaby = '', int $disablenofollow = 0, int $disablenoindex = 0): void {}
function llxFooter(): void {}