# a2si/lib — librairies GeMa

Librairie PHP partagée par les applications GeMa : classes `iit_*` (authentification, droits, grilles jqGrid,
accès SQL, synchronisation des agents, exports PDF/Excel/Word/ODT, mails, etc.), plus quelques librairies tierces
embarquées et patchées.

## Prérequis

- PHP **8.2 ou plus** (testé en 8.4). Le code reste lisible par PHP 7.4, ce qui permet une bascule progressive.
- Extensions : `pdo_mysql`, `mysqli`, `mbstring`, `xml`/`dom`, `zip`, `gd`, `curl`, `openssl`, `fileinfo`.
- PEAR (`PEAR.php` dans l'`include_path`, paquet `php-pear`), utilisé par `Spreadsheet_Excel_Writer` (`iit_ExcelWriter`).
- Composer.

## Installation

```sh
composer install
```

`vendor/` n'est pas versionné. `composer.json` fixe la plateforme à PHP 8.2.0 : les dépendances résolues
s'installent donc sur tout serveur en 8.2 ou plus.

| Dépendance | Version | Utilisée par |
|---|---|---|
| `twig/twig` | ^3.27 | `iit_Twig` (rendu avec ou sans sandbox) |
| `dompdf/dompdf` | ^3.1 | `iit_DomPDF` |
| `nesbot/carbon` | ^2.72 | applications |

## Utilisation

L'application définit ses constantes de configuration, puis inclut la lib :

```php
require DIR_LIBRARY . 'functions.php'; // LogMessage(), SetPEARPath(), utilitaires de dates...
require DIR_LIBRARY . 'common.php';    // autoload iit_* / app_* / spe_*, session, locale
```

L'autoloader de `common.php` résout les classes ainsi :

- `iit_X` : `DIR_LIBRARY/class/iit_X.php`
- `app_X` : `DIR_INCLUDE/class/app_X.php`
- `spe_X_Y` : `DIR_DATA/specific/NAME_PROG/<application>/X/class/spe_X_Y.php`

`common.php` démarre la session, sauf si `NOSESSIONSTART` est défini. Il utilise aussi `define_if_not_defined()`,
que l'application doit fournir.

### Constantes attendues de l'application

En PHP 8, une constante non définie provoque une `Error` (en PHP 7, elle valait son propre nom). Selon les
fonctionnalités utilisées, l'application doit définir :

- **Application** : `NAME_PROG`, `TITLE`, `SSTIME` (durée de session, en secondes)
- **Chemins** : `DIR_LIBRARY`, `DIR_INCLUDE`, `DIR_DATA`, `DIR_TMP`, `DIR_ROOT`, `DIR_AGENT`, `DIR_LICENCE`
- **URL** : `ROOT_URL`, `LIB_URL`, `APPLI_URL` (optionnelle)
- **Base de données** : `SQL_SERVERNAME`, `SQL_USER`, `SQL_PWD`. `SQL_DATABASE` est défini par la lib après authentification.
- **Logs** : `LOG_TOFILE`, `LOG_TODB`, `LOG_BROWSER` (optionnelle)
- **Mail** : `USESMTP`, `MAIL_FROM`, `MAIL_HOST`, `MAIL_PORT`, `MAIL_USER`, `MAIL_MP`, `MAIL_REPLY_TO`,
  `MAIL_COPY` (optionnelle), `MAIL_HOSTNAME` (optionnelle)
- **Autres** : `SCREEN_PDA`, `SIZE_X` (images), `SYSTEM_USR_NAME`, `SYSTEM_USR_PWD` (tâches planifiées Windows)

Valeurs par défaut fournies par la lib : `DB_PREFIX` (= `NAME_PROG`), `LOCAL`, `DIR_PHP`, `DIR_MYSQL`,
`PWD_CRYPT` (`md5`), `MONITORING_MAIL_TO` (`support@a2si.net`).

## Contenu

```
admin.php, sendmail.php   points d'entrée (administration des applications, envoi de mails)
common.php, functions.php bootstrap et fonctions globales
class/iit_*.php           classes de la lib
class/smarty/             Smarty 3.0.7
class/PHPExcel/           PHPExcel 1.8
class/PhpWord/            PhpWord (seul le TemplateProcessor est réellement utilisé)
class/html2pdf/           html2pdf + TCPDF
class/odtphp/             odtphp (base de iit_odf)
class/PDF/, class/Spreadsheet/, class/When/, class/JWT/, class/FirePHPCore/, class/tree/
PEAR/                     OLE et Spreadsheet_Excel_Writer
templates/, views/, js/, css/, img/, smartyPlugins/
```

## Librairies embarquées et PHP 8

Les librairies tierces de `class/` et `PEAR/` ne sont plus maintenues. Elles ont été **patchées sur place** pour
PHP 8.2+, sans changement d'API. Ces fichiers ne doivent pas être remplacés par une version amont sans reporter
les correctifs :

- accès `$str{0}` → `$str[0]` ; `each()`, `create_function()`, modificateur `/e` remplacés ;
- constructeurs « PHP 4 » (méthode du nom de la classe) renommés en `__construct` ;
- `#[\AllowDynamicProperties]` sur les classes racines (et les classes `iit_*` racines ou héritant d'une classe externe) ;
- `#[\ReturnTypeWillChange]` sur les implémentations d'`Iterator`/`ArrayAccess`/PDO ;
- paramètres nullables explicites (PHP 8.4), casts `(int)` là où PHP 7 tronquait implicitement ;
- PhpWord : `Shared\String` → `Shared\WordString`, `Element\Object` → `Element\OLEObject` (`addObject()` reste disponible).

Points de comportement à connaître :

- `iit_SQLQuery` active `PDO::ATTR_STRINGIFY_FETCHES` : les valeurs reviennent en chaînes, comme avant PHP 8.1.
- Les connexions mysqli appellent `mysqli_report(MYSQLI_REPORT_OFF)` : le code teste les valeurs de retour.
- Les classes `app_*` qui surchargent `load()` ou `save()` d'`iit_JQGridInterface`/`iit_Main_Interface` doivent
  accepter au moins les paramètres du parent, sans en rendre de nouveaux obligatoires (sinon, erreur fatale en PHP 8).
- `strftime()` (plugins Smarty `date_format`, `html_select_date`…) est déprécié depuis PHP 8.1, mais fonctionne
  jusqu'à PHP 9.
- Les QR codes TCPDF utilisent un masque aléatoire (`QR_FIND_FROM_RANDOM`) : deux générations successives ne
  sont pas identiques octet par octet.
